@educa-corp/sdd-framework 0.2.9 → 0.4.0

package/commands/generate-design-spec.md

@@ -187,23 +187,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`.)*
@@ -353,7 +412,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.
@@ -400,7 +459,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}
 ```

package/commands/generate-prd.md

@@ -187,23 +187,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`.)*
@@ -353,7 +412,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.
@@ -400,7 +459,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}
 ```
@@ -553,6 +612,34 @@ Không bao giờ để TICKET-ID dạng plain text nếu file PRD tương ứng
 - **BR ID**: `{TICKET-ID}-UC{N}-BR{M}` — **M tăng liên tục trên toàn PRD** (KHÔNG reset theo từng UC).
   - Ví dụ: UC1 → BR1, BR2; UC2 → BR3, BR4 (KHÔNG phải BR1, BR2 lại từ đầu).
 
+## Hình dạng bảng Business Rule *(3 cột mặc định — mở cột khi nội dung là bản ghi lặp)*
+
+Bảng 3 cột `ID | Business Rule | Business Logic` là **mặc định**, KHÔNG phải luật cứng. Nó hoạt động tốt khi Business Logic là **văn xuôi** (mô tả luật bằng câu). Nó **gãy** khi Business Logic là một **bản ghi có cấu trúc lặp** — lúc đó ép vào một ô buộc phải serialize bản ghi thành chuỗi, và bảng mất khả năng đọc lướt / đếm / diff.
+
+**Điều kiện kích hoạt mở cột** — cả hai phải đúng:
+1. **Mọi** BR trong một UC chia sẻ **cùng một bộ thuộc tính** lặp lại (vd `trigger` / `data` / `tần suất` / `nguồn`); VÀ
+2. Bộ thuộc tính đó là **cấu trúc đều**, không phải văn xuôi tự do.
+
+**Dấu hiệu tự phát hiện (dùng khi tự kiểm trước khi ghi):** đang phải dùng `<br/>` để nhồi **nhiều hơn một bản ghi cùng cấu trúc** vào một ô Business Logic. Một `<br/>` ngăn cách các ý của **cùng một** luật thì bình thường — nhiều `<br/>` ngăn cách các **bản ghi ngang hàng** là tín hiệu sai hình dạng.
+
+**Khi kích hoạt:** promote thuộc tính thành **cột**, một bản ghi = một **dòng**. Giữ nguyên hai cột `ID` + `Business Rule` (traceability phụ thuộc chúng); chỉ cột `Business Logic` được tách thành N cột. Giá trị dùng chung cho mọi dòng → đưa lên **§1d Quy ước**, đừng lặp trong từng ô.
+
+**Khi KHÔNG kích hoạt:** giữ nguyên 3 cột. Phần lớn PRD tính năng rơi vào đây — BR của chúng là văn xuôi ("coi Landing là không sẵn sàng khi dịch vụ gặp sự cố; quá 3 giây chưa trả nội dung; hoặc trả nội dung rỗng"), không có bộ thuộc tính nào lặp. **Luật này tự kích hoạt theo hình dạng nội dung — không phải một cờ người dùng phải nhớ bật.**
+
+> **⚠️ Guard — BR ID churn (BẮT BUỘC kiểm khi mở cột trên PRD ĐÃ TỒN TẠI):**
+> Mở cột đúng nghĩa = một bản ghi một dòng ⇒ **số BR tăng**. Vì BR ID tăng liên tục trên toàn PRD (xem "Quy ước đánh số"), chèn dòng ở giữa sẽ **đánh số lại mọi BR phía sau**. BDD mang tag `@trace.business_rules: {TICKET}-UC1-BR1, …` — nếu PRD đã có BDD, mọi tag sau điểm chèn sẽ trỏ **sai trong im lặng**.
+> Trước khi mở cột trên một PRD đã tồn tại → kiểm tra `{paths.specs_dir}/{domain}/{prd-slug}/bdd/`:
+> - **Chưa có BDD** → mở cột tự do, không cần hỏi.
+> - **Đã có BDD** → **DỪNG**, báo người dùng: *"Mở cột sẽ đánh số lại {N} BR; {M} file BDD đang ref BR ID cũ. Chọn: (1) mở cột + re-gen BDD, (2) giữ hình dạng cũ."* Chờ chọn.
+>
+> PRD sinh **mới** không bị ảnh hưởng — chưa có downstream nào ref BR ID.
+
+## Quy ước tài liệu (§1d) & Note block *(hai slot tuỳ chọn)*
+
+- **§1d Quy ước** — khi tài liệu có quy ước áp dụng **xuyên suốt mọi BR** (giá trị mặc định dùng chung, cách đọc cột, định nghĩa cục bộ), khai báo **một lần** ở đây. BR **không** lặp lại; AC **trỏ tới** thay vì chép lại. Không có quy ước xuyên suốt → **xoá hẳn section** (như `Existing API Contract` khi greenfield). Phân biệt: §1b Phạm vi = ranh giới; business-dictionary = thuật ngữ cấp domain; §1d = quy ước **cục bộ của tài liệu này**.
+- **Note block sau bảng BR** — cho phép `> **Note {BR ref}:** …` ngay sau bảng để giải thích **quyết định đã chốt** (vì sao luật như vậy, ràng buộc nào dẫn tới). Đặt cạnh nơi phát sinh, đừng dồn xuống cuối file.
+  **Ranh giới với "Giả định AI":** Note = quyết định **đã chốt**; Giả định AI = **độ vênh cần PO chốt**. Note KHÔNG được nuốt Giả định AI — nghi ngờ thì để ở Giả định AI, vì đó là thứ PO phải đọc.
+
 ## Traceability AC ↔ BR ↔ UC
 
 - **Giữ link AC→BR từ discovery (KHÔNG vứt khi flatten):** Product Definition Phase 6 có cột "Bắt nguồn từ BR-{N}". Khi viết AC §2, **remap** mỗi `BR-{N}` (số discovery) sang **BR ID của PRD** (`{TICKET-ID}-UC{n}-BR{m}` sau khi đã phân BR vào UC) và gắn vào cuối AC: `_(BR: {ids})_`. Mỗi AC PHẢI có ≥1 ref BR.
@@ -600,8 +687,13 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
   AI Agent sẽ điền các section dựa trên input từ PO.
   Các placeholder {…} cần được thay thế bằng nội dung thực tế.
 
-  FORMAT CHUẨN: Business Rule = bảng 3 cột
-  ID | Business Rule | Business Logic (KHÔNG tách Business Logic ra khối riêng).
+  FORMAT BR: MẶC ĐỊNH bảng 3 cột — ID | Business Rule | Business Logic
+    (KHÔNG tách Business Logic ra khối riêng).
+    NGOẠI LỆ — MỞ CỘT: nếu MỌI BR trong một UC chia sẻ cùng một bộ thuộc tính lặp lại
+    (vd trigger / data / tần suất), promote các thuộc tính đó thành CỘT RIÊNG —
+    một bản ghi = một DÒNG. Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi
+    NHIỀU HƠN MỘT bản ghi cùng cấu trúc vào một ô. Chi tiết + cảnh báo BR ID churn:
+    xem §3 "Business Rule" của template và mục "Hình dạng bảng Business Rule" của lệnh.
 
   TERMINOLOGY:
   - Tuân thủ 100% từ điển project: specs/domain-knowledge/business-dictionary.md
@@ -679,6 +771,18 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 
 - {Cần {dữ liệu/năng lực} từ {feature/team/partner} — vì {lý do nghiệp vụ}} — hoặc "Không có"
 
+## d. Quy ước *(TUỲ CHỌN — chỉ thêm khi tài liệu có quy ước áp dụng xuyên suốt; nếu không có → XOÁ HẲN section này)*
+
+> Khai báo **MỘT LẦN** các quy ước áp dụng cho **mọi BR** ở §3. BR **KHÔNG** lặp lại nội dung đã khai ở đây,
+> AC §2 **trỏ tới** quy ước thay vì chép lại. Đây là nơi chứa định nghĩa dùng chung, giá trị mặc định,
+> và cách đọc các cột của bảng BR — những thứ trước đây bị xé nhỏ và lặp trong từng dòng.
+>
+> Phân biệt với **§1b Phạm vi** (ranh giới làm/không làm) và **business-dictionary** (định nghĩa thuật ngữ
+> cấp domain, dùng chung nhiều PRD): §1d chỉ chứa quy ước **cục bộ của tài liệu này**.
+
+- **{Tên quy ước}**: {nội dung áp dụng cho mọi BR bên dưới}
+- **{Giá trị mặc định dùng chung}**: {…}
+
 ---
 
 # 2. Acceptance Criteria
@@ -713,11 +817,47 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 
 **Business Rule**
 
+> **Hình dạng bảng — mặc định 3 cột.** Dùng dạng này khi Business Logic là **văn xuôi** (mô tả luật bằng câu).
+
 | ID | Business Rule | Business Logic |
 |----|---------------|----------------|
 | {TICKET}-{N}-UC1-BR1 | {luật ngắn gọn} | - {logic chi tiết, xuống dòng bằng `<br/>`}<br/>- {…} |
 | {TICKET}-{N}-UC1-BR2 | {…} | - {…} |
 
+<!--
+  NGOẠI LỆ — MỞ CỘT (dùng THAY cho bảng 3 cột ở trên, KHÔNG dùng cả hai):
+
+  Điều kiện kích hoạt: MỌI BR trong UC này chia sẻ CÙNG một bộ thuộc tính lặp lại.
+  Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi NHIỀU HƠN MỘT bản ghi cùng
+  cấu trúc vào một ô Business Logic.
+
+  Khi kích hoạt: promote thuộc tính thành CỘT, một bản ghi = một DÒNG:
+
+    | ID  | Business Rule | {Thuộc tính 1} | {Thuộc tính 2} | {Thuộc tính 3} |
+    |-----|---------------|----------------|----------------|----------------|
+    | BR1 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
+    | BR2 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
+
+  Hai cột ID + Business Rule LUÔN giữ (traceability phụ thuộc chúng). Chỉ cột
+  Business Logic được tách thành N cột. Giá trị dùng chung cho mọi dòng → đưa lên
+  §1d Quy ước, ĐỪNG lặp trong từng ô.
+
+  ⚠️ CẢNH BÁO BR ID CHURN — đọc trước khi mở cột trên PRD ĐÃ TỒN TẠI:
+  Mở cột đúng nghĩa = một bản ghi một dòng ⇒ số BR TĂNG. Vì BR ID tăng liên tục
+  trên toàn PRD, chèn dòng ở giữa sẽ ĐÁNH SỐ LẠI mọi BR phía sau. Nếu PRD này đã có
+  BDD downstream, mọi tag `@trace.business_rules` trong .feature sẽ trỏ SAI trong im lặng.
+  → Trước khi mở cột trên PRD đã có: kiểm tra `{specs_dir}/{domain}/{prd-slug}/bdd/`.
+    - Chưa có BDD → mở cột tự do.
+    - ĐÃ có BDD → DỪNG, báo người dùng: cần re-gen BDD sau khi đổi, hoặc giữ nguyên hình dạng cũ.
+  PRD sinh MỚI không bị ảnh hưởng (chưa có downstream).
+-->
+
+> **Note {BR ref}:** *(TUỲ CHỌN)* {giải thích **quyết định đã chốt** — vì sao luật này như vậy, ràng buộc
+> nào dẫn tới nó, biên nào đã cân nhắc}. Đặt ngay sau bảng, cạnh nơi phát sinh.
+>
+> **Ranh giới với "Giả định AI" (Appendix):** Note = quyết định **đã chốt**, giải thích cho người đọc sau.
+> Giả định AI = **độ vênh CẦN PO chốt**. Note **KHÔNG** được nuốt Giả định AI — nghi ngờ thì để ở Giả định AI.
+
 ---
 
 #### {TICKET}-{N}-UC2: {Tên use case}
@@ -738,6 +878,12 @@ flowchart TD
 
 ## b. Wireframe
 
+> **KHÔNG nhân bản §3.** Wireframe liệt kê **màn + thành phần + hành động** — nó là nguồn coverage màn hình
+> cho `/generate-bdd` (C.1), KHÔNG phải bản sao thứ hai của bảng Business Rule.
+> Nếu một dòng Wireframe không thêm thông tin nào ngoài BR đã có → **tham chiếu BR ID, đừng chép nội dung**.
+> Nếu cả §4b không thêm gì mới so với §3 → **xoá hẳn §4b** (hai nguồn sự thật cho cùng một dữ liệu sẽ lệch nhau
+> ngay lần sửa đầu tiên).
+
 ### Screen 1: {Tên màn}
 
 | Thành phần | Chi tiết |
@@ -828,7 +974,10 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 - [ ] **Altitude (AC vs BR/BL)**: AC chỉ nêu **outcome quan sát/kiểm được + ref BR** — KHÔNG chứa cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết); cơ chế nằm ở **BR/BL** (§3). AC không lặp lại nội dung BR nó ref. **Scope** = ranh giới (KHÔNG định nghĩa thuật ngữ / KHÔNG cơ chế)
 - [ ] Mỗi UC có Actor / Description / Pre-condition / Post-condition
 - [ ] §1c "Phụ thuộc liên service" có mặt: kế thừa từ discovery Phase 1 câu 8 (hoặc "Không có" nếu discovery trống); case partner song song có ghi phụ thuộc partner ở đây
-- [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung bảng 3 cột `ID | Business Rule | Business Logic`
+- [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung **một bảng** — KHÔNG tách Business Logic ra khối riêng
+- [ ] **Hình dạng bảng BR đúng với nội dung**: 3 cột khi Business Logic là văn xuôi; **mở cột** (1 bản ghi = 1 dòng) khi mọi BR trong UC chia sẻ cùng bộ thuộc tính lặp. Kiểm cụ thể: **0 ô Business Logic chứa nhiều hơn một bản ghi cùng cấu trúc** (dấu hiệu: `<br/>` ngăn cách các bản ghi ngang hàng thay vì các ý của cùng một luật) — xem "Hình dạng bảng Business Rule"
+- [ ] **Nếu mở cột trên PRD đã tồn tại**: đã kiểm `bdd/` và xử lý BR ID churn (chưa có BDD → tự do; đã có BDD → đã hỏi người dùng, không tự ý đổi)
+- [ ] **§1d Quy ước**: nếu có quy ước xuyên suốt → khai báo MỘT LẦN ở §1d, 0 lần lặp lại trong ô BR, AC trỏ tới thay vì chép; nếu không có → section đã xoá hẳn (không để rỗng)
 - [ ] BR ID tăng liên tục trên toàn PRD — không reset theo từng UC
 - [ ] **Traceability AC↔BR↔UC**: mỗi AC §2 có ≥1 ref `_(BR: …)_`; mỗi UC §3 có dòng "AC liên quan"; và hai chiều khớp nhau (tập "AC liên quan" của UC = tập AC có ref BR trỏ về UC đó)
 - [ ] Mọi cross-reference TICKET-ID đều là inline link `[TICKET-ID](./file.md)`
@@ -838,6 +987,7 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 - [ ] **API Source nhất quán**: nếu `existing` → bảng "Existing API Contract" đủ method/path/request/response (hoặc mang block ⛔ PENDING kèm con trỏ nguồn); nếu greenfield/partner → section "Existing API Contract" đã bị xoá hẳn (không để bảng rỗng), và case partner có dependency + assumption ghi rõ
 - [ ] User Flow có cả luồng lỗi / luồng ngoại lệ
 - [ ] Wireframe phủ tất cả màn hình liên quan tới Use Case
+- [ ] **Wireframe không nhân bản §3**: 0 dòng §4b lặp lại nội dung đã có ở bảng Business Rule — không thêm thông tin thì ref BR ID; cả §4b không thêm gì mới thì xoá hẳn (tránh hai nguồn sự thật)
 - [ ] **Định dạng (readability)**: User Story / AC / các field của UC (Actor, Description, Pre/Post-condition) viết dạng bullet `- **Label:** …` — mỗi ý MỘT dòng, KHÔNG viết các dòng liền nhau (sẽ bị dồn thành 1 đoạn khi render); có một dòng trống trước và sau mỗi bảng
 
 ## Output

package/commands/generate-prd.tmpl

@@ -82,6 +82,34 @@ Không bao giờ để TICKET-ID dạng plain text nếu file PRD tương ứng
 - **BR ID**: `{TICKET-ID}-UC{N}-BR{M}` — **M tăng liên tục trên toàn PRD** (KHÔNG reset theo từng UC).
   - Ví dụ: UC1 → BR1, BR2; UC2 → BR3, BR4 (KHÔNG phải BR1, BR2 lại từ đầu).
 
+## Hình dạng bảng Business Rule *(3 cột mặc định — mở cột khi nội dung là bản ghi lặp)*
+
+Bảng 3 cột `ID | Business Rule | Business Logic` là **mặc định**, KHÔNG phải luật cứng. Nó hoạt động tốt khi Business Logic là **văn xuôi** (mô tả luật bằng câu). Nó **gãy** khi Business Logic là một **bản ghi có cấu trúc lặp** — lúc đó ép vào một ô buộc phải serialize bản ghi thành chuỗi, và bảng mất khả năng đọc lướt / đếm / diff.
+
+**Điều kiện kích hoạt mở cột** — cả hai phải đúng:
+1. **Mọi** BR trong một UC chia sẻ **cùng một bộ thuộc tính** lặp lại (vd `trigger` / `data` / `tần suất` / `nguồn`); VÀ
+2. Bộ thuộc tính đó là **cấu trúc đều**, không phải văn xuôi tự do.
+
+**Dấu hiệu tự phát hiện (dùng khi tự kiểm trước khi ghi):** đang phải dùng `<br/>` để nhồi **nhiều hơn một bản ghi cùng cấu trúc** vào một ô Business Logic. Một `<br/>` ngăn cách các ý của **cùng một** luật thì bình thường — nhiều `<br/>` ngăn cách các **bản ghi ngang hàng** là tín hiệu sai hình dạng.
+
+**Khi kích hoạt:** promote thuộc tính thành **cột**, một bản ghi = một **dòng**. Giữ nguyên hai cột `ID` + `Business Rule` (traceability phụ thuộc chúng); chỉ cột `Business Logic` được tách thành N cột. Giá trị dùng chung cho mọi dòng → đưa lên **§1d Quy ước**, đừng lặp trong từng ô.
+
+**Khi KHÔNG kích hoạt:** giữ nguyên 3 cột. Phần lớn PRD tính năng rơi vào đây — BR của chúng là văn xuôi ("coi Landing là không sẵn sàng khi dịch vụ gặp sự cố; quá 3 giây chưa trả nội dung; hoặc trả nội dung rỗng"), không có bộ thuộc tính nào lặp. **Luật này tự kích hoạt theo hình dạng nội dung — không phải một cờ người dùng phải nhớ bật.**
+
+> **⚠️ Guard — BR ID churn (BẮT BUỘC kiểm khi mở cột trên PRD ĐÃ TỒN TẠI):**
+> Mở cột đúng nghĩa = một bản ghi một dòng ⇒ **số BR tăng**. Vì BR ID tăng liên tục trên toàn PRD (xem "Quy ước đánh số"), chèn dòng ở giữa sẽ **đánh số lại mọi BR phía sau**. BDD mang tag `@trace.business_rules: {TICKET}-UC1-BR1, …` — nếu PRD đã có BDD, mọi tag sau điểm chèn sẽ trỏ **sai trong im lặng**.
+> Trước khi mở cột trên một PRD đã tồn tại → kiểm tra `{paths.specs_dir}/{domain}/{prd-slug}/bdd/`:
+> - **Chưa có BDD** → mở cột tự do, không cần hỏi.
+> - **Đã có BDD** → **DỪNG**, báo người dùng: *"Mở cột sẽ đánh số lại {N} BR; {M} file BDD đang ref BR ID cũ. Chọn: (1) mở cột + re-gen BDD, (2) giữ hình dạng cũ."* Chờ chọn.
+>
+> PRD sinh **mới** không bị ảnh hưởng — chưa có downstream nào ref BR ID.
+
+## Quy ước tài liệu (§1d) & Note block *(hai slot tuỳ chọn)*
+
+- **§1d Quy ước** — khi tài liệu có quy ước áp dụng **xuyên suốt mọi BR** (giá trị mặc định dùng chung, cách đọc cột, định nghĩa cục bộ), khai báo **một lần** ở đây. BR **không** lặp lại; AC **trỏ tới** thay vì chép lại. Không có quy ước xuyên suốt → **xoá hẳn section** (như `Existing API Contract` khi greenfield). Phân biệt: §1b Phạm vi = ranh giới; business-dictionary = thuật ngữ cấp domain; §1d = quy ước **cục bộ của tài liệu này**.
+- **Note block sau bảng BR** — cho phép `> **Note {BR ref}:** …` ngay sau bảng để giải thích **quyết định đã chốt** (vì sao luật như vậy, ràng buộc nào dẫn tới). Đặt cạnh nơi phát sinh, đừng dồn xuống cuối file.
+  **Ranh giới với "Giả định AI":** Note = quyết định **đã chốt**; Giả định AI = **độ vênh cần PO chốt**. Note KHÔNG được nuốt Giả định AI — nghi ngờ thì để ở Giả định AI, vì đó là thứ PO phải đọc.
+
 ## Traceability AC ↔ BR ↔ UC
 
 - **Giữ link AC→BR từ discovery (KHÔNG vứt khi flatten):** Product Definition Phase 6 có cột "Bắt nguồn từ BR-{N}". Khi viết AC §2, **remap** mỗi `BR-{N}` (số discovery) sang **BR ID của PRD** (`{TICKET-ID}-UC{n}-BR{m}` sau khi đã phân BR vào UC) và gắn vào cuối AC: `_(BR: {ids})_`. Mỗi AC PHẢI có ≥1 ref BR.
@@ -133,7 +161,10 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 - [ ] **Altitude (AC vs BR/BL)**: AC chỉ nêu **outcome quan sát/kiểm được + ref BR** — KHÔNG chứa cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết); cơ chế nằm ở **BR/BL** (§3). AC không lặp lại nội dung BR nó ref. **Scope** = ranh giới (KHÔNG định nghĩa thuật ngữ / KHÔNG cơ chế)
 - [ ] Mỗi UC có Actor / Description / Pre-condition / Post-condition
 - [ ] §1c "Phụ thuộc liên service" có mặt: kế thừa từ discovery Phase 1 câu 8 (hoặc "Không có" nếu discovery trống); case partner song song có ghi phụ thuộc partner ở đây
-- [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung bảng 3 cột `ID | Business Rule | Business Logic`
+- [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung **một bảng** — KHÔNG tách Business Logic ra khối riêng
+- [ ] **Hình dạng bảng BR đúng với nội dung**: 3 cột khi Business Logic là văn xuôi; **mở cột** (1 bản ghi = 1 dòng) khi mọi BR trong UC chia sẻ cùng bộ thuộc tính lặp. Kiểm cụ thể: **0 ô Business Logic chứa nhiều hơn một bản ghi cùng cấu trúc** (dấu hiệu: `<br/>` ngăn cách các bản ghi ngang hàng thay vì các ý của cùng một luật) — xem "Hình dạng bảng Business Rule"
+- [ ] **Nếu mở cột trên PRD đã tồn tại**: đã kiểm `bdd/` và xử lý BR ID churn (chưa có BDD → tự do; đã có BDD → đã hỏi người dùng, không tự ý đổi)
+- [ ] **§1d Quy ước**: nếu có quy ước xuyên suốt → khai báo MỘT LẦN ở §1d, 0 lần lặp lại trong ô BR, AC trỏ tới thay vì chép; nếu không có → section đã xoá hẳn (không để rỗng)
 - [ ] BR ID tăng liên tục trên toàn PRD — không reset theo từng UC
 - [ ] **Traceability AC↔BR↔UC**: mỗi AC §2 có ≥1 ref `_(BR: …)_`; mỗi UC §3 có dòng "AC liên quan"; và hai chiều khớp nhau (tập "AC liên quan" của UC = tập AC có ref BR trỏ về UC đó)
 - [ ] Mọi cross-reference TICKET-ID đều là inline link `[TICKET-ID](./file.md)`
@@ -143,6 +174,7 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 - [ ] **API Source nhất quán**: nếu `existing` → bảng "Existing API Contract" đủ method/path/request/response (hoặc mang block ⛔ PENDING kèm con trỏ nguồn); nếu greenfield/partner → section "Existing API Contract" đã bị xoá hẳn (không để bảng rỗng), và case partner có dependency + assumption ghi rõ
 - [ ] User Flow có cả luồng lỗi / luồng ngoại lệ
 - [ ] Wireframe phủ tất cả màn hình liên quan tới Use Case
+- [ ] **Wireframe không nhân bản §3**: 0 dòng §4b lặp lại nội dung đã có ở bảng Business Rule — không thêm thông tin thì ref BR ID; cả §4b không thêm gì mới thì xoá hẳn (tránh hai nguồn sự thật)
 - [ ] **Định dạng (readability)**: User Story / AC / các field của UC (Actor, Description, Pre/Post-condition) viết dạng bullet `- **Label:** …` — mỗi ý MỘT dòng, KHÔNG viết các dòng liền nhau (sẽ bị dồn thành 1 đoạn khi render); có một dòng trống trước và sau mỗi bảng
 
 ## Output

package/commands/generate-spec-manifest.md

@@ -192,23 +192,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`.)*
@@ -358,7 +417,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.
@@ -405,7 +464,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}
 ```