@educa-corp/sdd-framework 0.7.4 → 0.7.5

package/bin/gate-trace.js

@@ -63,6 +63,18 @@ const NO_RECONCILE = argv.includes('--no-reconcile');
 const TRACE_DIRS   = flag('--trace', '.trace').split(',').map(s => s.trim()).filter(Boolean);
 const REPORT_ARG   = flag('--report', null);
 
+// Version của framework — IN RA MỌI LẦN CHẠY.
+//
+// Vì sao (báo cáo từ project thật): người dùng chạy `npx …@${SDD_VERSION} --lint-trace`
+// trong CI và KHÔNG có cách nào biết bản nào thật sự chạy. `npx` cache theo version, biến
+// CI có thể rỗng, và `.agent/FRAMEWORK_VERSION` chỉ nói bản ĐÃ CÀI chứ không nói bản đang
+// KIỂM. Nên câu "lỗi này sửa chưa?" không trả lời được từ log — đúng lúc cần nhất.
+// Một cổng quyết định PR nào được merge thì phải nói nó là ai.
+const FW_VERSION = (() => {
+  try { return require(path.join(__dirname, '..', 'package.json')).version; }
+  catch { return '?'; }
+})();
+
 const fails = [];
 const warns = [];
 const oks   = [];
@@ -434,7 +446,7 @@ if (AS_JSON) {
 }
 
 console.log('');
-console.log('Trace gate (bin/trace-schema.json → gate) ...');
+console.log(`Trace gate v${FW_VERSION} (bin/trace-schema.json → gate) ...`);
 console.log('');
 
 for (const o of oks) console.log(`  ✅ ${o}`);

package/bin/index.js

@@ -45,6 +45,10 @@ const isInit     = args.includes('--init');
 const isProject  = args.includes('--project');
 const installHooks = args.includes('--hooks');
 const showHelp   = args.includes('--help') || args.includes('-h');
+// `--version` / `-v` — trả lời "bản nào đang chạy?" bằng MỘT lệnh, không cần đoán.
+// Cần thiết vì `npx` cache theo version và biến CI có thể rỗng: `npx pkg@${VAR}` với VAR
+// rỗng thành `pkg@` ⇒ npm resolve về latest, và log không nói gì về việc đó.
+const showVersion = args.includes('--version') || args.includes('-v');
 
 // --module <name> flag
 const moduleIdx  = args.indexOf('--module');
@@ -97,8 +101,21 @@ const MODULE_STACK = {
   'phaser-game':      { language: 'TypeScript',    framework: 'Phaser 3' },
 };
 
+if (showVersion) {
+  // In cả hai: version package VÀ version của core/ dựng sẵn. Lệch nhau nghĩa là bản cài
+  // hỏng (index.js §corePrebuilt sẽ xử) — thấy được ở đây thì đỡ một vòng chẩn đoán.
+  let coreV = '(không có core/)';
+  try { coreV = fs.readFileSync(path.join(ROOT, 'core', 'FRAMEWORK_VERSION'), 'utf8').trim(); } catch {}
+  console.log(`@educa-corp/sdd-framework ${VERSION}`);
+  console.log(`  core/FRAMEWORK_VERSION : ${coreV}${coreV === VERSION ? '' : '   ⚠️ LỆCH — bản cài hỏng'}`);
+  process.exit(0);
+}
+
 if (showHelp) {
-  console.log('Usage: npx @educa-corp/sdd-framework [options]');
+  console.log(`Usage: npx @educa-corp/sdd-framework [options]        (v${VERSION})`);
+  console.log('');
+  console.log('');
+  console.log('  --version, -v             In version đang chạy (package + core/). Dùng để chắc `npx` không lấy bản cache.');
   console.log('');
   console.log('Install modes:');
   console.log('  --init                    Install framework to .agent/ + create shortcuts in .claude/commands/');

package/bin/lint-trace.js

@@ -53,6 +53,18 @@ const flag = (name, def) => {
   const i = argv.indexOf(name);
   return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : def;
 };
+// Version của framework — IN RA MỌI LẦN CHẠY.
+//
+// Vì sao (báo cáo từ project thật): người dùng chạy `npx …@${SDD_VERSION} --lint-trace`
+// trong CI và KHÔNG có cách nào biết bản nào thật sự chạy. `npx` cache theo version, biến
+// CI có thể rỗng, và `.agent/FRAMEWORK_VERSION` chỉ nói bản ĐÃ CÀI chứ không nói bản đang
+// KIỂM. Nên câu "lỗi này sửa chưa?" không trả lời được từ log — đúng lúc cần nhất.
+// Một cổng quyết định PR nào được merge thì phải nói nó là ai.
+const FW_VERSION = (() => {
+  try { return require(path.join(__dirname, '..', 'package.json')).version; }
+  catch { return '?'; }
+})();
+
 const WARN_ONLY = argv.includes('--warn-only');
 const AS_JSON   = argv.includes('--json');
 const TRACE_DIRS = flag('--trace', '.trace').split(',').map(s => s.trim()).filter(Boolean);
@@ -657,13 +669,14 @@ for (const dir of TRACE_DIRS) {
 if (AS_JSON) {
   console.log(JSON.stringify({
     ok: errors.length === 0,
+    framework_version: FW_VERSION,
     scanned, trace_dirs: foundDirs, git_state: _gitState, errors, warns, infos,
   }, null, 2));
   process.exit(errors.length && !WARN_ONLY ? 1 : 0);
 }
 
 console.log('');
-console.log('Lint trace (bin/trace-schema.json) ...');
+console.log(`Lint trace v${FW_VERSION} (bin/trace-schema.json) ...`);
 console.log('');
 
 if (!foundDirs.length) {

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.7.4
+0.7.5

package/core/templates/ci/trace-gate.gitlab-ci.yml

@@ -75,9 +75,15 @@ variables:
     - CHANGE_ME
 
   before_script:
-    # Hai dòng này tồn tại để bẫy 2 và 4 lộ ra NGAY, chứ không lộ ra dưới dạng dấu xanh sai.
+    # Ba dòng này tồn tại để bẫy 2, 4 và "npx lấy bản cache" lộ ra NGAY ở đầu log, chứ không
+    # lộ ra dưới dạng một dấu xanh sai.
     - node -v
     - git --version
+    # CHỨNG MINH version đã pin. `npx` cache theo version, và một biến CI rỗng làm
+    # `pkg@${SDD_VERSION}` thành `pkg@` ⇒ npm resolve về latest mà log không nói gì.
+    # Dòng này in ra version THẬT sẽ chạy — nếu nó khác SDD_VERSION thì bạn thấy ngay.
+    - echo "SDD_VERSION=${SDD_VERSION}"
+    - npx -y @educa-corp/sdd-framework@${SDD_VERSION} --version
 
 # ── 1+2. Cấu trúc sổ + cổng chặn cờ 🔴 ───────────────────────────────────────
 # Sổ trace 24 cột do LLM ghi tay: một dấu tab thiếu dồn mọi ô sang trái, ô `status`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"