@educa-corp/sdd-framework 0.3.0 → 0.4.2

package/core/commands/generate-bdd.md

@@ -32,23 +32,23 @@ Hiển thị và chờ phản hồi:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4 (hoặc model Opus mới nhất)
+  Recommended  : model Opus mới nhất
   Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
-                 suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case.
+                 suy luận sâu. Model nhỏ hơn (Haiku/Sonnet) dễ bỏ sót edge case.
 
   Cách đổi trong Claude Code:
-    • Settings → Model → chọn "claude-opus"
-    • hoặc: /model → chọn claude-opus
+    • /model → chọn model Opus
+    • hoặc: Settings → Model
 
-  Đang chạy claude-opus?
-    Y — đúng, đang dùng claude-opus → tiếp tục
+  Đang chạy một model Opus?
+    Y — đúng → tiếp tục
     S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
 ──────────────────────────────────────────────────────────────────
 ```
 
 - "Y" → tiếp tục sang Bước 1.
 - "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
-- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang claude-opus rồi chạy lại lệnh này."
+- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang một model Opus (`/model`) rồi chạy lại lệnh này."
 
 ## Bước 1 — Xác định Target File
 
@@ -57,7 +57,12 @@ Hiển thị và chờ phản hồi:
 2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
    - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
    - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
-   - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **Lệnh tech-docs** — target là tech-doc **gộp cấp PRD** `{TICKET-ID}-tech-design.md` (MỘT doc phủ nhiều UC; danh sách UC nằm ở `@trace.ucs`). Vì tên file mang `{TICKET-ID}` chứ **không** mang `{UC-ID}`, phải tách trước khi glob:
+     - `$ARGUMENTS` là **UC-ID** (`{TICKET-ID}-UC{N}`) → lấy `{TICKET-ID}` = phần **trước** `-UC`, rồi glob `{specs_dir}/{domain}/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - `$ARGUMENTS` là **TICKET-ID** → glob trực tiếp như trên.
+     - Chưa biết domain → `{specs_dir}/*/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - Vẫn không khớp → glob rộng `{specs_dir}/*/*/tech-docs/*tech-design*.md` rồi liệt kê để người dùng chọn.
+     *(Đừng glob `{UC-ID}*-tech-design*.md` — nó nở thành `FT-001-UC1*-tech-design*.md` và **không bao giờ** khớp `FT-001-tech-design.md`.)*
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
@@ -185,23 +190,82 @@ Nếu có section `services`:
 - Nếu target không mang `@trace.platform` (vd target là PRD `.md`), thử suy từ segment `bdd/{platform}/` trong path target.
 - Nếu vẫn không xác định được → `active_platform = null`.
 
-**2. Route tới service** — nếu active domain khớp một key trong `services`. Giá trị `services.{domain}` có **hai dạng**; nhận dạng bằng việc có `path` trực tiếp hay không:
+**2. Route tới service** — nếu active domain khớp một key trong `services`.
+
+Hình dung việc này như **tra địa chỉ**: đi từ `domain`, có thể qua `platform`, có thể qua `prd_slug`, cho tới khi chỉ còn đúng một submodule.
+
+Thứ trỏ tới đích gọi là một **service entry**. Nó chỉ có hai kiểu:
+
+| Kiểu | Nhận ra bằng | Nghĩa |
+|---|---|---|
+| **Đã chốt** | có `path` | Xong — đây là submodule cần tìm |
+| **Tra tiếp** | có `by_prd_slug` | Ô này còn nhiều submodule → tra thêm một nấc bằng `prd_slug` (2c) |
+
+**Kiểm tra hợp lệ TRƯỚC khi dùng một entry** (làm ngay, đừng đợi tới 2a/2b/2c — sai ở đây mà đi tiếp là route nhầm repo mà không báo gì):
+
+| Entry trông thế nào | Xử lý |
+|---|---|
+| có `path`, không có `by_prd_slug` | hợp lệ → dùng |
+| có `by_prd_slug`, không có `path` | hợp lệ → tra tiếp (2c) |
+| **có CẢ HAI** | ❌ lỗi cấu hình → `active_service = unresolved`. **KHÔNG** ưu tiên `path` rồi bỏ qua `by_prd_slug` — như vậy mọi feature sẽ âm thầm route về cùng một repo. Báo đúng key sai để người dùng sửa. |
+| **không có cái nào** (và cũng không phải map platform) | ❌ lỗi cấu hình → `unresolved`, nêu rõ entry thiếu `path`/`by_prd_slug` |
+| `by_prd_slug` chứa entry lại có `by_prd_slug` | ❌ lỗi cấu hình → `unresolved`. Chỉ tra đúng **một** nấc slug, không đệ quy |
+
+Còn `services.{domain}` thì có thể là **một service entry** (chốt luôn ở cấp domain), hoặc **một map platform → service entry** (phải qua nấc platform trước). Nhận dạng theo đúng thứ tự này:
+
+| Thấy gì trong `services.{domain}` | Đi nhánh |
+|---|---|
+| có `path` | **2a** — chốt luôn |
+| có `by_prd_slug` | **2c** — tra bằng `prd_slug` |
+| không có cả hai (chỉ có các sub-key `system`/`web`/`app`…) | **2b** — tra bằng `platform`, rồi lặp lại đúng bảng này cho entry con |
 
 **2a. Dạng phẳng** — `services.{domain}` có **trực tiếp** `path`/`module` (một domain ↔ một service, mọi platform về cùng submodule). Route như cũ:
 - Lưu `active_service` = `services.{domain}.path`
 - Lưu `active_service_module` = `services.{domain}.module`
 - Nếu service có `module` riêng → dùng nó làm `active_module` (override `tech_stack.module`)
 
-**2b. Dạng map-theo-platform** — `services.{domain}` **KHÔNG** có `path` trực tiếp mà chứa các sub-key platform (`system` / `web` / `app`), mỗi cái là `{ path, module }` (một business-domain trải trên nhiều platform/submodule). Route theo `active_platform` (bước 1b):
-- Nếu `active_platform` khớp một sub-key → `entry = services.{domain}.{active_platform}`; lưu `active_service = entry.path`, `active_service_module = entry.module` (→ `active_module`, override `tech_stack.module`).
-- Nếu `active_platform = null` (chưa xác định platform, vd đang thao tác cấp PRD) → **KHÔNG** chốt một service; đặt `active_service = multi` và lưu `service_candidates = services.{domain}` (toàn map platform→{path,module}). Lệnh cần một service cụ thể (`/generate-code`, `/dev-*`, `/fix-bug`) luôn chạy trên target `.feature` có platform nên sẽ resolve được ở lần chạy đó; lệnh cấp PRD (`/generate-prd`, `/refine-prd`) không cần service cụ thể.
+**2b. Dạng map-theo-platform** — `services.{domain}` **KHÔNG** có `path` trực tiếp mà chứa các sub-key platform (`system` / `web` / `app`), mỗi cái là một **service entry** (một business-domain trải trên nhiều platform/submodule). Route theo `active_platform` (bước 1b):
+- Nếu `active_platform` khớp một sub-key → `entry = services.{domain}.{active_platform}`. Nếu `entry` có `path` → lưu `active_service = entry.path`, `active_service_module = entry.module` (→ `active_module`, override `tech_stack.module`). Nếu `entry` có `by_prd_slug` → **đi tiếp sang 2c** với entry đó.
+- Nếu `active_platform = null` (chưa xác định platform, vd đang thao tác cấp PRD) → **KHÔNG** chốt một service; đặt `active_service = multi`, `service_candidates_kind = platform`, và lưu `service_candidates` = map platform→`{path, module}`. **Làm phẳng luôn ở đây:** platform nào có entry `by_prd_slug` thì giải bằng `prd_slug` hiện tại (target cấp PRD vẫn nằm trong một feature-package nên `prd_slug` đã biết từ bước 1) → `service_candidates.{platform}` vẫn là `{path, module}` phẳng. Nếu `prd_slug` không khớp key nào, ghi platform đó là `unresolved` kèm lý do thay vì bỏ im. Nhờ vậy **mọi lệnh downstream chỉ cần biết một kiểu `service_candidates`**. Lệnh cần một service cụ thể (`/generate-code`, `/dev-*`, `/fix-bug`) luôn chạy trên target `.feature` có platform nên sẽ resolve được ở lần chạy đó; lệnh cấp PRD (`/generate-prd`, `/refine-prd`) không cần service cụ thể.
 - Nếu `active_platform` xác định nhưng không có sub-key tương ứng → `active_service = unresolved` (xem Fallback) với lý do "domain `{domain}` chưa cấu hình platform `{active_platform}`".
 
-*(Cả 2a/2b: override `paths.specs_dir`/`paths.tech_docs_dir` per-service CHỈ khi `setup.spec_source` KHÔNG được đặt. Khi `spec_source` ĐƯỢC đặt, MỌI BDD/tech-doc là artifact liên team → để bước 4 route sang spec repo; KHÔNG pin per-service ở đây.)*
+**2c. Dạng map-theo-prd_slug** — một service entry chứa `by_prd_slug` thay cho `path`: **một ô của bảng định tuyến ứng với NHIỀU submodule**, mỗi feature-package một submodule. Dùng khi một platform (hoặc cả một domain) bị chia thành nhiều repo theo feature — ví dụ mỗi mini-game webview là một repo riêng.
+
+Đến đây `prd_slug` đã được trích ở bước 1 (không cần detect thêm gì). Route:
+
+- Nếu `prd_slug` khớp một key dưới `by_prd_slug` → `entry = {…}.by_prd_slug.{prd_slug}`; lưu `active_service = entry.path`, `active_service_module = entry.module` (→ `active_module`, override `tech_stack.module`).
+  **"Khớp" ở đây là khớp CHÍNH XÁC toàn chuỗi, phân biệt hoa/thường.** KHÔNG prefix, KHÔNG bỏ hậu tố, KHÔNG so gần đúng: `dap-chuot-v2` **không** khớp key `dap-chuot`; `Ban-Cung` **không** khớp `ban-cung`. Feature mới tách ra từ một feature cũ là một repo khác cho tới khi có người khai nó vào bảng.
+- Nếu `prd_slug = null` (chưa xác định feature-package — chỉ xảy ra khi không có target file, vd `$ARGUMENTS` rỗng) → **KHÔNG** chốt một service; đặt `active_service = multi`, `service_candidates_kind = prd_slug`, và lưu `service_candidates` = toàn map `by_prd_slug` (slug → `{path, module}`).
+  ⚠️ Đây là kiểu `service_candidates` **khác** với 2b — lệnh nào duyệt `service_candidates` theo platform (vd `/generate-bdd` sinh `bdd/{platform}/`) phải kiểm `service_candidates_kind = platform` trước; gặp `prd_slug` thì DỪNG và yêu cầu người dùng chỉ rõ target, đừng coi slug là platform.
+- Nếu `prd_slug` xác định nhưng **không** có key tương ứng → `active_service = unresolved` với lý do rõ: "domain `{domain}`{, platform `{active_platform}`} chưa cấu hình prd_slug `{prd_slug}`". **KHÔNG** tự đoán submodule gần đúng theo tên.
+
+Vị trí đặt `by_prd_slug` — hợp lệ ở **cả hai cấp**:
+- **Dưới một platform** (lồng trong 2b): `services.{domain}.{platform}.by_prd_slug` — platform đó có nhiều repo, các platform khác vẫn `{path, module}` như thường.
+- **Ngay dưới domain** (thay cho `path` của 2a): `services.{domain}.by_prd_slug` — domain không chia platform nhưng vẫn nhiều repo theo feature.
+
+*(`by_prd_slug` lồng trong `by_prd_slug` là vô nghĩa — nếu gặp, coi là lỗi cấu hình: `active_service = unresolved`, nêu rõ để người dùng sửa file. Một entry vừa có `path` vừa có `by_prd_slug` cũng là lỗi cấu hình — báo lỗi, không âm thầm ưu tiên cái nào.)*
+
+Ví dụ (một domain trải nhiều platform, riêng `webview` chia theo feature):
+```yaml
+services:
+  learning:
+    system: { path: "backend",     module: "java-spring" }
+    web:    { path: "web-app",     module: "nextjs" }
+    webview:
+      by_prd_slug:
+        dap-chuot: { path: "games/whac-a-mole", module: "phaser-game" }
+        ban-cung:  { path: "games/archery",     module: "phaser-game" }
+```
+→ target `specs/learning/dap-chuot/bdd/webview/UC1.feature` cho `domain = learning`,
+`active_platform = webview`, `prd_slug = dap-chuot` → `active_service = games/whac-a-mole`.
+
+*(Cả 2a/2b/2c: override `paths.specs_dir`/`paths.tech_docs_dir` per-service CHỈ khi `setup.spec_source` KHÔNG được đặt. Khi `spec_source` ĐƯỢC đặt, MỌI BDD/tech-doc là artifact liên team → để bước 4 route sang spec repo; KHÔNG pin per-service ở đây.)*
 
 **3. Fallback**:
 - Không phát hiện được domain, hoặc domain không khớp key nào trong `services` → giữ path mặc định từ Bước 1, đặt `active_service = unresolved`.
 - Domain khớp một map-theo-platform (2b) nhưng `active_platform` xác định mà thiếu sub-key tương ứng → `active_service = unresolved`, ghi lý do rõ để lệnh DỪNG báo lỗi cấu hình (không tự đoán platform).
+- Entry là map-theo-prd_slug (2c) nhưng `prd_slug` xác định mà thiếu key tương ứng → `active_service = unresolved`, ghi lý do rõ (không tự đoán submodule).
+- Entry sai cấu trúc (vừa có `path` vừa có `by_prd_slug`, hoặc `by_prd_slug` lồng nhau) → `active_service = unresolved`, nêu đúng key sai để người dùng sửa `project-context.yaml`.
 
 **4. Tự động override theo spec source** — nếu `setup.spec_source` được đặt VÀ path tương ứng chưa được set tường minh trong `paths:`:
 - Override `paths.specs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt.** Mọi spec artifact (PRD, BDD, tech-docs, design-spec) nằm dưới gốc spec thống nhất trong spec repo dùng chung theo bố cục feature-package: `{spec_source}/specs/{domain}/{prd-slug}/`. Mọi umbrella (FE/App/BE) đều đọc từ đây. *(`specs/` theo service chỉ khi không có `spec_source`.)*
@@ -351,7 +415,7 @@ active_module = tech_stack.module   (vd: "java-spring", "react", "flutter")
 | `platform_type` | Modules |
 |---|---|
 | `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
-| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular`, `phaser-game` |
 | `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
 
 Nếu `tech_stack.module` rỗng hoặc không nhận diện được → set `platform_type = "unknown"` và gắn cờ ⚠️ trong recap Bước 7.
@@ -398,7 +462,7 @@ Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
 Lessons   : {loaded — N guardrails | chưa có}
 Platform  : {active_platform: system | web | app | — nếu chưa xác định}
-Service   : {active_service} ({active_service_module}) | multi (map-theo-platform, chốt khi target có platform) | single-service
+Service   : {active_service} ({active_service_module}) [← domain{/platform}{/prd_slug} nếu route qua by_prd_slug] | multi (map-theo-platform hoặc map-theo-prd_slug, chốt khi target đủ platform/prd_slug) | single-service
 Svc Root  : {service_root} — đã nạp conventions + trace_dir từ config service | —
 Status    : {FULL | PARTIAL — thiếu: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
@@ -422,7 +486,16 @@ Tiếp tục sang bước kế tiếp của lệnh đang gọi.
 
 
 > **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: 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.
 
@@ -616,20 +689,36 @@ Từ vựng step của System BDD (luôn dùng — bất kể từ vựng FE/App
 
 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"`, lấy module theo từng platform từ `service_candidates` khi sinh `bdd/{platform}/`.
+- `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"` (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. |
+| `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. |
 
-**Output path (umbrella mode):** `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC{N}-{slug}.feature`
+### 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`) |
 
-*(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.)*
+- `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`:
 
@@ -712,9 +801,9 @@ Sau khi sinh tất cả file `.feature` và `.tsv` cho UC được giao, trả v
 
 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`
+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`.
@@ -763,7 +852,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 | 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.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. |
@@ -819,19 +908,23 @@ CHECKPOINT: "Outline này đúng chưa? Bạn muốn thêm hay bớt SC nào kh
 
 ## 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)*
+**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
+```
 
-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).
+`{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
 # ============================================================
 # @trace.id: {TICKET-ID}-UC{N}
 # @trace.title: <Feature name>
-# @trace.revision: 1  ← field tĩnh; dùng @trace.bdd_version để theo dõi version (tăng bởi /review-context --fix hoặc --resume)
+# @trace.revision: 1  ← field tĩnh; version theo dõi bằng @trace.bdd_version
 # @trace.domain: <domain>
-# @trace.platform: {active_platform — web | app | system | (bỏ trong umbrella mode)}
+# @trace.platform: {active_platform — web | app | system}   ← BẮT BUỘC mọi mode; phải khớp segment bdd/{platform}/ của path
 # @trace.service: {active_service — bỏ trong spec repo mode}
 # @trace.module: {active_module trong umbrella mode; "unknown" trong spec repo mode}
 # @trace.status: draft
@@ -839,8 +932,8 @@ Với mỗi UC, ghi vào path đã phân giải ở trên. Dùng từ vựng cho
 # @trace.created_at: {YYYY-MM-DD}
 # @trace.prd: {TICKET-ID}
 # @trace.prd_version: {đọc từ metadata PRD "| **Version** |"}
-# @trace.bdd_version: {1.0 nếu gen mới; tăng 0.1 khi gen lại — vd 1.0 → 1.1}
-# @trace.business_rules: {TICKET-ID}-UC{N}-BR1, {TICKET-ID}-UC{N}-BR2
+# @trace.bdd_version: {cấp FILE — 1.0 nếu gen mới; tăng 0.1 khi gen lại. Khác @trace.sc_version (cấp từng SC) bên dưới}
+# @trace.business_rules: {TICKET-ID}-UC{N}-BR{m}, {TICKET-ID}-UC{N}-BR{m+1}   ← {m} lấy NGUYÊN từ PRD §3: BR đánh số LIÊN TỤC toàn PRD, KHÔNG reset theo UC
 # @trace.dataset: {domain}.testdata.yaml
 # ============================================================
 
@@ -887,8 +980,8 @@ Feature: <Feature name>
 
   # 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
+  # @trace.sc_version: 1.0   ← cấp SCENARIO. Sửa thân SC này (tên/step/table/side-effect) thì +0.1, nếu không code cũ mãi hiện OK
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR{m}
   @happy
   Scenario: <mô tả business outcome — dùng động từ chính xác: create/receive/assign/block>
     Given <input state — alias từ dataset>
@@ -899,7 +992,7 @@ Feature: <Feature name>
   # Side-effects: <...>
   # @trace.scenario: {TICKET-ID}-UC{N}-SC2
   # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR{m}
   @happy @alternative
   Scenario: <cùng theme NHÓM 1 nhưng path khác — vd: giá trị enum khác>
     Given <state>
@@ -913,7 +1006,7 @@ Feature: <Feature name>
   # Side-effects: <...>
   # @trace.scenario: {TICKET-ID}-UC{N}-SC3
   # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET-ID}-UC{N}-BR2
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR{m+2}
   @edge
   Scenario: <scenario boundary / error>
     Given <state>
@@ -925,8 +1018,8 @@ Feature: <Feature name>
 #   AC1 (...) → SC1, SC2
 #   AC2 (...) → SC3
 # 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
+#   {TICKET-ID}-UC{N}-BR{m}   (...) → SC1, SC2
+#   {TICKET-ID}-UC{N}-BR{m+2} (...) → SC3
 # Wireframe mapping (mỗi component/action ≥1 SC — C.1):
 #   Screen "<screen name>":
 #     [x] <action 1>  → SC1
@@ -939,6 +1032,9 @@ Feature: <Feature name>
 
 # === PRE-MERGE CHECKLIST ===
 # - [ ] Mỗi SC có Side-effects + @trace.scenario + @trace.sc_version + @trace.business_rules
+# - [ ] SỬA nội dung một SC (tên / step / data table / side-effect) → đã bump @trace.sc_version của
+#       CHÍNH SC đó (+0.1). Quên bump = code sinh từ SC cũ vẫn hiện OK, không ai biết phải regen.
+#       (Đổi @trace.business_rules / tag / comment → KHÔNG bump: không đổi hành vi cần implement.)
 # - [ ] Coverage Matrix: 0 dòng MISSING (C.1)
 # - [ ] FE/App: mỗi Screen State (≠default) + AC-UI behavioral của design-spec có ≥1 SC (C.1 mở rộng)
 # - [ ] Mỗi AC/BR map tới ≥1 SC (C.2)
@@ -949,7 +1045,35 @@ Feature: <Feature name>
 
 ```
 
-*(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.)*
+> **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`.
 
 ---
 
@@ -970,7 +1094,19 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tde
   - 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.)*
+  - 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:**
 
@@ -1103,6 +1239,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
 | /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
 | /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
+| /map-testids            | `/qc-design-test {UC-ID}` (QC dựng Page Object từ contract §4.5.6 vừa ghi) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
 | /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
@@ -1111,8 +1248,8 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
 | /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
 | /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
-| /fix-bug                | Tạo PR và link tới ticket                  |
+| /validate-traces        | **Cờ 🔴 trước (chặn PR):** SEAM_UNWIRED → nối binding sang class thật, xoá/thay stub · STUB_UNRESOLVED → `/generate-code {owner_uc}` (lấp logic tại chỗ + xoá hàm song song) · ORPHANED/TRACE_ORPHAN → quyết định thủ công (xoá code+test, đưa scenario trở lại `.feature`, hoặc sửa `sc_id` của tag). **Rồi:** DRIFT/UNTRACKED → `/generate-code {UC-ID}` · BDD_DRIFT → `/generate-code {feature-file}` · tech-doc lỗi thời vs BDD → `/generate-tech-docs` → `/review-tech-docs` · PRD drift → `/generate-bdd {prd-file}` · GAP → `/dev-gen-test {UC-ID}`. **Chỉ tạo PR khi mọi cờ 🔴 = 0** |
+| /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-test {UC-ID}` để verify + đóng bug |
 | /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
 | /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
 | /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
@@ -1147,9 +1284,9 @@ Next (spec repo):
   → 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}]
+[Umbrella mode — service: {active_service} · platform: {active_platform} (suy từ module {active_module})]
 Files:
-  {paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC1-{slug}.feature ({N} scenarios)
+  {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):
@@ -1157,5 +1294,11 @@ Next (umbrella):
   → /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}
+
 📊 Living Docs: chạy /validate-traces (hoặc /sync) để push trace này lên dashboard spec-module.
 ```