@educa-corp/sdd-framework 0.3.0 → 0.4.2

package/core/steps/context-loader.md

@@ -90,23 +90,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`.)*
@@ -256,7 +315,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.
@@ -303,7 +362,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/core/steps/gate.md

@@ -29,23 +29,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
 
@@ -54,7 +54,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.

package/core/steps/report-footer.md

@@ -71,6 +71,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}` |
@@ -79,8 +80,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/` |

package/core/templates/README.md

@@ -0,0 +1,47 @@
+# templates/ — build-time skeletons
+
+> **Nếu bạn đang mở thư mục này ở `.agent/templates/` trong một project: sửa file ở đây KHÔNG có tác dụng.**
+
+## Vì sao
+
+Các skeleton trong thư mục này được `{{include}}` **nướng cứng vào file lệnh lúc `npm run build`**:
+
+```
+templates/feature.template
+      ↓ {{include:templates/feature.template}}  ← bin/build.js, thay thế văn bản lúc build
+commands/generate-bdd.md
+      ↓ copy vào core/ → mirror sang .agent/
+.agent/commands/generate-bdd.md        ← LỆNH THẬT SỰ CHẠY (đã chứa sẵn skeleton)
+.agent/templates/feature.template      ← bản tham khảo, KHÔNG lệnh nào đọc
+```
+
+Không lệnh nào đọc một path template lúc chạy. `paths.feature_template` / `paths.prd_template` từng tồn tại trong `project-context.yaml` nhưng chưa bao giờ có tác dụng — đã được gỡ bỏ (xem `GAPS.md` G9).
+
+**Thêm nữa:** `.agent/` là vùng bị ghi đè. `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện** (`bin/index.js` → `copyDirRecursive`, không có existence check, không backup). File duy nhất được giữ lại là `.agent/project-context.yaml`. Nên mọi chỉnh sửa ở `.agent/templates/` sẽ **biến mất im lặng** ở lần nâng cấp kế tiếp.
+
+## Muốn đổi cấu trúc artifact sinh ra thì làm gì
+
+Sửa file trong **repo framework** rồi build lại:
+
+```bash
+# trong repo sdd-framework
+vim templates/feature.template          # hoặc prd.template.md, tech-design.template.md, …
+npm run build                           # inline lại vào commands/*.md + core/ + .agent/
+```
+
+Rồi phát hành version mới; project chạy `/update-framework` để nhận.
+
+## File nào ở đây đi vào đâu
+
+| Template | Được include vào | Trở thành |
+|---|---|---|
+| `feature.template` | `commands/generate-bdd.tmpl` | mỗi file `.feature` |
+| `prd.template.md` | `commands/generate-prd.tmpl` | mỗi PRD |
+| `tech-design.template.md` | `commands/generate-tech-docs.tmpl` | tech-doc gộp / PRD |
+| `design-spec.template.md` | `commands/generate-design-spec.tmpl` | design-spec / platform |
+| `architecture.template.md` | `commands/generate-architecture.tmpl` | tài liệu kiến trúc |
+| `product-definition.template.md` | `commands/define-product.tmpl` | product definition |
+| `platform-guide.template.md` | (tham khảo) | — |
+| `project-context.yaml` | **không** include — được copy thẳng làm file config khởi tạo | `.agent/project-context.yaml` |
+
+> Lưu ý `project-context.yaml` là ngoại lệ duy nhất: nó **được** copy ra làm file thật của project, và **được bảo vệ** khỏi ghi đè khi nâng cấp (chỉ tạo nếu chưa tồn tại).

package/core/templates/feature.template

@@ -1,9 +1,9 @@
 # ============================================================
 # @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
@@ -11,8 +11,8 @@
 # @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
 # ============================================================
 
@@ -59,8 +59,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>
@@ -71,7 +71,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>
@@ -85,7 +85,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>
@@ -97,8 +97,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
@@ -111,6 +111,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)

package/core/templates/project-context.yaml

@@ -25,28 +25,41 @@ project:
 # All paths are relative to workspace root.
 paths:
   # Feature-Package Layout:
-  #   specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md  — PRD document
-  #   specs/{domain}/{prd-slug}/bdd/             — BDD .feature files
-  #   specs/{domain}/{prd-slug}/tech-docs/       — Technical design docs
-  #   specs/{domain}/{prd-slug}/design-spec/     — Design specs (FE/App only)
-  #   .trace/{domain}/{prd-slug}/{UC-ID}.tsv     — Trace state
+  #   specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md      — PRD document
+  #   specs/{domain}/{prd-slug}/bdd/{platform}/                — BDD .feature  ({platform} = web | app | system)
+  #   specs/{domain}/{prd-slug}/tech-docs/                     — Technical design (ONE merged doc per PRD: {TICKET-ID}-tech-design.md)
+  #   specs/{domain}/{prd-slug}/design-spec/                   — Design specs (FE/App only)
+  #   specs/{domain}/{prd-slug}/changelog/                     — PRD changelog overflow (created once history exceeds 5 versions)
+  #   .trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv        — Trace state (ONE book per UC × platform)
+  #
+  # The {platform} segment is NOT optional — in any mode, including umbrella.
+  # A UC's `web` and `system` features are two different files; without the segment they
+  # collide on one filename and overwrite each other. Trace is split the same way, so the
+  # spec layout has to match it. Every .feature also carries `@trace.platform` matching
+  # its own {platform} segment. (Projects still on the old flat bdd/ layout:
+  # run `npx @educa-corp/sdd-framework --migrate-bdd-platform` — dry-run by default.)
   #
   # specs_dir is the unified root for all spec artifact types (PRD, BDD, tech-docs, design-spec).
   # prd-slug is derived from the PRD folder path — not a separate config variable.
   specs_dir: "specs"
-  templates_dir: "specs/templates"
 
   # Source code root — gốc mã nguồn của service/app này (nơi generate-code đặt & quét code).
   # BE thường suy vị trí từ CLAUDE.md §2 (code_base_package + layer); src_dir là gốc chung,
   # và là NGUỒN CHÍNH cho FE (component/hook/service/adapter) + phạm vi quét reuse (DS5).
   # Ví dụ: "src" (mono FE), "app/src", "src/main/java" (BE). Chỉnh theo layout thật của repo.
   src_dir: "src"
-  feature_template: ".agent/templates/feature.template"   # SoT skeleton .feature (dùng bởi /generate-bdd qua {{include}})
-  bdd_writing_guide: "specs/templates/bdd-writing-guide.md"
-  trace_report: "specs/.trace/trace-report.md"
 
-  # PRD template (PRDs are at specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md)
-  prd_template: "specs/templates/prd.template.md"
+  # ── Template artifact — KHÔNG cấu hình được ──
+  # Đã bỏ 6 key chết (không lệnh nào đọc): feature_template · prd_template ·
+  # templates_dir · bdd_writing_guide · product_definition_template · trace_report.
+  # Các skeleton được {{include}} NƯỚNG CỨNG vào file lệnh lúc `npm run build`,
+  # nên lệnh không bao giờ đọc một path template lúc chạy.
+  # (trace_report còn trỏ sai hẳn: report thật là {trace_dir}/trace-report.json.)
+  #
+  # Đổi cấu trúc .feature / PRD sinh ra = sửa templates/*.template* TRONG REPO
+  # FRAMEWORK rồi build lại. Sửa .agent/templates/* trong project KHÔNG có tác
+  # dụng, và 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).
   refinement_dir: ".agent/review"
 
   # QC's OWN analysis/design working docs (qc-analyze/plan/design-test outputs:
@@ -66,7 +79,6 @@ paths:
 
   # Product Definitions
   product_definitions_dir: "specs/product-definition"
-  product_definition_template: "specs/templates/product-definition.template.md"
 
   # Domain Knowledge
   domain_knowledge_dir: "specs/domain-knowledge"
@@ -90,7 +102,7 @@ paths:
   # This variable is no longer needed as a separate path — derived from specs_dir.
   # design_spec_dir: "specs/design-spec"   ← removed; use specs_dir instead
 
-  # Trace (internal structure: .trace/{domain}/{prd-slug}/{UC-ID}.tsv)
+  # Trace (internal structure: .trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv — one book per UC × platform)
   trace_dir: ".trace"
 
   # Tester / QC feedback (written by /report-bug and /propose-scenario).
@@ -133,14 +145,16 @@ domains:
 #   specs_dir            → {spec_source}/specs                # unified root — PRD/BDD/tech-docs/design-spec
 #   tech_docs_dir        → {spec_source}/specs                # merged into specs_dir
 #   domain_knowledge_dir → {spec_source}/specs/domain-knowledge
-#   trace_dir            → {spec_source}/.trace               # structure: .trace/{domain}/{prd-slug}/{UC-ID}.tsv
+#   trace_dir            → {spec_source}/.trace               # structure: .trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv
 # (You can still override these manually in paths: section below.)
 # With spec_source set, only ONE override is needed instead of four separate dir vars.
 #
 # services:                                   # domain → service submodule routing
 #   # 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:
+#   # A domain value has THREE forms — context-loader (Step 1.5) auto-detects in this order:
+#   #   has `path`          → FORM A (resolved)
+#   #   has `by_prd_slug`   → FORM C (look up one more level)
+#   #   otherwise           → FORM B (per-platform map)
 #   #
 #   # FORM A — FLAT (one domain ↔ one submodule, all platforms):
 #   {{DOMAIN_1}}:
@@ -157,6 +171,22 @@ domains:
 #     web:    { path: "{{WEB_SUBMODULE_DIR}}", module: "nextjs" }
 #     app:    { path: "{{APP_SUBMODULE_DIR}}", module: "flutter" }
 #   #
+#   # FORM C — PER-PRD_SLUG MAP (one routing cell ↔ MANY submodules, one per feature-package).
+#   #          Use when a platform — or a whole domain — is split into one repo per feature,
+#   #          e.g. each webview mini-game lives in its own repo. No `path`; instead a
+#   #          `by_prd_slug` table keyed by the feature-package folder name. context-loader
+#   #          already extracted prd_slug in Step 1, so no extra detection is needed.
+#   #          Valid at BOTH levels: directly under the domain, or nested under a platform.
+#   {{DOMAIN_3}}:
+#     system: { path: "{{BE_SUBMODULE_DIR}}", module: "java-spring" }   # normal entry
+#     webview:                                                          # this cell → many repos
+#       by_prd_slug:
+#         {{PRD_SLUG_1}}: { path: "games/{{GAME_1}}", module: "phaser-game" }
+#         {{PRD_SLUG_2}}: { path: "games/{{GAME_2}}", module: "phaser-game" }
+#   #  A prd_slug with no entry → active_service = unresolved (the command STOPS rather than
+#   #  guessing a lookalike repo). An entry with BOTH `path` and `by_prd_slug` is a config
+#   #  error, as is nesting `by_prd_slug` inside `by_prd_slug`.
+#   #
 #   # 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.
@@ -169,7 +199,9 @@ domains:
 #   root, so without a service CLAUDE.md, code generation falls back to umbrella defaults
 #   + 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).
+#   submodule ({system|web|app}.path/CLAUDE.md). For FORM C, one per feature repo
+#   (by_prd_slug.{slug}.path/CLAUDE.md) — these repos usually share a stack, so the fastest
+#   route is to write one and copy it, adjusting the parts that actually differ.
 
 # ----- Architecture -----
 architecture:

package/core/templates/tech-design.template.md

@@ -40,7 +40,7 @@
 @trace.service: {service — từ header BDD @trace.service}
 @trace.module: {module liên quan — vd dotnet, angular}
 @trace.platforms: {system | web | app — tuỳ thư mục BDD nào tồn tại}
-@trace.bdd_version: {map theo từng platform — vd system=1.5, web=1.9, app=1.7; chỉ platform có mặt. Mỗi feature mang bdd_version riêng; đừng gộp về một số.}
+@trace.bdd_versions: {MAP theo từng platform — số nhiều, KHÁC @trace.bdd_version (scalar) của .feature — vd system=1.5, web=1.9, app=1.7; chỉ platform có mặt. Mỗi feature mang bdd_version riêng; đừng gộp về một số.}
 @trace.api_source: {existing | —}
 @trace.revision: 1
 @trace.status: draft

package/docs/02-concepts/traceability.md

@@ -10,9 +10,11 @@
 
 | Artifact | Trace tag |
 |----------|-----------|
-| **BDD scenario** | `@trace.id` · `@trace.scenario` · `@trace.business_rules` · `@trace.bdd_version` · `@trace.prd_version` |
-| **Code** (boundary only) | `@trace.implements` · `@trace.source` — *KHÔNG lưu version* (tránh dual SSOT) |
-| **Test** | `@trace.verifies` · `@trace.covers` |
+| **BDD file** (header) | `@trace.id` · **`@trace.platform`** · `@trace.domain` · `@trace.prd` · `@trace.prd_version` · `@trace.bdd_version` · `@trace.status` |
+| **BDD scenario** (mỗi SC) | `@trace.scenario` · **`@trace.sc_version`** · `@trace.business_rules` |
+| **Code** (boundary only) | `@trace.implements` · `@trace.source` · **`@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision`** — lặp cả block theo **từng UC** trong file đa-UC |
+| **Code** (chỗ chưa implement) | `@trace.stub` · `@trace.stub_owner` · `@trace.stub_for` · `@trace.seam_pending` · `@trace.seam_port` |
+| **Test** | `@trace.verifies` |
 | **Bug fix** | `@trace.fixes` · `@trace.root_cause` · `@trace.regression` |
 
 → Đầy đủ field & format: [Reference › Trace Schema](../04-reference/trace-schema.md).
@@ -65,10 +67,31 @@ Chỉ tag `@trace` ở **boundary**, không tag mọi file → tránh **tag expl
 
 ---
 
-## Single SSOT cho version
+## Version sống ở đâu — và vì sao code CŨNG mang version
 
-- **Version chỉ ở spec level** (`bdd_version`/`prd_version`). Code **không** lưu version riêng — nó dùng `.tsv` (`gen_ver`) để so.
-- Lưu version cả spec lẫn code = **dual SSOT** → drift không đáng tin.
+**Spec là SSOT của "version hiện tại". Code mang version của "lúc tôi được sinh ra".** Hai thứ khác nhau, nên không phải dual SSOT.
+
+| Nơi | Ghi cái gì | Ai ghi |
+|---|---|---|
+| `.feature` / PRD / tech-doc | version **hiện tại** của spec — SSOT | tác giả spec |
+| `.tsv` `spec_ver` | gương của `@trace.sc_version` hiện tại | `/generate-bdd`, `/validate-traces` |
+| `.tsv` `gen_ver` | version scenario **tại thời điểm codegen**, theo từng SC | `/generate-code` |
+| **Code** `@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision` | version của **từng artifact upstream** tại thời điểm codegen, theo từng **method** | `/generate-code` |
+
+Drift = **so các mốc này với nhau**; sự lệch nhau chính là tín hiệu, không phải lỗi dữ liệu:
+
+- `spec_ver != gen_ver` → `DRIFT` (scenario đổi sau khi sinh code)
+- `@trace.prd_version` trong code < Version PRD hiện tại → `PRD_DRIFT`
+- `@trace.bdd_version` trong code < `.feature` hiện tại → `BDD_DRIFT`
+- `@trace.tech_doc_revision` trong code < `@trace.revision` của tech-doc → `TECHDOC_DRIFT`
+
+**Vì sao không thể bỏ tag version trong code và chỉ dựa vào `.tsv`:**
+
+1. **Độ phân giải khác nhau.** `.tsv` là một sổ cho mỗi UC × platform. Một **file code** có thể phục vụ nhiều UC, mỗi UC ở một version khác nhau — chỉ tag đặt cạnh từng method mới diễn đạt được "UC1 ở bdd v1.4, UC3 ở v2.1".
+2. **Vòng đời khác nhau.** `.tsv` là artifact **sinh ra**, có thể regen/xoá/mirror; ở chế độ umbrella nó còn nằm ở **repo khác** (spec submodule) với code. Tag trong code là bản ghi duy nhất **đi cùng** code qua mọi lần copy/move/merge.
+3. **Sự lệch nhau là thứ ta muốn đo.** Nếu chỉ có một bản ghi thì không có gì để so — đó mới là lúc drift trở nên không phát hiện được.
+
+> ⚠️ **Đừng "tối ưu" bằng cách gỡ tag version khỏi code.** `/validate-traces` Step 4/5/5c **đọc chính các tag đó**; gỡ đi là làm drift detection mù **im lặng** — build vẫn xanh, dashboard vẫn đẹp. `/review-code` lăng kính 1 gắn cờ **major** cho mỗi block `@trace.implements` thiếu tag version đi kèm.
 
 ---