@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/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/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/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