@educa-corp/sdd-framework 0.4.2 → 0.5.0

package/package.json

@@ -1,50 +1,50 @@
-{
-  "name": "@educa-corp/sdd-framework",
-  "version": "0.4.2",
-  "description": "Spec Driven Development workflow framework for Claude Code",
-  "bin": {
-    "sdd-framework": "./bin/index.js"
-  },
-  "scripts": {
-    "build": "node bin/build.js && node bin/self-check.js",
-    "prepublishOnly": "node bin/build.js && node bin/self-check.js",
-    "pub": "npm publish --access=public",
-    "dev": "node bin/build.js && node bin/index.js --init",
-    "prepack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync(f)) fs.renameSync(f,'__'+f); });\"",
-    "postpack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync('__'+f)) fs.renameSync('__'+f,f); });\"",
-    "self-check": "node bin/self-check.js"
-  },
-  "files": [
-    "bin/",
-    "commands/",
-    "core/",
-    "hooks/",
-    "modules/",
-    "rules/",
-    "scripts/",
-    "skills/",
-    "steps/",
-    "templates/",
-    "docs/"
-  ],
-  "keywords": [
-    "claude-code",
-    "spec-driven",
-    "ai-first",
-    "bdd",
-    "traceability",
-    "workflow"
-  ],
-  "author": "duclm2 <duclm2@edupia.com.vn>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/duclm2/sdd-framework"
-  },
-  "engines": {
-    "node": ">=14"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@educa-corp/sdd-framework",
+  "version": "0.5.0",
+  "description": "Spec Driven Development workflow framework for Claude Code",
+  "bin": {
+    "sdd-framework": "./bin/index.js"
+  },
+  "scripts": {
+    "build": "node bin/build.js && node bin/self-check.js",
+    "prepublishOnly": "node bin/build.js && node bin/self-check.js",
+    "pub": "npm publish --access=public",
+    "dev": "node bin/build.js && node bin/index.js --init",
+    "prepack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync(f)) fs.renameSync(f,'__'+f); });\"",
+    "postpack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync('__'+f)) fs.renameSync('__'+f,f); });\"",
+    "self-check": "node bin/self-check.js"
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "core/",
+    "hooks/",
+    "modules/",
+    "rules/",
+    "scripts/",
+    "skills/",
+    "steps/",
+    "templates/",
+    "docs/"
+  ],
+  "keywords": [
+    "claude-code",
+    "spec-driven",
+    "ai-first",
+    "bdd",
+    "traceability",
+    "workflow"
+  ],
+  "author": "duclm2 <duclm2@edupia.com.vn>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/duclm2/sdd-framework"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/rules/workflow.md

@@ -28,6 +28,24 @@
   `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
 

package/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}` |
@@ -84,7 +85,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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/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/templates/feature.template

@@ -4,7 +4,7 @@
 # @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Ắ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.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