@educa-corp/sdd-framework 0.3.0 → 0.4.2

package/docs/04-reference/trace-schema.md

@@ -4,54 +4,100 @@
 
 > Field metadata `@trace.*` và cột file `.tsv`. Giải thích khái niệm → [Traceability](../02-concepts/traceability.md).
 
+> ⚙️ **Bản máy đọc: `bin/trace-schema.json`.** File đó là nguồn-sự-thật mà `bin/self-check.js`
+> đối chiếu với `commands/*.tmpl` + `steps/*.md` mỗi lần `npm run build` — build **fail** nếu
+> lệnh lệch schema. Đổi contract thì sửa file JSON **trước**, rồi sửa lệnh, rồi cập nhật trang này.
+
 ---
 
 ## Trace tags theo artifact
 
-### BDD scenario (`.feature`)
+### BDD — header file (`.feature`)
+
+| Tag | Ý nghĩa | Bắt buộc |
+|-----|---------|:--------:|
+| `@trace.id` | UC-ID — `{TICKET-ID}-UC{N}` (vd `SEG01-UC1`) | ✅ |
+| `@trace.platform` | `web` / `app` / `system` — **mọi mode, kể cả umbrella** | ✅ |
+| `@trace.domain` | Domain nghiệp vụ | ✅ |
+| `@trace.prd` | TICKET-ID của PRD nguồn | ✅ |
+| `@trace.prd_version` | Version PRD lúc sinh BDD | ✅ |
+| `@trace.bdd_version` | Version **cả file** — tăng 0.1 mỗi lần gen lại / `--fix` | ✅ |
+| `@trace.status` | `draft` / `in-review` / `approved` — cổng duyệt BDD | ✅ |
+| `@trace.title` · `@trace.revision` · `@trace.author` · `@trace.created_at` · `@trace.business_rules` · `@trace.dataset` | thông tin | ⚪ |
+| `@trace.service` · `@trace.module` | chỉ **umbrella mode**; vắng ở spec repo mode là đúng | ⚪ có điều kiện |
+| `@trace.api_source` | `existing` — chỉ khi `platform = system` và PRD brownfield | ⚪ có điều kiện |
+
+> **`@trace.platform` là field load-bearing nhất.** Thiếu nó: `/generate-code` không quyết được BE/FE (và **cấm** fallback sang `platform_type`), không định vị được sổ trace `{UC-ID}-{platform}.tsv`, không tìm được design-spec. Nó phải **khớp** segment `{platform}` của đường dẫn file.
+
+### BDD — mỗi scenario
 
 | Tag | Ý nghĩa |
 |-----|---------|
-| `@trace.id` | UC-ID (vd `UC-02`) |
-| `@trace.scenario` | SC-ID (vd `SC-02.1`) |
-| `@trace.business_rules` | BR liên quan (vd `BR-03`) |
-| `@trace.bdd_version` | Version của `.feature` (phát hiện drift) |
-| `@trace.prd_version` | Version PRD nguồn |
-| `@trace.status` | `draft` / `in-review` / `approved` (gate) |
-| `@trace.platform` | `web` / `app` / `system` |
-| `@trace.domain` | Domain nghiệp vụ |
+| `@trace.scenario` | SC-ID — `{UC-ID}-SC{N}` (vd `SEG01-UC1-SC3`) |
+| **`@trace.sc_version`** | Version **của riêng scenario này**. Tăng 0.1 khi **thân SC** đổi (tên · step · data table · side-effect). |
+| `@trace.business_rules` | BR liên quan — `{TICKET-ID}-UC{N}-BR{m}` |
+
+> **`sc_version` vs `bdd_version`:** `sc_version` là tín hiệu **duy nhất** cho `DRIFT` (`spec_ver != gen_ver`). `bdd_version` bắt thay đổi cấp file mà `sc_version` không thấy (Background, dataset, Business Definition, Coverage Matrix). Quên bump `sc_version` = code sinh từ scenario cũ **vĩnh viễn** hiện `OK`.
 
-### Code (boundary only)
+### Code — entry-point (boundary only)
+
+```java
+// @trace.implements=SEG01-UC1-SC3
+// @trace.prd_version=1.2
+// @trace.bdd_version=1.4
+// @trace.tech_doc_revision=3
+// @trace.source=specs/segment/scoring/bdd/system/SEG01-UC1-scoring.feature
+public ScoreDto calculate(...) { }
+```
 
 | Tag | Ý nghĩa |
 |-----|---------|
 | `@trace.implements` | SC mà method này hiện thực |
-| `@trace.source` | `.feature` nguồn |
+| `@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision` | version của từng artifact upstream **tại thời điểm codegen** — nguồn của `PRD_DRIFT` / `BDD_DRIFT` / `TECHDOC_DRIFT` |
+| `@trace.source` | `.feature` nguồn — **phải gồm segment `{platform}`** |
+
+> **File phủ nhiều UC → lặp CẢ BLOCK theo từng method.** Không gộp về một header file, không trỏ thư mục. 3 tag version là scalar **theo từng UC**; gộp lại thì không diễn đạt được "UC1 ở bdd v1.4, UC3 ở v2.1" → drift báo oan hoặc mù. Và các lệnh tra tag bằng **khớp chuỗi chính xác**, nên `@trace.source` trỏ thư mục sẽ ra 0 kết quả → UC rơi về `UNTRACKED` dù code đã có.
+
+### Code — chỗ chưa implement (sổ `_seams.tsv`)
 
-> **KHÔNG** lưu version trong code — tránh dual SSOT. Version dò qua `.tsv`.
+| Tag | Đặt ở đâu | Ý nghĩa |
+|-----|---|---------|
+| `@trace.stub` · `@trace.stub_owner` · `@trace.stub_for` | method trắng | logic thuộc BDD **khác của cùng feature** — ai để trắng / ai sẽ lấp / trách nhiệm gì |
+| `@trace.seam_pending` · `@trace.seam_port` | class stub | port **cross-UC** do UC khác sở hữu, hàng thật chưa có |
 
 ### Test
 
 | Tag | Ý nghĩa |
 |-----|---------|
-| `@trace.verifies` | SC mà test kiểm chứng (vd `UC-02-SC1`) |
-| `@trace.covers` | Phạm vi phủ |
+| `@trace.verifies` | SC mà test kiểm chứng — `{UC-ID}-SC{N}` |
 
 ### Bug fix
 
 | Tag | Ý nghĩa |
 |-----|---------|
-| `@trace.fixes` | Bug/ticket được sửa |
+| `@trace.fixes` | `{BUG-ID}` nếu fix từ bug report đã file, else TICKET_ID |
 | `@trace.root_cause` | Nguyên nhân gốc |
 | `@trace.regression` | Test regression thêm vào |
 
+### Tech-doc gộp (header, cấp PRD)
+
+| Tag | Ý nghĩa |
+|-----|---------|
+| `@trace.id` · `@trace.domain` · `@trace.prd` | định danh |
+| `@trace.ucs` | **danh sách** UC mà doc này phủ |
+| `@trace.platforms` | platform có mặt |
+| `@trace.bdd_versions` | **map theo platform** (`system=1.5, web=1.9`). Tên **số nhiều** để phân biệt với `@trace.bdd_version` (scalar) của `.feature` — cùng tên cho hai kiểu dữ liệu sẽ làm vỡ parser generic. |
+| `@trace.revision` | integer, bump mỗi lần sửa — nguồn của `TECHDOC_DRIFT` |
+| `@trace.status` | `draft` / `in-review` / `approved` — cổng của `/generate-code` DS3 |
+| `@trace.api_source` | `existing` → chế độ reverse-document, bỏ cổng T7 |
+
 ---
 
 ## Boundary-only tagging
 
 | ✅ Tag | ❌ Không tag |
 |--------|-------------|
-| Controller · Handler · Middleware · Steps file | Entity · Repository · DTO · Interface · Base class |
+| Controller · Handler · Middleware · Consumer · Steps file | Entity · Repository · DTO · Interface · Base class |
 
 Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 
@@ -59,34 +105,79 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 
 ## Trace state — `.tsv`
 
-Đường dẫn: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (mỗi UC × platform một sổ; trong umbrella nằm ở spec repo).
+Đường dẫn: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` — **một sổ cho mỗi UC × platform** (`sc_id` chỉ độc nhất trong phạm vi đó; `web-SC1` và `system-SC1` là hai scenario khác nhau). Ở umbrella + `spec_source`, sổ nằm trong spec repo.
+
+**22 cột, tab-separated:**
+
+| # | Cột | Ý nghĩa | Chủ ghi |
+|---|-----|---------|---------|
+| 1 | `sc_id` | `{UC-ID}-SC{N}` | generate-bdd |
+| 2 | `sc_title` | tiêu đề scenario | generate-bdd |
+| 3 | `spec_ver` | gương của `@trace.sc_version` hiện tại | generate-bdd · validate-traces |
+| 4 | `gen_ver` | `spec_ver` **tại thời điểm codegen** | generate-code |
+| 5 | `implemented_by` | `{Class}.{method}` (`—` nếu chưa) | generate-code |
+| 6 | `test_count` | số test phủ SC | dev-gen-test · fix-bug |
+| 7 | `test_classes` | tên test class / describe | dev-gen-test · fix-bug |
+| 8 | `dev_selftest` | `pass`/`fail`/`not_run` — **dev tự chạy** | dev-run-test |
+| 9 | `dev_selftest_at` | ngày | dev-run-test |
+| 10 | `qc_status` | `pass`/`fail`/`skip`/`not_run` — **QC chính thức** | qc-run-test |
+| 11 | `qc_run_at` | ngày | qc-run-test |
+| 12 | `qc_owner` | SC đang chờ ai: `dev` / `po` | qc-run-test · report-bug |
+| 13 | `qc_blocked_by` | `BUG-{id}` / `GAP-{id}` | qc-run-test · report-bug |
+| 14 | `prd_version` | version PRD lúc sinh BDD | generate-bdd |
+| 15 | `bdd_version` | version `.feature` | generate-bdd · review-context |
+| 16 | `tech_doc_revision` | `@trace.revision` của tech-doc | generate-code · review-tech-docs |
+| 17 | `fe_tech_doc_revision` | revision lúc FE wire adapter thật (§4.5.4) | generate-code |
+| 18 | `prd_status` | gương của PRD Metadata `Status` | generate-bdd · validate-traces |
+| 19 | `uc_status` | gương của `@trace.status` (`.feature`) | generate-bdd · validate-traces |
+| 20 | `fe_phase` | `ui` / `integrated` / `—` | generate-code `--phase` |
+| 21 | `status` | tổng hợp — xem bảng dưới | validate-traces |
+| 22 | `last_updated` | `YYYY-MM-DD` | mọi lệnh ghi row |
+
+> `dev_selftest` (dev smoke) và `qc_status` (QC chính thức) là **hai tín hiệu riêng**, không bao giờ gộp. Cả hai **trực giao** với `status` — `status` đo *coverage*, chúng đo *kết quả chạy*.
+
+> Giá trị rỗng trong TSV là `—`. Khi xuất JSON: `implemented_by`→`null`, `test_count`→`0`, `test_classes`→`[]`, `tech_doc_revision`/`fe_tech_doc_revision`→`0`, `dev_selftest`/`qc_status`→`"not_run"`.
+
+---
+
+## Phân loại `status` (thứ tự ưu tiên, first-match-wins)
 
-| Cột | Chủ sở hữu | Ý nghĩa |
-|-----|-----------|---------|
-| `status` | `/generate-code`, `/validate-traces` | OK / GAP / DRIFT / UNTRACKED |
-| `implemented_by` | `/generate-code` | File code hiện thực SC (`—` nếu chưa) |
-| `spec_ver` | spec | Version spec hiện tại |
-| `gen_ver` | `/generate-code` | Version lúc sinh code (`—` nếu chưa) |
-| `test_count` | test | Số test phủ SC |
-| `dev_selftest` | `/dev-run-test` | Smoke của dev (pass/fail/`—`) |
-| `qc_status` | `/qc-run-test`, `/report-bug` | QC chính thức (pass/fail/gap) |
-| `bdd_version` | spec | Version BDD |
-| `last_updated` | nhiều | Mốc cập nhật |
+| # | Trạng thái | Điều kiện | Hành động |
+|---|-----------|-----------|-----------|
+| 0 | **ORPHANED** | SC **không còn trong `.feature`** nhưng `implemented_by != —` | Người quyết định: xoá code+test, hoặc đưa scenario trở lại |
+| 1 | **UNTRACKED** | `implemented_by == —` | `/generate-code` |
+| 2 | **DRIFT** | có code **và** `spec_ver != gen_ver` | regen **trước khi** test |
+| 3 | **GAP** | có code **và** `test_count == —`/`0` | `/dev-gen-test` |
+| 4 | **OK** | version khớp, có code, có test | đủ phủ |
+
+`code_coverage = (rows where implemented_by != —) / total_scs` — **`total_scs` loại row `ORPHANED`** (không còn là scope; tính vào sẽ bóp méo coverage vì thứ không ai cần implement).
+
+> **ORPHANED là Rule 0** vì 4 rule kia đều giả định scenario **còn tồn tại**. Để rule khác thắng thì mỗi giá trị route người dùng sang một lệnh vô nghĩa: `GAP`→sinh test cho SC không tồn tại · `DRIFT`→regen từ SC đã xoá · `OK`→cho tạo PR.
+>
+> **DRIFT xét trước GAP** vì `/generate-code` xử `GAP` = "skip codegen" còn `DRIFT` = "regenerate". Nếu GAP thắng, code lỗi thời bị bỏ qua và test lại sinh trên code cũ.
 
 ---
 
-## Phân loại coverage (thứ tự ưu tiên)
+## Cờ audit (không phải cột — do `/validate-traces` tính)
+
+| Cờ | Nguồn | Nghĩa |
+|---|---|---|
+| `PRD_DRIFT` | Step 4 | code mang `@trace.prd_version` cũ hơn PRD hiện tại |
+| `BDD_DRIFT` | Step 5c | code mang `@trace.bdd_version` cũ hơn `.feature` |
+| `TECHDOC_DRIFT` · `FE_TECHDOC_DRIFT` | Step 5 | code sinh từ revision tech-doc cũ hơn |
+| `TECHDOC_STALE_VS_BDD` | Step 5c | tech-doc dựng từ BDD cũ hơn `.feature` hiện tại |
+| `TRACE_ORPHAN` 🔴 | Step 2b | tag `@trace.implements`/`@trace.verifies` trỏ SC không tồn tại **và** không có row TSV |
+| `SEAM_UNWIRED` 🔴 | Step 5b | hàng thật đã có nhưng consumer còn wire vào stub |
+| `STUB_UNRESOLVED` 🔴 | Step 5b | method còn trắng dù owner đã gen / có hàm song song |
+| `SEAM_PENDING` · `STUB_PENDING` | Step 5b | owner UC chưa gen — **bình thường**, chỉ nhắc |
 
-| # | Trạng thái | Điều kiện |
-|---|-----------|-----------|
-| 1 | **UNTRACKED** | `gen_ver == —` |
-| 2 | **DRIFT** | `implemented_by != —` AND `spec_ver != gen_ver` |
-| 3 | **GAP** | `implemented_by != —` AND (`test_count == —` OR `0`) |
-| 4 | **OK** | `spec_ver == gen_ver` AND `implemented_by != —` AND `test_count > 0` |
+> 🔴 = **chặn PR**. Build xanh, test từng-UC xanh, coverage đẹp — nhưng luồng ghép chạy vào no-op hoặc code trỏ vào scenario đã bị xoá.
+
+---
 
-`code_coverage = (rows where implemented_by != —) / total_scs`
+## Xuất JSON cho panel
 
-> DRIFT xét **trước** GAP: code lỗi thời + chưa test + spec drift phải hiện DRIFT (regen) không phải GAP (skip).
+`trace-report.json` giữ enum `status` **đúng 4 giá trị** `OK`/`DRIFT`/`GAP`/`UNTRACKED` — VS Code extension "Spec Driven Docs Tools" sống ngoài repo framework và switch trên field này. Row `ORPHANED` xuất ra là `"status": "DRIFT"` + `"orphaned": true`; panel cũ hiện nó như DRIFT (đúng nghĩa, không im lặng), panel mới đọc `orphaned` để hiện nhãn riêng. **TSV giữ nguyên chữ `ORPHANED`** — TSV là nguồn-sự-thật.
 
 ---
 

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

@@ -1,49 +1,50 @@
-{
-  "name": "@educa-corp/sdd-framework",
-  "version": "0.3.0",
-  "description": "Spec Driven Development workflow framework for Claude Code",
-  "bin": {
-    "sdd-framework": "./bin/index.js"
-  },
-  "scripts": {
-    "build": "node bin/build.js",
-    "prepublishOnly": "node bin/build.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); });\""
-  },
-  "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.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"
+  }
+}

package/rules/workflow.md

@@ -18,6 +18,17 @@
 - 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).
+
 ## Code Generation
 
 - Never generate code for files not backed by a `.feature` spec (unless `/fix-bug` or `/debug`).