@educa-corp/sdd-framework 0.2.1 → 0.2.4

package/core/commands/review-context.md

@@ -186,16 +186,28 @@ Nếu có section `services`:
   *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
 - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
-**2. Route tới service** — nếu active domain khớp với một key trong `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, MỌI BDD (web/app/**system**) là artifact dùng chung liên team → để bước 4 route sang spec repo; KHÔNG pin theo service ở đây.
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, tech-design (API contract) là artifact liên team và phải nằm trong spec repo dùng chung (xử lý ở bước 4), nên để bước 4 route `tech_docs_dir` — KHÔNG pin theo service ở đây.
+**1b. Phát hiện active platform** (chỉ cần khi service ở dạng map-theo-platform — bước 2b):
+- Đọc `@trace.platform` từ header của target `.feature` (`system` | `web` | `app`) — Gate đã resolve target trước bước này.
+- 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:
+
+**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`)
 
-**3. Fallback** — nếu không phát hiện được domain hoặc không có service key khớp:
-- Giữ path mặc định từ Bước 1
-- Đặt `active_service = unresolved`
+**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ể.
+- 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.)*
+
+**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).
 
 **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`.)*
@@ -215,7 +227,7 @@ Nếu có section `services`:
 
 ## Bước 1.6 — [SERVICE CONVENTIONS] Nạp convention riêng của service (chế độ umbrella)
 
-*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc context ở chế độ single-service.*
+*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc `"multi"` (chưa chốt một service — dạng map-theo-platform ở cấp PRD) hoặc context ở chế độ single-service.*
 
 Khi `active_service` đã được phân giải thành một path thật ở Bước 1.5 (vd: `user-service/`):
 
@@ -391,7 +403,8 @@ Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
 Lessons   : {loaded — N guardrails | chưa có}
-Service   : {active_service} ({active_service_module}) | single-service
+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
 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/core/commands/review-tech-docs.md

@@ -183,16 +183,28 @@ Nếu có section `services`:
   *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
 - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
-**2. Route tới service** — nếu active domain khớp với một key trong `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, MỌI BDD (web/app/**system**) là artifact dùng chung liên team → để bước 4 route sang spec repo; KHÔNG pin theo service ở đây.
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, tech-design (API contract) là artifact liên team và phải nằm trong spec repo dùng chung (xử lý ở bước 4), nên để bước 4 route `tech_docs_dir` — KHÔNG pin theo service ở đây.
+**1b. Phát hiện active platform** (chỉ cần khi service ở dạng map-theo-platform — bước 2b):
+- Đọc `@trace.platform` từ header của target `.feature` (`system` | `web` | `app`) — Gate đã resolve target trước bước này.
+- 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:
+
+**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`)
 
-**3. Fallback** — nếu không phát hiện được domain hoặc không có service key khớp:
-- Giữ path mặc định từ Bước 1
-- Đặt `active_service = unresolved`
+**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ể.
+- 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.)*
+
+**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).
 
 **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`.)*
@@ -212,7 +224,7 @@ Nếu có section `services`:
 
 ## Bước 1.6 — [SERVICE CONVENTIONS] Nạp convention riêng của service (chế độ umbrella)
 
-*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc context ở chế độ single-service.*
+*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc `"multi"` (chưa chốt một service — dạng map-theo-platform ở cấp PRD) hoặc context ở chế độ single-service.*
 
 Khi `active_service` đã được phân giải thành một path thật ở Bước 1.5 (vd: `user-service/`):
 
@@ -388,7 +400,8 @@ Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
 Lessons   : {loaded — N guardrails | chưa có}
-Service   : {active_service} ({active_service_module}) | single-service
+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
 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/core/commands/setup-ai-first.md

@@ -122,18 +122,25 @@ Dựa trên câu trả lời:
 
 **project_type = 1 (Single-service):** Tiếp tục setup chuẩn bên dưới.
 
-**project_type = 2 (Umbrella):** Hỏi hai câu follow-up:
-- "Path tới spec submodule (vd `free-trial-specs`)? Nhấn Enter để skip."
-- "Liệt kê các service dạng cặp `domain:module`, ngăn cách bởi dấu phẩy
-  (vd `user:java-spring,order:java-spring`). Nhấn Enter để skip."
+**project_type = 2 (Umbrella):** Hỏi các câu follow-up:
+- "Path tới spec submodule (vd `free-trial-spec`)? Nhấn Enter để skip."
+- "Một business-domain được triển khai trên NHIỀU platform (BE + Web + App) không? (Y/N)"
+  - **N → dạng phẳng (FORM A):** "Liệt kê service dạng cặp `domain:module`, ngăn cách bởi dấu phẩy
+    (vd `user:java-spring,order:java-spring`). Nhấn Enter để skip."
+  - **Y → dạng map-theo-platform (FORM B):** "Liệt kê dạng bộ ba `domain:platform:module`
+    (platform ∈ system|web|app), ngăn cách bởi dấu phẩy — lặp lại domain cho từng platform
+    (vd `onboarding:system:java-spring,onboarding:web:nextjs,onboarding:app:flutter`). Nhấn Enter để skip."
+    context-loader route theo `@trace.platform` của target `.feature` → chọn đúng submodule.
+    **Giữ `@trace.domain` là business-domain** (KHÔNG bịa `onboarding-web`).
 
 Rồi:
 - Skip tạo bất kỳ artifact `specs/` nào (mọi spec — PRD, BDD, tech-docs, design-spec — sống trong spec submodule theo bố cục feature-package `specs/{domain}/{prd-slug}/`)
 - Chỉ tạo: `.trace/`, `.agent/review/` ở cấp umbrella
   *(Trừ khi user yêu cầu rõ tạo cấu trúc đầy đủ)*
-- Sinh `.agent/project-context.yaml` ở umbrella mode với services và spec_source đã cung cấp
-- Skip tạo `CLAUDE.md` (umbrella không có một tech stack đơn)
-- Sau setup, nhắc: "Mở từng service submodule riêng trong Claude Code để cài framework ở đó nếu cần."
+- Sinh `.agent/project-context.yaml` ở umbrella mode với services (FORM A hoặc B) và spec_source đã cung cấp.
+  **Sau khi sinh, MỞ file kiểm tra:** mỗi `services.{domain}.path` (hoặc `.{platform}.path`) phải trỏ **đúng tên thư mục submodule thật** — generator để placeholder `TODO-…` vì tên dir thường khác tên domain. Sửa cho khớp trước khi chạy lệnh generate.
+- Skip tạo `CLAUDE.md` root (umbrella không có một tech stack đơn) — nhưng nhắc mỗi submodule code cần overlay `{path}/CLAUDE.md` riêng (thiếu thì code-gen fallback về default + cờ ⚠️, có thể sai coding-standards).
+- Sau setup, nhắc: "Mở từng service submodule riêng trong Claude Code để cài framework/overlay ở đó nếu cần."
 
 **project_type = 3 (PO Spec repo):**
 - Tạo base dir: `specs/product-definition/`, `specs/domain-knowledge/`, `feedback/`, `.agent/review/`

package/core/commands/validate-traces.md

@@ -181,16 +181,28 @@ Nếu có section `services`:
   *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
 - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
-**2. Route tới service** — nếu active domain khớp với một key trong `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, MỌI BDD (web/app/**system**) là artifact dùng chung liên team → để bước 4 route sang spec repo; KHÔNG pin theo service ở đây.
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, tech-design (API contract) là artifact liên team và phải nằm trong spec repo dùng chung (xử lý ở bước 4), nên để bước 4 route `tech_docs_dir` — KHÔNG pin theo service ở đây.
+**1b. Phát hiện active platform** (chỉ cần khi service ở dạng map-theo-platform — bước 2b):
+- Đọc `@trace.platform` từ header của target `.feature` (`system` | `web` | `app`) — Gate đã resolve target trước bước này.
+- 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:
+
+**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`)
 
-**3. Fallback** — nếu không phát hiện được domain hoặc không có service key khớp:
-- Giữ path mặc định từ Bước 1
-- Đặt `active_service = unresolved`
+**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ể.
+- 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.)*
+
+**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).
 
 **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`.)*
@@ -210,7 +222,7 @@ Nếu có section `services`:
 
 ## Bước 1.6 — [SERVICE CONVENTIONS] Nạp convention riêng của service (chế độ umbrella)
 
-*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc context ở chế độ single-service.*
+*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc `"multi"` (chưa chốt một service — dạng map-theo-platform ở cấp PRD) hoặc context ở chế độ single-service.*
 
 Khi `active_service` đã được phân giải thành một path thật ở Bước 1.5 (vd: `user-service/`):
 
@@ -386,7 +398,8 @@ Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
 Lessons   : {loaded — N guardrails | chưa có}
-Service   : {active_service} ({active_service_module}) | single-service
+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
 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/core/steps/context-loader.md

@@ -83,16 +83,28 @@ Nếu có section `services`:
   *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
 - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
-**2. Route tới service** — nếu active domain khớp với một key trong `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, MỌI BDD (web/app/**system**) là artifact dùng chung liên team → để bước 4 route sang spec repo; KHÔNG pin theo service ở đây.
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, tech-design (API contract) là artifact liên team và phải nằm trong spec repo dùng chung (xử lý ở bước 4), nên để bước 4 route `tech_docs_dir` — KHÔNG pin theo service ở đây.
+**1b. Phát hiện active platform** (chỉ cần khi service ở dạng map-theo-platform — bước 2b):
+- Đọc `@trace.platform` từ header của target `.feature` (`system` | `web` | `app`) — Gate đã resolve target trước bước này.
+- 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:
+
+**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`)
 
-**3. Fallback** — nếu không phát hiện được domain hoặc không có service key khớp:
-- Giữ path mặc định từ Bước 1
-- Đặt `active_service = unresolved`
+**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ể.
+- 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.)*
+
+**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).
 
 **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`.)*
@@ -112,7 +124,7 @@ Nếu có section `services`:
 
 ## Bước 1.6 — [SERVICE CONVENTIONS] Nạp convention riêng của service (chế độ umbrella)
 
-*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc context ở chế độ single-service.*
+*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc `"multi"` (chưa chốt một service — dạng map-theo-platform ở cấp PRD) hoặc context ở chế độ single-service.*
 
 Khi `active_service` đã được phân giải thành một path thật ở Bước 1.5 (vd: `user-service/`):
 
@@ -288,7 +300,8 @@ Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
 Lessons   : {loaded — N guardrails | chưa có}
-Service   : {active_service} ({active_service_module}) | single-service
+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
 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/core/templates/project-context.yaml

@@ -132,12 +132,28 @@ domains:
 # With spec_source set, only ONE override is needed instead of four separate dir vars.
 #
 # services:                                   # domain → service submodule routing
-#   {{DOMAIN_1}}:                             # must match the PRD's `Domain` (Metadata row) / folder path segment
+#   # Each domain key MUST match the PRD's `Domain` (Metadata row) / folder path segment.
+#   # A domain value has TWO forms — context-loader (Step 1.5) auto-detects by whether
+#   # `path` is present directly:
+#   #
+#   # FORM A — FLAT (one domain ↔ one submodule, all platforms):
+#   {{DOMAIN_1}}:
 #     path: "{{SERVICE_SUBMODULE_DIR}}"       # relative path to service submodule (code + .trace/)
 #     module: "{{STACK_MODULE}}"              # e.g., java-spring, nextjs, flutter
-#     # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo —
-#     # do NOT pin per-service specs_dir / tech_docs_dir here (they would be ignored).
-#     # Per-service specs_dir / tech_docs_dir apply ONLY when there is no spec_source.
+#   #
+#   # FORM B — PER-PLATFORM MAP (one business-domain implemented on several platforms /
+#   #          submodules — a merged monorepo/workspace). No direct `path`; instead one
+#   #          sub-key per platform (system | web | app). context-loader routes by the
+#   #          target .feature's @trace.platform → picks {path, module} for that platform.
+#   #          The PRD keeps a SINGLE business @trace.domain (do NOT invent onboarding-web).
+#   {{DOMAIN_2}}:
+#     system: { path: "{{BE_SUBMODULE_DIR}}",  module: "java-spring" }
+#     web:    { path: "{{WEB_SUBMODULE_DIR}}", module: "nextjs" }
+#     app:    { path: "{{APP_SUBMODULE_DIR}}", module: "flutter" }
+#   #
+#   # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo —
+#   # do NOT pin per-service specs_dir / tech_docs_dir here (they would be ignored).
+#   # Per-service specs_dir / tech_docs_dir apply ONLY when there is no spec_source.
 #
 # IMPORTANT — per-service CLAUDE.md:
 #   Each service submodule should have its OWN CLAUDE.md ({path}/CLAUDE.md) defining its
@@ -145,12 +161,9 @@ domains:
 #   layers: root CLAUDE.md (umbrella-wide shared rules) + {service}/CLAUDE.md (overlay,
 #   wins on conflict for architecture/coding-standards). The agent sits at the umbrella
 #   root, so without a service CLAUDE.md, code generation falls back to umbrella defaults
-#   (likely the wrong stack). Generate one per service via /setup-ai-first inside each.
-#   {{DOMAIN_2}}:
-#     path: "{{SERVICE_2_DIR}}"
-#     module: "{{STACK_MODULE}}"
-#     specs_dir: "{{SERVICE_2_DIR}}/specs"
-#     tech_docs_dir: "{{SERVICE_2_DIR}}/specs"
+#   + the module stack-profile (a ⚠️ is flagged in the context recap). Generate one per
+#   service via /setup-ai-first inside each. For FORM B, add one CLAUDE.md per platform
+#   submodule ({system|web|app}.path/CLAUDE.md).
 
 # ----- Architecture -----
 architecture:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"

package/steps/context-loader.md

@@ -83,16 +83,28 @@ Nếu có section `services`:
   *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
 - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
-**2. Route tới service** — nếu active domain khớp với một key trong `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, MỌI BDD (web/app/**system**) là artifact dùng chung liên team → để bước 4 route sang spec repo; KHÔNG pin theo service ở đây.
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, tech-design (API contract) là artifact liên team và phải nằm trong spec repo dùng chung (xử lý ở bước 4), nên để bước 4 route `tech_docs_dir` — KHÔNG pin theo service ở đây.
+**1b. Phát hiện active platform** (chỉ cần khi service ở dạng map-theo-platform — bước 2b):
+- Đọc `@trace.platform` từ header của target `.feature` (`system` | `web` | `app`) — Gate đã resolve target trước bước này.
+- 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:
+
+**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`)
 
-**3. Fallback** — nếu không phát hiện được domain hoặc không có service key khớp:
-- Giữ path mặc định từ Bước 1
-- Đặt `active_service = unresolved`
+**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ể.
+- 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.)*
+
+**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).
 
 **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`.)*
@@ -112,7 +124,7 @@ Nếu có section `services`:
 
 ## Bước 1.6 — [SERVICE CONVENTIONS] Nạp convention riêng của service (chế độ umbrella)
 
-*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc context ở chế độ single-service.*
+*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc `"multi"` (chưa chốt một service — dạng map-theo-platform ở cấp PRD) hoặc context ở chế độ single-service.*
 
 Khi `active_service` đã được phân giải thành một path thật ở Bước 1.5 (vd: `user-service/`):
 
@@ -288,7 +300,8 @@ Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
 Lessons   : {loaded — N guardrails | chưa có}
-Service   : {active_service} ({active_service_module}) | single-service
+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
 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/templates/project-context.yaml

@@ -132,12 +132,28 @@ domains:
 # With spec_source set, only ONE override is needed instead of four separate dir vars.
 #
 # services:                                   # domain → service submodule routing
-#   {{DOMAIN_1}}:                             # must match the PRD's `Domain` (Metadata row) / folder path segment
+#   # Each domain key MUST match the PRD's `Domain` (Metadata row) / folder path segment.
+#   # A domain value has TWO forms — context-loader (Step 1.5) auto-detects by whether
+#   # `path` is present directly:
+#   #
+#   # FORM A — FLAT (one domain ↔ one submodule, all platforms):
+#   {{DOMAIN_1}}:
 #     path: "{{SERVICE_SUBMODULE_DIR}}"       # relative path to service submodule (code + .trace/)
 #     module: "{{STACK_MODULE}}"              # e.g., java-spring, nextjs, flutter
-#     # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo —
-#     # do NOT pin per-service specs_dir / tech_docs_dir here (they would be ignored).
-#     # Per-service specs_dir / tech_docs_dir apply ONLY when there is no spec_source.
+#   #
+#   # FORM B — PER-PLATFORM MAP (one business-domain implemented on several platforms /
+#   #          submodules — a merged monorepo/workspace). No direct `path`; instead one
+#   #          sub-key per platform (system | web | app). context-loader routes by the
+#   #          target .feature's @trace.platform → picks {path, module} for that platform.
+#   #          The PRD keeps a SINGLE business @trace.domain (do NOT invent onboarding-web).
+#   {{DOMAIN_2}}:
+#     system: { path: "{{BE_SUBMODULE_DIR}}",  module: "java-spring" }
+#     web:    { path: "{{WEB_SUBMODULE_DIR}}", module: "nextjs" }
+#     app:    { path: "{{APP_SUBMODULE_DIR}}", module: "flutter" }
+#   #
+#   # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo —
+#   # do NOT pin per-service specs_dir / tech_docs_dir here (they would be ignored).
+#   # Per-service specs_dir / tech_docs_dir apply ONLY when there is no spec_source.
 #
 # IMPORTANT — per-service CLAUDE.md:
 #   Each service submodule should have its OWN CLAUDE.md ({path}/CLAUDE.md) defining its
@@ -145,12 +161,9 @@ domains:
 #   layers: root CLAUDE.md (umbrella-wide shared rules) + {service}/CLAUDE.md (overlay,
 #   wins on conflict for architecture/coding-standards). The agent sits at the umbrella
 #   root, so without a service CLAUDE.md, code generation falls back to umbrella defaults
-#   (likely the wrong stack). Generate one per service via /setup-ai-first inside each.
-#   {{DOMAIN_2}}:
-#     path: "{{SERVICE_2_DIR}}"
-#     module: "{{STACK_MODULE}}"
-#     specs_dir: "{{SERVICE_2_DIR}}/specs"
-#     tech_docs_dir: "{{SERVICE_2_DIR}}/specs"
+#   + the module stack-profile (a ⚠️ is flagged in the context recap). Generate one per
+#   service via /setup-ai-first inside each. For FORM B, add one CLAUDE.md per platform
+#   submodule ({system|web|app}.path/CLAUDE.md).
 
 # ----- Architecture -----
 architecture: