@educa-corp/sdd-framework 0.6.0 → 0.7.1

package/commands/generate-bdd.tmpl

@@ -1,590 +0,0 @@
-# /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, **normalize khi chèn** (xem dưới), 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.
->
->   **Normalize — bắt buộc, nếu không scenario sẽ vô hình với trace:**
->   1. Gán `# @trace.scenario: {UC-ID}-SC{N}` với `{N}` = số SC **kế tiếp** trong file đó (thay placeholder `SC?`).
->   2. Giữ `# @trace.sc_version: 1.0`. Bổ sung `# @trace.business_rules` nếu proposal để `—` (suy từ AC mà dòng `# Covers:` trỏ tới); không suy được → để `—` và nêu trong report.
->   3. **Strip** tag `@proposed` / `@from-test` — chúng là nhãn vòng đời proposal, không thuộc BDD canonical.
->   4. Đặt scenario vào **đúng NHÓM** theo business theme (C.5), không nối vào cuối file.
->   5. **Append row TSV** cho SC mới (như nhánh "SC mới" ở Write Trace State: `spec_ver = 1.0`, mọi cột gen/test/qc = `—`, `status = UNTRACKED`).
->
->   **Backward-compat:** proposal cũ mang `@trace.uc=` / `@trace.ac=` (vocabulary trước đây, không thuộc contract `.feature`) → tự map sang canonical (`@trace.uc` bỏ — số UC đã có trong `sc_id`; `@trace.ac` → dòng `# Covers:`) và in một dòng cảnh báo khuyến nghị proposal sau viết theo format mới.
-> - `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` = path submodule đã phân giải (dạng phẳng), hoặc `"multi"` (dạng map-theo-platform ở cấp PRD — chưa chốt 1 platform), 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. Với `"multi"` + `service_candidates_kind = platform`, lấy module theo từng platform từ `service_candidates.{platform}.module` khi sinh `bdd/{platform}/` (context-loader đã làm phẳng các entry `by_prd_slug` nên luôn có `.module` trực tiếp).
-
-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 = "multi"` **và** `service_candidates_kind = platform` (domain map-theo-platform, target PRD chưa gắn 1 platform) | Tiếp tục — BDD là artifact liên team, platform-split. Sinh `bdd/{platform}/` cho các platform có trong `service_candidates`; từ vựng lấy theo `service_candidates.{platform}.module`. KHÔNG cần chốt 1 service. Platform nào bị đánh dấu `unresolved` trong candidates (thiếu `prd_slug` tương ứng dưới `by_prd_slug`) → vẫn sinh BDD nhưng gắn ⚠️ nêu rõ chưa có repo nhận. |
-| `active_service = "multi"` **và** `service_candidates_kind = prd_slug` | **DỪNG.** Candidates đang là map feature→repo, KHÔNG phải map platform — sinh `bdd/{slug}/` là sai bố cục. Yêu cầu người dùng chạy lại với target file cụ thể để `prd_slug` được xác định. |
-| `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. |
-
-### Phân giải `active_platform` (umbrella mode)
-
-Umbrella mode không hỏi platform (khác spec repo mode) — nó **suy** từ module của service. Bắt buộc phải có giá trị: `active_platform` đi vào **path file**, vào **header `@trace.platform`**, và vào **tên sổ trace** `{UC-ID}-{platform}.tsv`.
-
-| `active_module` | → `active_platform` |
-|---|---|
-| react · nextjs · vue · nuxt · angular | `web` |
-| flutter · react-native · ios-swiftui · android-compose | `app` |
-| java-spring · golang · dotnet · php-laravel | `system` |
-| context-engineering · phaser-game | theo `platform_type` của stack-profile (`backend` → `system`, còn lại → `web`) |
-
-- `active_service = "multi"` + `service_candidates_kind = platform` → **nhiều** `active_platform` (một cho mỗi platform trong `service_candidates`); sinh một file `.feature` cho mỗi platform, module lấy theo `service_candidates.{platform}.module`.
-- Không suy được (module lạ, không có trong bảng và không có `platform_type`) → **DỪNG**, hỏi người dùng chọn `web`/`app`/`system`. **KHÔNG** ghi file khi chưa có `active_platform` — file thiếu platform sẽ vô hình với `/validate-traces` và va chạm tên với platform khác.
-
-**Output path (umbrella mode):** `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{TICKET-ID}-UC{N}-{slug}.feature`
-
-*(**Subfolder `{platform}/` LUÔN có — mọi mode.** `web` và `system` của cùng một UC là hai file khác nhau: nếu bỏ subfolder, chúng ra cùng filename và **ghi đè nhau**; ngoài ra trace tách theo platform (`{UC-ID}-{platform}.tsv`) nên bố cục spec phải tách tương ứng.*
-*Cái KHÔNG thêm là subfolder theo **service**: feature-package đã domain-scoped sẵn ở `{domain}/`, mà service route 1-1 theo domain — thêm subfolder service 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. Search path (**giống nhau ở cả hai mode** — bố cục `bdd/{platform}/` là chuẩn duy nhất):
-   `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{TICKET-ID}-UC*.feature`
-   > **Legacy:** nếu không khớp gì, thử thêm một lần ở bố cục phẳng cũ `…/bdd/{TICKET-ID}-UC*.feature`. Khớp → xử lý như file có sẵn **và** in cảnh báo: `⚠️ File .feature đang ở bố cục phẳng (trước v0.4.1). Chạy: npx sdd-framework --migrate-bdd-platform để chuyển sang bdd/{platform}/.` Đừng tự di chuyển file trong lệnh này.
-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 **thuộc UC này** (đúng tập ở `**AC liên quan:**` của UC trong PRD §3) và mỗi BR trong bảng Business Rule của UC này map tới ≥1 SC. **KHÔNG** phủ AC của UC khác — đó là việc của `.feature` UC đó. *(AC ở PRD là global cấp PRD, còn `.feature` là per-UC; enforce theo nghĩa "mọi AC của PRD" sẽ bắt AI bịa scenario ngoài scope hoặc báo MISSING giả.)* |
-| 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 — MỘT bố cục duy nhất cho cả hai mode:**
-
-```
-{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{TICKET-ID}-UC{N}-{slug}.feature
-```
-
-`{active_platform}` ∈ `web` | `app` | `system` — từ Platform Selection (spec repo mode) hoặc suy từ `active_module` (umbrella mode, xem §Service Detection). **Không có `active_platform` thì không ghi file.**
-
-Với mỗi UC, ghi vào path trên và set `# @trace.platform: {active_platform}` trong header (**bắt buộc, mọi mode** — `/generate-code` dùng nó để quyết BE/FE và để định vị sổ trace; `/generate-tech-docs` và `context-loader` cũng đọc nó). Dùng từ vựng cho active platform.
-
-```gherkin
-{{include:templates/feature.template}}
-```
-
-> **Template này đến từ đâu — đọc trước khi định "customize":**
-> Skeleton trên là **single-source** ở `templates/feature.template` **của repo framework**, được `{{include}}` **nướng cứng vào lệnh này lúc `npm run build`**. Muốn đổi cấu trúc mọi `.feature` sinh ra: sửa file đó **trong repo framework** rồi build lại + phát hành.
->
-> **Sửa `.agent/templates/feature.template` trong project KHÔNG có tác dụng** — không lệnh nào đọc file đó; nó chỉ là bản tham khảo. Và nó **sẽ bị ghi đè im lặng** ở lần `/update-framework` kế tiếp (`--init` copy `core/` → `.agent/` vô điều kiện; file duy nhất được giữ là `.agent/project-context.yaml`).
->
-> Coverage Matrix + Pre-merge Checklist nằm ở **cuối** template, thêm vào cuối mỗi file.
-
-### Bump `@trace.sc_version` *(CHỈ khi gen lại — file `.feature` đã tồn tại)*
-
-*Bỏ qua hoàn toàn khi gen mới: mọi SC nhận `1.0`.*
-
-`@trace.sc_version` là version **của từng scenario** — nó là tín hiệu DUY NHẤT cho `/validate-traces` biết code của SC đó đã lỗi thời (`spec_ver != gen_ver` → `DRIFT`). Không bump = code sinh từ scenario cũ mãi mãi hiện `OK`. Phân biệt với `@trace.bdd_version` (version **cả file**, không đủ phân giải để biết SC nào cần regen).
-
-Trước khi ghi file, với **mỗi** SC, so **thân scenario** bản mới vs bản trên disk theo 4 thành phần:
-
-1. dòng `Scenario:` (tên)
-2. chuỗi step `Given` / `When` / `Then` / `And` (nội dung + thứ tự)
-3. nội dung data table (nếu có)
-4. dòng `# Side-effects:`
-
-| Kết quả so | Hành động |
-|---|---|
-| Khác ở **bất kỳ** thành phần nào | `@trace.sc_version` += `0.1` (vd `1.0` → `1.1`) |
-| Giống hoàn toàn | **GIỮ NGUYÊN** — bump vô cớ sẽ tạo `DRIFT` giả, làm cờ mất giá trị |
-| SC mới (chưa có trong bản cũ) | `1.0` |
-
-*(Thay đổi ngoài 4 thành phần trên — `@trace.business_rules`, tag `@happy`/`@edge`, comment — KHÔNG bump: chúng không đổi hành vi mà code phải implement.)*
-
-In danh sách SC được bump vào report cuối để người dùng biết cái nào sẽ hiện `DRIFT`.
-
----
-
-## 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\tservice\tdesign_spec_version
-```
-
-**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`, `service`, `design_spec_version`, `last_updated`. Giữ nguyên các cột khác. *(`service` + `design_spec_version` là sự thật cấp-file, làm mới theo `.feature`/design-spec hiện tại — chúng KHÔNG phải tín hiệu nghiệm thu nên làm mới chúng không che giấu gì.)*
-  - 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`, `service`, `design_spec_version`, `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`.
-    **VÀ hạ hiệu lực tín hiệu kiểm thử của đúng SC đó** — spec vừa đổi nên test/QC cũ đang nghiệm thu một hành vi **không còn tồn tại**:
-    `dev_selftest → not_run` · `dev_selftest_at → —` · `qc_status → not_run` · `qc_run_at → —`.
-    > **Vì sao bắt buộc** *(luật "Làm mất hiệu lực ≠ ghi đè", `rules/workflow.md`)*: không hạ thì chuỗi sau báo xanh sai — spec đổi → `DRIFT` → `/generate-code` sửa method → `gen_ver = spec_ver` → `/validate-traces` Rule 4 cho `OK` (vì `test_count` vẫn > 0) → dashboard hiện `OK · ✅ 10 tests · qc pass` trong khi hành vi mới **chưa được test lần nào**. Đây là lớp lỗi nguy hiểm hơn G1: G1 làm cờ im lặng, cái này làm cờ **nói dối**.
-    > **KHÔNG** đụng `test_count`/`test_classes` (test vẫn nằm trên đĩa — số lượng không sai, chỉ nội dung cũ; hạ số sẽ làm tỷ lệ coverage nhảy loạn) và **KHÔNG** đụng `qc_owner`/`qc_blocked_by` (con trỏ tới bug — spec đổi không làm bug biến mất).
-    In cảnh báo kèm: `⚠️ {test_count} test của {sc_id} viết cho spec cũ — /dev-gen-test rà lại trước khi chạy`.
-  - 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á / gộp / đổi số) → **phụ thuộc SC đó đã có code chưa:**
-    - `implemented_by == —` (**chưa** có code) → **xoá row**. Không có gì mồ côi.
-    - `implemented_by != —` (**ĐÃ** có code) → **GIỮ row**, set `status = ORPHANED`, giữ nguyên `implemented_by` / `test_count` / `test_classes` / các cột qc, cập nhật `last_updated`. **KHÔNG xoá** — xoá row thì method đó thành vô hình: không `UNTRACKED`, không `GAP`, không `DRIFT`, không xuất hiện ở report nào, mà vẫn nằm trong code và vẫn được caller gọi. Coverage còn *đẹp hơn* thực tế vì mẫu số nhỏ đi.
-      In cảnh báo nổi bật ở report cuối:
-      ```
-      ⚠️  ORPHANED — {UC-ID}-SC{N} "{sc_title}" đã bị xoá khỏi .feature nhưng còn code:
-           {implemented_by}  (+ {test_count} test: {test_classes})
-         Không tự hết — chọn MỘT:
-           (a) behavior không còn cần → xoá method + test, rồi xoá row khỏi .tsv
-           (b) SC bị xoá do nhầm      → đưa scenario trở lại .feature (row về DRIFT/OK bình thường)
-         (/validate-traces giữ cờ ORPHANED 🔴 và chặn "pass" tới khi xử lý xong.)
-      ```
-    *(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` |
-| `service` | `@trace.service` từ header `.feature` — đội/submodule sở hữu scenario này. `multi` nếu chưa chốt (map-theo-platform ở cấp PRD), `unresolved` nếu domain không khớp entry nào, `—` ở single-service mode. **Đừng bỏ trống** — trace gộp không tách theo service nên đây là chỗ DUY NHẤT mang thông tin sở hữu ở cấp row. |
-| `design_spec_version` | `\| **Version** \|` của design-spec đã nạp ở §Design Spec — Gate & Load. `—` cho `system`/backend (không có design-spec), và `—` khi người dùng chọn "Y — vẫn sinh BDD" mà không có design-spec. |
-
-## 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} · platform: {active_platform} (suy từ module {active_module})]
-Files:
-  {paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{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}
-
-{chỉ khi gen lại VÀ có ≥1 SC bị bump — ngược lại bỏ cả khối}
-🔄 sc_version đã bump (scenario đổi nội dung → code cũ lỗi thời):
-  {UC-ID}-SC2  1.0 → 1.1   {sc_title}
-  {UC-ID}-SC5  1.2 → 1.3   {sc_title}
-  → {n} SC này sẽ hiện DRIFT ở /validate-traces. Sinh lại code: /generate-code {feature-file}
-
-{cùng điều kiện — chỉ in các SC bump mà TRƯỚC ĐÓ có dev_selftest/qc_status khác "—"}
-🔻 Tín hiệu kiểm thử bị hạ (spec vừa đổi — nghiệm thu cũ hết hiệu lực):
-  {UC-ID}-SC2  dev_selftest pass→not_run · qc_status pass→not_run
-  ⚠️  {n} test của các SC này viết cho spec CŨ — rà lại nội dung, đừng chỉ chạy lại.
-  → sau khi /generate-code: /dev-gen-test (rà test) → /dev-run-test → QC /qc-run-test
-  ℹ️  Coverage "đã kiểm đạt" sẽ TỤT trên dashboard — đó là số đúng; số cũ mới là số sai.
-     (Tỷ lệ phủ code/test KHÔNG đổi — test_count giữ nguyên vì test vẫn nằm trên đĩa.)
-
-📊 Living Docs: chạy /validate-traces (hoặc /sync) để push trace này lên dashboard spec-module.
-```