@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.1

package/commands/generate-bdd.tmpl

@@ -1,4 +1,4 @@
-# /generate-bdd — Generate BDD Feature Files
+# /generate-bdd — Sinh BDD Feature Files
 
 ## Gate
 {{include:steps/gate.md}}
@@ -6,57 +6,57 @@
 ## Context
 {{include:steps/context-loader.md}}
 
-> **Tester proposals (optional input):** before generating, check `{paths.bdd_proposals_dir}/` (default `{spec_source}/feedback/bdd-proposals/`) for scenarios proposed by testers via `/propose-scenario` that map to this UC's ACs. Incorporate any the PO/Dev has accepted — then the tester's draft is removed/archived from `feedback/`. Skip if the folder is empty.
+> **Proposal của tester (input tuỳ chọn):** trước khi sinh, kiểm tra `{paths.bdd_proposals_dir}/` (mặc định `{spec_source}/feedback/bdd-proposals/`) tìm các scenario mà tester đề xuất qua `/propose-scenario` ứng với AC của UC này. Đưa vào những cái PO/Dev đã chấp nhận — rồi draft của tester được xoá/lưu trữ khỏi `feedback/`. Bỏ qua nếu folder rỗng.
 
 ---
 
-## Repo Mode Detection
+## Phát hiện Repo Mode
 
-After loading context, determine which mode to operate in:
+Sau khi nạp context, xác định chế độ hoạt động:
 
-- **Spec repo mode**: `project-context.yaml` has NO `services` section OR `setup.mode: spec`
-- **Umbrella mode**: `project-context.yaml` HAS `services` section AND `setup.mode: umbrella`
+- **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 → proceed to **Platform Selection** below (skip Service Detection)
-→ Umbrella mode → proceed to **Service Detection** below (skip Platform Selection)
+→ 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 (Spec Repo Mode Only)
+## Platform Selection (chỉ Spec Repo Mode)
 
-*Skip this section if running in umbrella mode.*
+*Bỏ qua section này nếu đang chạy umbrella mode.*
 
-Ask the user to select the target platform:
+Hỏi người dùng chọn platform target:
 
 ```
-Which platform is this BDD for?
+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 (synthesized from existing web + app BDDs)
+  3. system — System/BE BDD (tổng hợp từ web + app BDD có sẵn)
 ```
 
-Wait for user selection. Set `active_platform` = chosen value.
+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`
 
-**Platform vocabulary:**
+**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 — use business events | — | "the system returns" / "receives response" | — |
+| system | N/A — dùng business event | — | "the system returns" / "receives response" | — |
 
 ---
 
 ## System BDD Synthesis (active_platform = system)
 
-*Only applies when platform = system. Skip for web and app.*
+*Chỉ áp dụng khi platform = system. Bỏ qua với web và app.*
 
 ### Step S0 — Brownfield Check
 
-Check the source PRD Metadata table for `| **API Source** | existing |`.
+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.
@@ -69,47 +69,47 @@ Check the source PRD Metadata table for `| **API Source** | existing |`.
 
 ---
 
-### Step S1 — Scan available FE/App BDDs
+### Step S1 — Scan các BDD FE/App có sẵn
 
-Search for existing BDDs for this TICKET-ID:
-- Web BDDs: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/web/{TICKET-ID}-*.feature`
-- App BDDs: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/app/{TICKET-ID}-*.feature`
+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`
 
-Classify the feature:
+Phân loại feature:
 
-| Condition | Mode |
+| Điều kiện | Mode |
 |---|---|
-| Both web + app BDDs found | **Multi-platform** — synthesize from both |
-| Only web BDD found | **Web-only** — synthesize from web |
-| Only app BDD found | **App-only** — synthesize from app |
-| No FE/App BDDs found | **Backend-only** — gen directly from PRD |
+| 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 — Extract expected contracts per platform
+### Step S2 — Trích contract kỳ vọng theo từng platform
 
-For each found BDD file, extract:
-- **Triggers**: what user actions call the backend? (map to logical "request" events)
-- **Expected response data**: what fields/shape does each `Then` clause need from the system?
-- **Error signals**: what error states must the backend signal?
-- **Business rules**: what invariants does each platform assume the system enforces?
+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 (multi-platform mode only)
+### Step S3 — Cross-Platform Conflict Check (chỉ multi-platform mode)
 
-*Skip if web-only, app-only, or backend-only.*
+*Bỏ qua nếu web-only, app-only, hoặc backend-only.*
 
-Compare the extracted contracts across platforms. Flag a conflict if any of these differ:
+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:
 
-| Conflict type | Example |
+| Loại conflict | Ví dụ |
 |---|---|
-| **Response shape mismatch** | Web expects `{ token, redirect_url }`, App expects `{ token, user_profile }` |
-| **Error semantics mismatch** | Web expects HTTP 423 for lock, App expects custom error code `ACC_LOCKED` |
-| **Business rule contradiction** | Web BDD says "lock after 5 attempts", App BDD says "lock after 3 attempts" |
-| **Data field conflict** | Web expects `expires_in: seconds`, App expects `expires_at: ISO timestamp` |
+| **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` |
 
-**If conflicts detected → CHECKPOINT (mandatory, cannot skip):**
+**Nếu phát hiện conflict → CHECKPOINT (bắt buộc, không bỏ qua được):**
 
 ```
 ⚠️  CROSS-PLATFORM CONTRACT CONFLICT
@@ -122,103 +122,103 @@ Conflict 1: Response shape mismatch
 
 Resolution options:
   A — Union response
-      BE returns all fields: { token, redirect_url, user_profile }
-      Clients ignore fields they don't use. Simple, slight over-fetch.
-  B — Platform hint in request
-      Client sends X-Platform: web|app in header, BE tailors response.
-      Cleaner responses, more BE logic.
-  C — Separate endpoints
-      POST /auth/login/web  and  POST /auth/login/app
-      Maximum flexibility, more endpoints to maintain.
-  D — Custom: describe your approach
+      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
 ──────────────────────────────────────────────────────────────────
-Choose resolution for each conflict (A/B/C/D):
+Chọn resolution cho mỗi conflict (A/B/C/D):
 ```
 
-Wait for PO's resolution per conflict. Record each decision as a `# @system.resolution:` annotation in the generated system BDD file.
+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.
 
-**If no conflicts → proceed to Step S4 directly.**
+**Nếu không có conflict → tới Step S4 trực tiếp.**
 
 ---
 
-### Step S4 — Generate System BDD scenarios
+### Step S4 — Sinh các scenario System BDD
 
-Generate scenarios based on mode and resolved conflicts:
+Sinh scenario dựa trên mode và các conflict đã giải quyết:
 
-- **Multi-platform**: synthesize from both web + app contracts, applying resolved resolutions
-- **Web-only / App-only**: derive from the single platform's contracts
-- **Backend-only**: derive directly from PRD AC/BR using business event language (not HTTP)
+- **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)
 
-System BDD step vocabulary (always use — regardless of FE/App vocabulary):
+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}"
-- Do NOT use UI words (click, tap, see, navigate) in system BDD
+- KHÔNG dùng từ UI (click, tap, see, navigate) trong system BDD
 
-**If multi-platform with resolution A (union):**
-- System BDD shows the full response contract: all fields from all platforms
-- Add comment: `# @system.resolution: union — clients receive all fields`
+**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`
 
-**If resolution B (platform hint):**
-- Write separate `Scenario Outline` using Examples table for `web` vs `app` response variants
-- Add comment: `# @system.resolution: platform-hint — X-Platform header determines response shape`
+**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`
 
-**If resolution C (separate endpoints):**
-- Write separate Scenarios for each endpoint
-- Note the endpoint split explicitly in the SCOPE section
+**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 (Umbrella Mode Only)
+## Service Detection (chỉ Umbrella Mode)
 
-*Skip this section if running in spec repo mode.*
+*Bỏ qua section này nếu đang chạy spec repo mode.*
 
-Read the PRD Metadata table for `| **Service** |` and `| **Module** |` rows.
+Đọc bảng Metadata của PRD tìm row `| **Service** |` và `| **Module** |`.
 
-| Condition | Action |
+| Điều kiện | Hành động |
 |---|---|
-| PRD has `Service` row AND value is not "default" | Use it as `active_service` + `active_module`. Load catalog for that module. |
-| PRD has no `Service` row AND `services` defined in project-context.yaml | Ask: "Which service is this BDD for?" (list services, wait for selection) |
-| Single-service project (no `services` array) | `active_service = "default"`, `active_module = tech_stack.module` |
+| PRD có row `Service` VÀ giá trị không phải "default" | Dùng làm `active_service` + `active_module`. Nạp catalog cho module đó. |
+| PRD không có row `Service` VÀ `services` được định nghĩa trong project-context.yaml | Hỏi: "BDD này dành cho service nào?" (liệt kê service, chờ chọn) |
+| Dự án single-service (không có mảng `services`) | `active_service = "default"`, `active_module = tech_stack.module` |
 
 **Output path (umbrella mode):**
 - `active_service = "default"` → `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC{N}-{slug}.feature`
 - `active_service ≠ "default"` → `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_service}/{TICKET-ID}-UC{N}-{slug}.feature`
 
-**Platform vocabulary** — adapt BDD step wording based on `active_module`:
+**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 | *(no UI steps — use)* "submits a request" / "calls the API" | — | "receives response" / "the system returns" | — |
+| 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" | — |
 
-Apply this vocabulary silently when writing Gherkin steps. Do NOT mix web and mobile terms in the same feature file.
+Á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.
 
 ---
 
 ## Orchestration Check
 
-*Skip this section if already in sub-agent mode (Step 0 of Gate was triggered).*
+*Bỏ qua section này nếu đã ở sub-agent mode (Step 0 của Gate đã kích hoạt).*
 
-After loading context, check if the target PRD is large enough to warrant sub-agents:
+Sau khi nạp context, kiểm tra PRD target có đủ lớn để cần sub-agent không:
 
-1. Count `#### {TICKET-ID}-UC` headings in the PRD → **UC count**.
-2. Count total lines in the PRD → **line count**.
-3. If **UC count > 3** OR **line count > 300**:
-   - Switch to orchestration mode — follow `steps/spawn-agent.md`.
-   - The main session becomes the orchestrator: spawn 1 sub-agent per UC.
-   - Each sub-agent runs `/generate-bdd` with `_agent_mode: true` payload.
-   - Collect results and show merged report.
-   - **Do NOT continue with the steps below.**
-4. If UC count ≤ 3 AND line count ≤ 300 → continue with Version Check below (single-session mode).
+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
 
-*This section applies when running as a sub-agent (Gate Step 0 detected `_agent_mode: true`).*
+*Section này áp dụng khi chạy như sub-agent (Gate Step 0 phát hiện `_agent_mode: true`).*
 
-After generating all `.feature` and `.tsv` files for the assigned UC, return the structured result JSON (as specified in `steps/spawn-agent.md` Step E):
+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": [] }
@@ -228,83 +228,83 @@ After generating all `.feature` and `.tsv` files for the assigned UC, return the
 
 ## Version Check
 
-Before generating, check for existing `.feature` files for this PRD:
+Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 
-1. Resolve the search path based on mode:
+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` (or with `{active_service}/` if multi-service)
-2. Read current PRD `| **Version** |` from metadata (e.g., `1.2`).
-
-**If no existing feature files** → fresh generation, proceed normally. Use PRD version as `@trace.prd_version`.
-
-**If existing feature files found**:
-- Read `# @trace.prd_version:` from the existing feature file header.
-- Compare with current PRD version.
-- If **same** → ask: "BDD already generated from PRD v{version}. Regenerate? (Y/N)"
-- If **different** (PRD was updated):
-  1. Read `## Changelog` from the PRD — extract all rows newer than the existing BDD's `@trace.prd_version`.
-  2. Show CHECKPOINT:
+   - **Umbrella mode**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC*.feature` (hoặc với `{active_service}/` nếu multi-service)
+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 `## Changelog` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có.
+  2. Hiện CHECKPOINT:
      ```
-     ⚠️  PRD version drift detected
-     BDD was generated from PRD v{old}
-     PRD is now at v{new}
+     ⚠️  Phát hiện PRD version drift
+     BDD được sinh từ PRD v{old}
+     PRD giờ ở v{new}
 
-     Changes since v{old}:
+     Thay đổi kể từ v{old}:
        {changelog rows}
 
      Options:
-       Y — update only affected scenarios
-       F — full regeneration of all scenarios
-       N — cancel
+       Y — chỉ cập nhật các scenario bị ảnh hưởng
+       F — gen lại toàn bộ scenario
+       N — huỷ
      ```
-  3. Proceed based on user choice.
+  3. Tiếp tục theo lựa chọn của người dùng.
 
 ---
 
-## BDD Writing Rules (R1-R10 — enforce strictly)
+## BDD Writing Rules (R1-R10 — enforce nghiêm)
 
-| Rule | Name | Requirement |
+| Rule | Name | Yêu cầu |
 |------|------|-------------|
-| R1 | Given/When/Then Semantics | Given=state, When=action, Then=outcome. Every SC needs full G/W/T. |
-| R2 | One Behavior Per Scenario | 1 SC = 1 behavior. Do NOT chain When→Then→When→Then. |
-| R3 | Ubiquitous Language | Do NOT use UI selectors / API names / tech terms in steps. |
-| R4 | Outside-in Naming | SC name describes business outcome. No "click" / "(Case X)" / component names. |
-| R5 | Declarative over Imperative | Describe WHAT (business intent), NOT HOW (UI mechanic). |
-| R6 | Observable Outcomes Only | Then asserts observable outcome. Not UI intermediate state / internal state. |
-| R7 | Key Examples / Concrete | Use concrete values. Not vague "valid data". |
-| R8 | Independence | SC runs independently. Does not depend on state from another SC. |
-| R9 | Test Data Completeness | Data table has enough fields to derive expected Then. |
-| R10 | Scope Boundary Explicit | Cross-UC reference uses navigation wording + Note comment. |
-
-## Project Compliance (fail review if missing — C.1-C.5)
+| 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 | Every component/action in Wireframe has ≥1 SC. |
-| C.2 PRD Traceability | Every AC and every BR (including each logic bullet) maps to ≥1 SC. |
-| C.3 Business Dictionary | Use correct canonical terms from business-dictionary.md. |
-| C.4 Banned Terms | 0 banned terms in file — grep before generating. |
-| C.5 NHÓM Grouping | Feature ≥3 SCs → MUST have NHÓM grouping by business theme. |
+| C.1 Wireframe Coverage | Mỗi component/action trong Wireframe có ≥1 SC. |
+| 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 — mandatory for ≥3 scenarios)
+## NHÓM Grouping Convention (C.5 — bắt buộc cho ≥3 scenario)
 
-Group by business theme, NOT by happy/negative/edge.
+Gom theo business theme, KHÔNG theo happy/negative/edge.
 
-Format header (indent 2 spaces, same level as Background):
+Format header (thụt 2 space, cùng cấp với Background):
 ```
   # ==========================================================
-  # NHÓM N: <Business theme> (<BR refs if applicable>)
+  # NHÓM N: <Business theme> (<BR refs nếu áp dụng>)
   # ==========================================================
 ```
 
 Rules:
-- Number sequentially NHÓM 1 → N. SC IDs sequential across lifecycle (do not reset per NHÓM).
-- Each NHÓM can contain @happy + @edge + @negative of the same theme.
-- SCs in NHÓM do not need to be in ID order (NHÓM 2 can contain SC4, SC8, SC11 if same theme).
+- Đá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).
 
-Suggested patterns (adjust per UC):
+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`
@@ -316,7 +316,7 @@ Suggested patterns (adjust per UC):
 
 ## UC Decomposition
 
-For each UC in the PRD, present the SC outline **before generating**:
+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)
@@ -329,52 +329,52 @@ For each UC in the PRD, present the SC outline **before generating**:
   BRs covered: {TICKET-ID}-UC1-BR1, BR2, BR3
 ```
 
-CHECKPOINT: "Does this outline look correct? Do you want to add or remove any SCs?" → **Wait for confirm before generating.**
+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 by mode:**
+**Output path theo mode:**
 - **Spec repo mode**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{TICKET-ID}-UC{N}-{slug}.feature`
 - **Umbrella mode (single-service)**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC{N}-{slug}.feature`
 - **Umbrella mode (multi-service)**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_service}/{TICKET-ID}-UC{N}-{slug}.feature`
 
-For each UC, write to the resolved path above. Use vocabulary for the active platform (from Platform Selection or Service Detection).
+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
 # ============================================================
 # @trace.id: {TICKET-ID}-UC{N}
 # @trace.title: <Feature name>
-# @trace.revision: 1  ← static field; use @trace.bdd_version for version tracking (incremented by /review-context --fix or --resume)
+# @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 | (omit in umbrella mode)}
-# @trace.service: {active_service — omit in spec repo mode}
-# @trace.module: {active_module in umbrella mode; "unknown" in spec repo mode}
+# @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: {read from PRD metadata "| **Version** |"}
-# @trace.bdd_version: {1.0 if fresh generation; increment by 0.1 on re-generation — e.g. 1.0 → 1.1}
+# @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
 # ============================================================
 
 # === CONTEXT ===
-# Actor:     <role performing the action, e.g., Consumer, Staff, System>
-# Screens:   <related screens, e.g., Cart → Confirm Order → Order Detail>
-# Entities:  <business entities, e.g., Order, OrderItem, Consumer>
-# Pre-state: <shared state before entering scenarios>
+# 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:  <business entity, vd: Order, OrderItem, Consumer>
+# Pre-state: <state dùng chung trước khi vào các scenario>
 
 # === SCOPE ===
-# In:  <what this UC covers>
-# Out: <what is NOT in this UC — link to other UC/feature (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 ===
-# Quick reference for terms used in this feature. SoT details: business-dictionary.md
-# <Term 1>: <short definition>
-# <Term 2>: <short 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>
 
 Feature: <Feature name>
   As a <role>
@@ -382,29 +382,29 @@ Feature: <Feature name>
   So that <business value>
 
   Background:
-    Given <shared precondition — use aliases from dataset, not technical IDs>
+    Given <precondition dùng chung — dùng alias từ dataset, không phải ID kỹ thuật>
 
   # ==========================================================
   # NHÓM 1: <Business theme> (<BR refs>)
   # ==========================================================
 
-  # Side-effects: <list brief Then side-effects to verify>
+  # 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}-BR1
   @happy
-  Scenario: <describe business outcome — use precise verb: create/receive/assign/block>
-    Given <input state — alias from dataset>
+  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 declared in header>
+      And <side-effect 1 khai báo trong header>
 
   # Side-effects: <...>
   # @trace.scenario: {TICKET-ID}-UC{N}-SC2
   # @trace.sc_version: 1.0
   # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
   @happy @alternative
-  Scenario: <same NHÓM 1 theme but different path — e.g., different enum value>
+  Scenario: <cùng theme NHÓM 1 nhưng path khác — vd: giá trị enum khác>
     Given <state>
     When <action>
     Then <outcome>
@@ -418,85 +418,85 @@ Feature: <Feature name>
   # @trace.sc_version: 1.0
   # @trace.business_rules: {TICKET-ID}-UC{N}-BR2
   @edge
-  Scenario: <boundary / error scenario>
+  Scenario: <scenario boundary / error>
     Given <state>
     When <action>
     Then <expected error handling>
 ```
 
-### Coverage Matrix & Pre-merge Checklist *(appended to end of each file)*
+### Coverage Matrix & Pre-merge Checklist *(thêm vào cuối mỗi file)*
 
 ```gherkin
 # === PRD COVERAGE (C.1 + C.2) ===
 # AC mapping:
 #   AC1 (...) → SC1, SC2
 #   AC2 (...) → SC3
-# BR mapping (each bullet MUST have ≥1 SC — C.2):
+# 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 (every component/action ≥1 SC — C.1):
+# 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
 
 # === PRE-MERGE CHECKLIST ===
-# - [ ] Every SC has Side-effects + @trace.scenario + @trace.sc_version + @trace.business_rules
-# - [ ] Coverage Matrix: 0 MISSING lines (C.1)
-# - [ ] Every AC/BR maps to ≥1 SC (C.2)
-# - [ ] 0 banned terms (C.4) — grep file before merging
-# - [ ] Feature ≥3 SCs has NHÓM grouping by business theme (C.5)
-# - [ ] If popup/modal: Popup/Modal Lifecycle declared in BUSINESS DEFINITION
-# - [ ] If display logic ≥2 dimensions: Display Logic Matrix in BUSINESS DEFINITION
+# - [ ] Mỗi SC có Side-effects + @trace.scenario + @trace.sc_version + @trace.business_rules
+# - [ ] Coverage Matrix: 0 dòng MISSING (C.1)
+# - [ ] 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
 ```
 
 ---
 
 ## Write Trace State
 
-After generating all `.feature` files, create or update `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` for each UC.
+Sau khi sinh tất cả file `.feature`, tạo hoặc cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` cho mỗi UC.
 
-> **Umbrella + `spec_source`:** both the `.feature` files **and** the trace `.tsv` write to the **spec repo** (`{spec_source}/specs/{domain}/{prd-slug}/bdd/…` and `{spec_source}/.trace/{domain}/{prd-slug}/…`, resolved by context-loader) — a **single-repo** write, committed/pushed to the spec submodule. (Trace is consolidated in the spec repo so the PM manages all status in one place; code-side commands update it cross-repo later.)
+> **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.)
 
-**TSV columns (tab-separated, one header row + one data row per scenario):**
+**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:**
-- If file does not exist → create with header row + all scenario rows.
-- If file exists (re-generation) → for each SC in the new `.feature`:
-  - SC already in `.tsv` AND `spec_ver` is unchanged → update only: `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Leave all other columns unchanged.
-  - SC already in `.tsv` AND `spec_ver` changed (scenario was modified) → update: `sc_title`, `spec_ver`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated` AND set `status = DRIFT` immediately (so the TSV reflects drift without waiting for `/validate-traces`). Leave `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision`, `fe_tech_doc_revision` unchanged.
-  - SC is new (added in this re-gen) → append new row with `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` all set to `—`.
-  - SC no longer in `.feature` (removed) → delete its row.
+- 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ó.
 
-**Values to write for each scenario:**
+**Giá trị ghi cho mỗi scenario:**
 
-| Column | Value |
+| Cột | Giá trị |
 |--------|-------|
 | `sc_id` | `{UC-ID}-SC{N}` |
-| `sc_title` | scenario title text |
-| `spec_ver` | `@trace.sc_version` of this scenario |
-| `gen_ver` | `—` (not yet generated) |
+| `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` | `—` (no tests run yet) |
+| `dev_selftest` | `—` (chưa chạy test) |
 | `dev_selftest_at` | `—` |
-| `qc_status` | `—` (official QC automation result — set by `/qc-run-test`) |
+| `qc_status` | `—` (kết quả QC automation chính thức — set bởi `/qc-run-test`) |
 | `qc_run_at` | `—` |
-| `qc_owner` | `—` (who a non-passing SC waits on: `dev` / `po` — set by `/qc-run-test` + `/report-bug`) |
-| `qc_blocked_by` | `—` (linked `BUG-{id}` / `GAP-{id}` — set by `/qc-run-test` + `/report-bug`) |
-| `prd_version` | `@trace.prd_version` from `.feature` header |
-| `bdd_version` | `@trace.bdd_version` from `.feature` header |
-| `tech_doc_revision` | `—` (BE API contract revision — set by `/generate-code` + `/review-tech-docs`) |
-| `fe_tech_doc_revision` | `—` (FE client tech-design revision `{UC-ID}-tech-design-{platform}.md` — set by `/generate-code --phase=integration` + `/review-tech-docs` on an FE doc) |
-| `prd_status` | read `\| **Status** \|` from PRD metadata |
-| `uc_status` | `draft` for new UCs; keep existing value for re-gen |
-| `fe_phase` | `—` (set by `/generate-code --phase` when FE implements) |
+| `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 API contract BE — set bởi `/generate-code` + `/review-tech-docs`) |
+| `fe_tech_doc_revision` | `—` (revision FE client tech-design `{UC-ID}-tech-design-{platform}.md` — set bởi `/generate-code --phase=integration` + `/review-tech-docs` trên doc FE) |
+| `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` | today `YYYY-MM-DD` |
+| `last_updated` | hôm nay `YYYY-MM-DD` |
 
 ## Refresh Panel Mirror
 {{include:steps/trace-mirror.md}}
@@ -506,7 +506,7 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tde
 {{include:steps/report-footer.md}}
 
 ```
-/generate-bdd Complete
+/generate-bdd Hoàn tất
 
 [Spec repo mode — platform: {active_platform}]
 Files:
@@ -516,9 +516,9 @@ Trace:
   {paths.trace_dir}/{domain}/{prd-slug}/{TICKET-ID}-UC1.tsv ({N} rows)
   {paths.trace_dir}/{domain}/{prd-slug}/{TICKET-ID}-UC2.tsv ({N} rows)
 Next (spec repo):
-  → Run /generate-bdd again for other platforms (web → app → system)
-  → After all platforms generated: commit + push + notify dev team
-  → Dev team reads BDD from spec submodule — no /generate-bdd on their side
+  → 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:
@@ -526,9 +526,9 @@ Files:
 Trace:
   {paths.trace_dir}/{domain}/{prd-slug}/{TICKET-ID}-UC1.tsv ({N} rows)
 Next (umbrella):
-  → /review-context {feature-file} to verify coverage
+  → /review-context {feature-file} để kiểm tra coverage
   → /generate-tech-docs {feature-file}
   → /generate-code {feature-file}
 
-📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
+📊 Living Docs: chạy /validate-traces (hoặc /sync) để push trace này lên dashboard spec-module.
 ```