@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/core/modules/android-compose/stack-profile.yaml

@@ -54,4 +54,4 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"

package/core/modules/flutter/stack-profile.yaml

@@ -56,4 +56,4 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"

package/core/modules/ios-swiftui/stack-profile.yaml

@@ -52,4 +52,4 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"

package/core/modules/java-spring/stack-profile.yaml

@@ -23,6 +23,6 @@ coding_standards:
 
 trace_tags:
   implements: "@trace.implements={UC-ID}-SC{N}"
-  source: "@trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "@trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "@trace.verifies={UC-ID}"
   test_type: "@trace.test_type=unit|integration"

package/core/modules/nextjs/stack-profile.yaml

@@ -69,6 +69,6 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "// @trace.verifies={UC-ID}"
   test_type: "// @trace.test_type=unit|e2e"

package/core/modules/nuxt/stack-profile.yaml

@@ -53,6 +53,6 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "// @trace.verifies={UC-ID}"
   test_type: "// @trace.test_type=unit|integration"

package/core/modules/phaser-game/stack-profile.yaml

@@ -85,6 +85,6 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "// @trace.verifies={UC-ID}"
   test_type: "// @trace.test_type=unit|integration"

package/core/modules/php-laravel/stack-profile.yaml

@@ -51,6 +51,6 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "// @trace.verifies={UC-ID}"
   test_type: "// @trace.test_type=unit|feature"

package/core/modules/qc-playwright/stack-profile.yaml

@@ -59,7 +59,7 @@ testing:
 trace_tags:
   # QC tests map back to the framework's scenarios — drives qc_status in the trace TSV.
   verifies: "# @trace.verifies={UC-ID}-SC{N}"
-  source: "# @trace.source=<official .feature path>"
+  source: "# @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   test_type: "# @trace.test_type=functional|integration|e2e|non-functional"
 
 # qc_status: /qc-run-test writes pass|fail|skip|not_run + qc_run_at into {trace_dir}/{UC-ID}.tsv

package/core/modules/react/stack-profile.yaml

@@ -58,6 +58,6 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "// @trace.verifies={UC-ID}"
   test_type: "// @trace.test_type=unit|integration"

package/core/modules/react-native/stack-profile.yaml

@@ -53,4 +53,4 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"

package/core/modules/vue/stack-profile.yaml

@@ -60,6 +60,6 @@ testing:
 
 trace_tags:
   implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   verifies: "// @trace.verifies={UC-ID}"
   test_type: "// @trace.test_type=unit|integration"

package/core/rules/workflow.md

@@ -18,6 +18,35 @@
 - Do NOT create files outside the directories specified in `project-context.yaml → paths`.
 - If new scope is discovered mid-command, STOP and ask: "I found additional scope [{description}]. Should I include it? (Y/N)"
 
+## Trace Contract
+
+- Contract trace (field `@trace.*`, cột `.tsv`, path pattern, giá trị enum) có **một
+  nguồn-sự-thật máy đọc**: `bin/trace-schema.json`. Bản cho người đọc:
+  `docs/04-reference/trace-schema.md` — giữ hai file đồng bộ.
+- Đổi contract (thêm/bỏ/đổi nghĩa một field, path, hay giá trị enum) → **sửa
+  `bin/trace-schema.json` TRƯỚC**, rồi mới sửa lệnh. `npm run build` chạy
+  `bin/self-check.js` và **fail** nếu lệnh lệch schema.
+- Field có consumer mà **không có producer** là lỗi chặn build — đó chính là hình dạng
+  của G1 (`@trace.sc_version`: 3 consumer, 0 producer, DRIFT chết mà không ai báo).
+- **Làm mất hiệu lực ≠ ghi đè.** Cột trace có chủ sở hữu rõ ràng — `dev_selftest`/`dev_selftest_at`
+  thuộc `/dev-run-test` · `qc_status`/`qc_run_at` thuộc `/qc-run-test` · `test_count`/`test_classes`
+  thuộc `/dev-gen-test` — và **chỉ chủ được ghi giá trị KHẲNG ĐỊNH** (`pass`/`fail`/số lượng).
+  Nhưng lệnh nào làm giá trị đó **HẾT ĐÚNG** (spec đổi, code đổi) thì **BẮT BUỘC** hạ nó về giá
+  trị "chưa biết" (`not_run` / `—`). Giữ một `pass` đã hết hiệu lực là **báo cáo sai**, không phải
+  tôn trọng quyền sở hữu.
+  *Tiền lệ đúng có sẵn: `/fix-bug` hạ `dev_selftest → not_run` với lý do "code vừa đổi nên tín
+  hiệu self-test cũ hết hiệu lực". Cùng lý do đó áp cho MỌI lệnh làm đổi spec hoặc code.*
+  **Ngoại lệ có chủ ý:** `qc_owner`/`qc_blocked_by` (con trỏ tới bug — spec đổi không làm bug biến
+  mất) và `test_count`/`test_classes` (test vẫn tồn tại trên đĩa; số lượng không sai, chỉ nội dung
+  cũ → **cảnh báo**, không hạ số, để tỷ lệ coverage không nhảy loạn).
+- **Mỗi audit flag phải quan sát được ở CẢ BA tầng.** Mọi giá trị trong
+  `vocabularies.audit_flags` bắt buộc có đủ: **(1)** một counter `{flag_lowercase}_count`
+  trong Step 7 + `summary` của `trace-report.json` · **(2)** một mảng trong `issues` ·
+  **(3)** một khối trong report terminal. Thiếu tầng nào = cờ vô hình ở tầng đó.
+  `bin/self-check.js` R7 ép tầng (1) — **không có ngoại lệ**. Đây là hình dạng của G33:
+  7/10 cờ có counter, 3 cái không, nên dashboard (chỉ đọc `summary`) không tổng hợp
+  được — và bất đối xứng 7/10 là bẫy cho người viết dashboard: đọc `summary` rồi tưởng đủ.
+
 ## Code Generation
 
 - Never generate code for files not backed by a `.feature` spec (unless `/fix-bug` or `/debug`).

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

@@ -34,7 +34,7 @@ Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **pha
 | Phase | Commands |
 |-------|----------|
 | Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| PRD | `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` (PRD) |
 | Design Spec | `/generate-design-spec` |
 | BDD | `/generate-bdd` · `/review-context` (BDD) |
 | Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
@@ -59,6 +59,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
+| /extend-prd             | `/refine-prd {prd-file}` (soi phần vừa thêm) rồi `/review-context {prd-file}` → PO duyệt → `/generate-bdd` **chỉ cho UC MỚI**; UC cũ dùng `/validate-traces --realign-prd-version {UC-ID}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
 | /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
@@ -71,6 +72,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,11 +81,11 @@ 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/` |
+| /propose-scenario       | **Case A** (thiếu scenario cho AC có sẵn) → báo PO/Dev review trong `feedback/bdd-proposals/`; `/generate-bdd` tự chèn khi `Status: accepted`. **Case B** (requirement mới) → `feedback/prd-change-requests/` — PO phải đưa vào PRD trước, KHÔNG tự vào BDD được; `/validate-traces` nhắc lại kèm số ngày chờ chừng nào `Status: Open` |
 | /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
 | /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
 | /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |

package/core/steps/trace-mirror.md

@@ -1,7 +1,31 @@
-# Làm mới panel mirror của Living Docs *(local, chế độ umbrella)*
+# Làm mới panel mirror của Living Docs *(local)*
 
-*Bỏ qua hoàn toàn ở chế độ single-service (không có `services` và không có `setup.spec_source`) — ở đó
-`.trace/` của chính repo CHÍNH LÀ vị trí panel, nên không có gì để mirror.*
+> **Hai vị trí, HAI TÊN KHÁC NHAU — đọc trước khi sửa gì ở đây.**
+>
+> | Đường dẫn | Vai trò | Git |
+> |---|---|---|
+> | `{paths.trace_dir}` (`.trace/` hoặc `{spec_source}/.trace/`) | **AUTHORITATIVE** — TSV + `trace-history.jsonl`. Không regenerate được. | **PHẢI commit** |
+> | `./.trace-mirror/` ở gốc workspace hiện tại | **MIRROR** — bản sao tiện cho panel VS Code. Sinh lại được bất cứ lúc nào. | **Luôn gitignore** |
+>
+> Trước v0.4.3 cả hai đều tên `.trace`, nên một luật gitignore theo tên có thể **xoá sạch sổ gốc**
+> khi dev mở thẳng spec repo làm workspace (lúc đó hai path bằng nhau). Hai tên khác nhau làm
+> luật git đọc được bằng mắt và **không còn ca nhập nhằng nào**: `.trace-mirror/` không bao giờ
+> commit, `.trace/` không bao giờ gitignore.
+
+## Khi nào CÓ mirror
+
+Mirror chỉ tồn tại khi **`{paths.trace_dir}` nằm NGOÀI workspace hiện tại** — panel đọc từ workspace đang mở nên cần một bản sao ở đây.
+
+| Tình huống | `{paths.trace_dir}` | Có mirror? |
+|---|---|---|
+| Single-service | `./.trace` — **trong** workspace | ❌ Không. Panel đọc thẳng `.trace/trace-report.json`. Bỏ qua cả file này. |
+| Dev mở thẳng **spec repo** | `./.trace` — **trong** workspace | ❌ Không. Như trên. |
+| Umbrella + `spec_source`, dev đứng ở umbrella hoặc service submodule | `{spec_source}/.trace` — **ngoài** workspace | ✅ Có |
+| Umbrella legacy (không `spec_source`) | `.trace` theo từng service | ✅ Có |
+
+Quy tắc một dòng: **phân giải `panel_mirror = ./.trace-mirror` ở gốc workspace hiện tại; nếu `{paths.trace_dir}` đã nằm trong workspace này thì bỏ qua toàn bộ bước mirror.**
+
+---
 
 Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 
@@ -9,11 +33,14 @@ Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 `{paths.trace_dir}` phân giải về `{spec_source}/.trace` — vị trí authoritative duy nhất.
 Lệnh này chạy từ `service_root`, nên thao tác ghi là **liên-repo vào spec submodule**;
 commit/push spec submodule cho lần cập nhật trace (giống như `feedback/`).
-1. Phân giải `panel_mirror = ./.trace` tại **gốc workspace hiện tại**.
-2. Nếu `panel_mirror` phân giải ra path khác với `{paths.trace_dir}`, copy mỗi
+
+1. Phân giải `panel_mirror = ./.trace-mirror` tại **gốc workspace hiện tại**.
+2. Nếu `{paths.trace_dir}` **không** nằm trong workspace hiện tại, copy mỗi
    `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{UC-ID}-{platform}.tsv` (tạo thư mục; ghi đè).
-   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang trong
-   `@trace.service` của từng row.
+   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang ở
+   **cột `service` (cột 23)** của chính từng row, do `/generate-bdd` ghi từ `@trace.service`.
+3. **KHÔNG copy `trace-history.jsonl`.** Nó là dữ liệu tích luỹ, không phải thứ sinh lại được —
+   nhân bản nó ra một thư mục gitignore là tạo hai lịch sử lệch nhau rồi mất bản thật.
 
 **Legacy (không có `spec_source` — trace theo service):**
 Copy mỗi `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{service-name}/{UC-ID}-{platform}.tsv`

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,18 +1,18 @@
 # ============================================================
 # @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.service: {active_service — bỏ trong spec repo 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ẮT BUỘC mọi mode. "—" ở single-service/spec repo mode; "multi" nếu chưa chốt; "unresolved" nếu routing sai. Nguồn của cột TSV `service` — trace gộp không tách theo service nên đây là chỗ DUY NHẤT mang thông tin sở hữu}
 # @trace.module: {active_module trong umbrella mode; "unknown" trong spec repo mode}
 # @trace.status: draft
 # @trace.author: AI-generated
 # @trace.created_at: {YYYY-MM-DD}
 # @trace.prd: {TICKET-ID}
 # @trace.prd_version: {đọ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,7 +145,7 @@ 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.
 #

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/01-getting-started/installation.md

@@ -77,12 +77,29 @@ AI *follow* các file này — để trống thì nó *đoán*:
 
 | Lệnh | Việc | Ghi đè | KHÔNG đụng |
 |------|------|--------|-----------|
-| `/update-framework` | Sync bản npm mới | `.agent/commands\|steps\|hooks\|rules\|templates\|skills\|modules` | `CLAUDE.md`, `project-context.yaml`, `domain-knowledge/`, `.trace/` |
+| `/update-framework` | Sync bản npm mới | `.agent/commands\|steps\|hooks\|rules\|templates\|skills\|modules` | `CLAUDE.md`, `.agent/project-context.yaml`, `.agent/project-lessons.md`, `.agent/review/`, `domain-knowledge/`, `.trace/`, `feedback/` |
 | `/sync` (umbrella) | Pull + init submodule + nổi feedback + Living Docs | — | — |
 
 Kiểm tra version mới nhất: `npm view @educa-corp/sdd-framework version`.
 
 > **Quy tắc edit (critical):** `.tmpl` + `steps/` là source of truth. Sửa framework artifact phải sửa `.tmpl`/`steps` rồi `node bin/build.js`. Sửa thẳng `.agent/commands/*.md` sẽ **mất** khi rebuild/update.
+>
+> Từ v0.4.2, nâng cấp **cứu** file bạn đã sửa trong vùng ghi đè: bản cũ lưu ở `.agent/.overwritten-{version}-{date}/` và danh sách được in ra. Ranh giới vùng-sửa-được đầy đủ: `.agent/README.md`. Chi tiết cơ chế: [Configuration › Vùng nào bị ghi đè](../04-reference/configuration.md#vùng-nào-bị-ghi-đè-khi-update).
+
+### Migration bố cục spec
+
+Một số version đổi **bố cục** chứ không chỉ nội dung lệnh. `/update-framework` Step 5.5 tự quét và nhắc, hoặc chạy tay (đều **dry-run mặc định**, thêm `--apply` để thực thi):
+
+| Lệnh | Khi nào cần |
+|---|---|
+| `--migrate-bdd-platform` | Có `.feature` nằm **trực tiếp** dưới `bdd/` (bố cục phẳng trước v0.4.1) → chuyển sang `bdd/{platform}/`. Bố cục phẳng làm `web`/`system` cùng UC **va tên và ghi đè nhau**. |
+| `--migrate-specs` | Còn `specs/prd/` hay `specs/bdd/` ở cấp gốc (bố cục artifact-type-first rất cũ) |
+| `--rename-prd-files` | PRD còn tên cố định `prd.md` thay vì `{TICKET-ID}-{prd-slug}.md` |
+
+```bash
+npx @educa-corp/sdd-framework --migrate-bdd-platform          # xem plan
+npx @educa-corp/sdd-framework --migrate-bdd-platform --apply  # thực thi
+```
 
 ---
 

package/docs/01-getting-started/what-is-sdd.md

@@ -26,8 +26,10 @@ Dùng AI tự do (mở chat, gõ prompt, copy-paste) → AI suy diễn theo tr
 | Vấn đề | Cách giải |
 |--------|-----------|
 | AI viết lung tung, không bám requirement | Spec là **anchor cứng**; code link `@trace.source` về scenario |
-| Sửa code → spec lệch → AI hiểu sai lần sau | **Spec là single source of truth**; code không lưu version riêng |
-| Sửa spec → không biết code nào cần regen | **Trace state `.tsv` per-UC** → phát hiện OK/GAP/DRIFT/UNTRACKED |
+| Sửa code → spec lệch → AI hiểu sai lần sau | **Spec là SSOT của "bản hiện tại"**; code mang version của "bản tôi được sinh theo" — **lệch nhau chính là tín hiệu drift** |
+| Sửa spec → không biết code nào cần regen | **Trace state `.tsv`** một sổ / UC × platform → `OK`/`GAP`/`DRIFT`/`UNTRACKED`/`ORPHANED` |
+| Xoá scenario → code mồ côi nằm im | **Quét ngược code → spec**; code trỏ vào SC không còn tồn tại bị gắn cờ 🔴, không tự hết |
+| Build xanh nhưng ghép luồng chạy vào no-op | **Sổ seam/stub** — bắt lớp lỗi mà build + test từng-UC không thấy |
 | PRD/BDD kém → code rác hàng loạt | **Quality gate** (`/review-context`) phải sạch critical + PO approve |
 | Lỗi/định hướng sai lặp lại | **`/learn`** ghi lesson, nạp lại vào context |
 | Đổi tech stack → viết lại workflow | **Module overlay** — skill đọc `stack-profile.yaml`, không hardcode |

package/docs/02-concepts/architecture.md

@@ -62,13 +62,37 @@ Spec-driven thành/bại phụ thuộc **~80%** vào việc context được n
 
 ```
 .tmpl (source) + steps/*.md  --[node bin/build.js, {{include:...}}]-->  commands/*.md + core/
-                                                                              │
-                                                                              ▼
-                                                              .agent/commands/*.md (runtime)
+                                     │                                        │
+                                     │  templates/*.template* cũng được inline │
+                                     ▼                                        ▼
+                        bin/self-check.js (fail build)      .agent/commands/*.md (runtime)
 ```
 
 - Cơ chế `{{include:steps/...}}` ghép phẳng → single source of truth ở `.tmpl` + `steps/`.
 - **Không sửa tay** `commands/*.md` / `.agent/` — sửa `.tmpl`/`steps` rồi `node bin/build.js`. *(Quy ước + memory bảo vệ, không phải hook.)*
+- **Template artifact cũng bị inline lúc build.** `templates/feature.template` và `prd.template.md` được `{{include}}` **nướng cứng** vào file lệnh, nên lệnh không đọc path template lúc chạy — sửa `.agent/templates/` **không có tác dụng**. Đổi cấu trúc `.feature`/PRD = sửa `templates/*` trong repo framework rồi build lại.
+
+### Self-check — contract trace không được lệch
+
+```
+bin/trace-schema.json  ──[bin/self-check.js]──>  đối chiếu commands/*.tmpl + steps/*.md
+   (SoT máy đọc)                                 → exit 1 nếu lệch → build FAIL
+```
+
+**Vì sao cần:** phần lớn lỗi lịch sử của framework là **cùng một dạng** — contract (field `@trace.*`, cột `.tsv`, path pattern, giá trị enum) được phát biểu lại bằng **prose** ở nhiều lệnh rồi lệch nhau qua từng lần sửa, và không có gì phát hiện. Ca thuần khiết nhất: `@trace.sc_version` từng có **3 consumer, 0 producer** — nghĩa là `DRIFT` chết hoàn toàn — mà không lệnh nào, cổng nào, test nào bắt được.
+
+| Rule | Bắt gì | Mức |
+|:---:|---|:---:|
+| R1 | field có consumer nhưng **không producer** | ERROR |
+| R2 | field có producer nhưng **không ai đọc** (field chết) | WARN |
+| R3 | actor khai trong schema mà file của nó **không nhắc** field | ERROR |
+| R4 | `{paths.X}` dùng mà không khai / khai mà không ai dùng | ERROR / WARN |
+| R5 | pattern bị cấm **quay lại** (vd `bdd/` thiếu `{platform}`) | ERROR |
+| R6 | giá trị enum khai mà **không xuất hiện ở đâu** | WARN |
+
+**Quy tắc vận hành:** đổi contract → sửa `bin/trace-schema.json` **TRƯỚC**, rồi mới sửa lệnh, rồi cập nhật [Trace Schema (người đọc)](../04-reference/trace-schema.md). Chạy riêng: `npm run self-check`.
+
+*(Schema là JSON chứ không YAML vì `package.json` có **zero dependency** — npx chạy không cần install; thêm `js-yaml` chỉ để đọc một file build-time là không đáng. Nó nằm ở `bin/` chứ không `templates/` để không lọt vào `.agent/templates/` của mọi project.)*
 
 ---