@educa-corp/sdd-framework 0.7.3 → 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/bin/self-check.js

@@ -1111,6 +1111,77 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
   }
 }
 
+// ── R15 — field nguy hiểm phải được DÙNG, không chỉ được NHẮC TÊN ─────────────
+//
+// R3 hỏi "file có nhắc tên field không". Đó là câu SAI cho những field mà trả lời sai
+// gây hại im lặng. Ca thật: schema khai cột `status` có read_by gồm dev-run-test và
+// qc-run-test; R3 xác nhận ✅ vì cả hai file CÓ nhắc `status` — trong đúng câu khai rằng
+// chúng "trực giao" với nó, tức CỐ Ý KHÔNG dùng. Số lần đọc thật: 0. Đó là G55, và R3
+// xác nhận contract bằng đúng câu văn đang phủ nhận contract.
+//
+// R15 KHÔNG thay R3 và KHÔNG áp cho mọi field — nó siết đúng danh sách khai ở
+// `strict_use_check.fields`. Lý do không siết toàn cục nằm ở `$comment` của khối đó;
+// tóm gọn: (a) 42 tag × 33 lệnh ⇒ báo oan ⇒ checker bị tắt ⇒ mất cả phần R3 bắt thật;
+// (b) file lệnh là VĂN XUÔI và văn xuôi CHÍNH LÀ chương trình, nên không tồn tại dấu
+// hiệu cú pháp tách "câu dùng giá trị" khỏi "câu nói về giá trị".
+//
+// Anchor = DÒNG BẢNG MARKDOWN, ngoài blockquote. Không phải heuristic tuỳ ý: framework
+// này viết mọi luật rẽ nhánh bằng bảng. Đã kiểm chứng trên bản dev-run-test TRƯỚC G55 —
+// R3 PASS, R15 FAIL — và trên bản hiện tại, cả 5 field trong danh sách đều PASS.
+{
+  const SUC = schema.strict_use_check;
+  if (SUC) {
+    if (SUC.anchor !== 'markdown_table_row') {
+      err('R15', `\`strict_use_check.anchor\` = "${SUC.anchor}" — R15 chỉ implement \`markdown_table_row\``,
+          'Đổi anchor trong schema mà không dạy R15 nghĩa là rule này im lặng theo một luật khác.');
+    }
+    if (!(SUC.fields || []).length) {
+      warn('R15', '`strict_use_check.fields` rỗng — rule không siết field nào',
+           'Khối tồn tại mà không khai field nào là một cái cổng không canh gì. Khai field khi\n'
+         + '        phát hiện nó nguy hiểm, đừng để danh sách trống.');
+    }
+
+    // Dòng bảng markdown, NGOÀI blockquote. Blockquote là chỗ của giải thích và trích dẫn
+    // lịch sử — hai thứ ĐƯỢC PHÉP nhắc tên field mà không dùng nó.
+    const isTableRow = (line) => {
+      const t = line.trim();
+      if (t.startsWith('>')) return false;
+      return (t.match(/\|/g) || []).length >= 2;
+    };
+
+    for (const entry of SUC.fields || []) {
+      if (!entry.why) {
+        err('R15', `\`strict_use_check.fields\` mục \`${entry.field}\` thiếu \`why\``,
+            'Một field được siết mà không nói VÌ SAO sẽ bị người sau coi là tuỳ ý và gỡ khỏi danh sách.');
+      }
+      for (const actor of entry.actors || []) {
+        const rel = schema.actors[actor] || `commands/${actor}.tmpl`;
+        const abs = path.join(ROOT, rel);
+        if (!fs.existsSync(abs)) {
+          err('R15', `\`strict_use_check\` khai actor \`${actor}\` — ${rel} không tồn tại`);
+          continue;
+        }
+        const text = fs.readFileSync(abs, 'utf8');
+        // Điều kiện tiên quyết: R3 phải pass trước. Nếu file không nhắc field CHÚT NÀO thì
+        // đó là việc của R3 — đừng báo hai lần cùng một chuyện bằng hai giọng khác nhau.
+        if (!mentions(text, entry.field)) continue;
+
+        const inDecision = text.split('\n').filter(isTableRow)
+          .some(l => mentions(l, entry.field));
+        if (!inDecision) {
+          err('R15', `${rel} nhắc \`${entry.field}\` nhưng KHÔNG ở một dòng bảng nào — nhắc tên, không phải dùng`,
+              `Vì sao siết field này: ${entry.why}\n`
+            + `        R3 đã pass (file CÓ nhắc tên). Nhưng framework viết mọi luật rẽ nhánh bằng\n`
+            + `        BẢNG, nên một field chỉ xuất hiện trong câu văn là dấu hiệu nó đang được\n`
+            + `        NÓI TỚI, không được DÙNG — đúng hình dạng G55, nơi câu "trực giao với\n`
+            + `        \`status\`" thoả mãn R3 trong khi chính nó khai là cố ý bỏ qua.\n`
+            + `        Sửa: đưa \`${entry.field}\` vào bảng quyết định của lệnh (điều kiện → hành động).`);
+        }
+      }
+    }
+  }
+}
+
 // ── report ────────────────────────────────────────────────────────────────────
 const tagCount = schema.tags.length;
 const colCount = schema.tsv_columns.length;

package/bin/trace-schema.json

@@ -1771,6 +1771,74 @@
       }
     ]
   },
+  "strict_use_check": {
+    "$comment": [
+      "R3 CANH 'CÓ NHẮC TÊN', KHÔNG CANH 'CÓ DÙNG'. Khối này siết đúng những field mà trả lời",
+      "sai gây hại IM LẶNG — và chỉ những field đó.",
+      "",
+      "R3 kiểm lời khai producer/consumer bằng cách tìm tên field trong file actor. Thấy → ✅.",
+      "Nhưng một file có thể chứa tên field vì nhiều lý do KHÔNG PHẢI 'đang dùng nó':",
+      "  1. câu tuyên bố CỐ Ý BỎ QUA — G55: /dev-run-test viết 'dev_selftest trực giao với",
+      "     `status`', tức chính câu đó khai rằng nó không dùng. R3 thấy chữ, đóng dấu ✅, và số",
+      "     lần đọc thật là 0. R3 xác nhận một contract bằng đúng câu văn đang phủ nhận contract.",
+      "  2. chú thích giải thích luật — R9(h): comment viết `scope.kind !== 'all'` trong khi code",
+      "     đã thành `false`.",
+      "  3. trích dẫn lịch sử — 'Bản cũ ghi cứng X'. Ca này HỢP LỆ và phải được phép tồn tại:",
+      "     framework cố ý giữ luật cũ để người sau biết luật mới chống cái gì.",
+      "  4. substring — `DRIFTED` chứa `DRIFT`. `mentions()` đã chặn được ca này (xem doc-comment",
+      "     của nó); ba ca trên thì không.",
+      "",
+      "VÌ SAO KHÔNG SIẾT R3 TOÀN CỤC — hai lý do, cái thứ hai là gốc:",
+      "  (a) R3 áp cho 42 tag + 24 cột × 33 lệnh. Siết toàn cục đẻ ra một loạt báo oan, và cái gì",
+      "      báo oan thì bị TẮT — rồi mất luôn phần R3 đang bắt thật (G5, G12, G13, G31, G32).",
+      "  (b) FILE LỆNH LÀ VĂN XUÔI, VÀ VĂN XUÔI CHÍNH LÀ CHƯƠNG TRÌNH. Với .js thì tách được code",
+      "      khỏi comment (`codeOf()`). Với .tmpl thì KHÔNG TỒN TẠI dấu hiệu cú pháp nào tách",
+      "      'câu chỉ dẫn dùng giá trị' khỏi 'câu nói về giá trị' — cả hai đều là câu tiếng Việt.",
+      "      Đây là tính chất của thiết kế framework, không sửa được bằng một rule.",
+      "",
+      "NÊN: opt-in, khoanh vùng. Cùng khuôn `positive_assertion_guards` và `checkpoint_levels` —",
+      "khai tường minh từng field nguy hiểm rồi để máy canh, thay vì một cú siết toàn cục.",
+      "",
+      "ANCHOR = DÒNG BẢNG MARKDOWN. Đây không phải heuristic tuỳ ý: framework này viết MỌI luật",
+      "rẽ nhánh bằng bảng — validate-traces Step 3 (`| Rule | Status | Điều kiện |`), gate.md Bước",
+      "3a (`| Mức | Lệnh nào |`), generate-code §Read Trace State (`| Status | Hành động |`),",
+      "dev-run-test §Guard (`| status của row | ghi gì |`). Một field được DÙNG để quyết định thì",
+      "nó xuất hiện trong bảng. Một field chỉ được NHẮC TỚI thì nằm trong câu văn.",
+      "Blockquote (`>`) bị loại: đó là chỗ của giải thích và trích dẫn lịch sử (ca 3 ở trên).",
+      "",
+      "KIỂM CHỨNG ANCHOR trên bản dev-run-test TRƯỚC G55: R3 PASS (lý do G55 sống được),",
+      "R15 FAIL. Và trên bản hiện tại: cả 8 field trong danh sách đều PASS — không báo oan."
+    ],
+    "anchor": "markdown_table_row",
+    "$anchor_note": "Dòng có ≥2 ký tự `|` sau khi trim, và KHÔNG bắt đầu bằng `>`. Khớp tên field theo ranh giới token (cùng hàm `mentions()` của R3) — nên `qc_status` KHÔNG thoả cho field `status`.",
+    "fields": [
+      {
+        "field": "status",
+        "actors": ["dev-run-test", "qc-run-test"],
+        "why": "G55 — đây là ca đã xảy ra thật. Không rẽ nhánh theo `status` thì hai lệnh ghi `pass` trên row `DRIFT`, tức dựng lại đúng tín hiệu `/generate-bdd` vừa hạ. Cờ NÓI DỐI, không phải cờ im lặng."
+      },
+      {
+        "field": "spec_ver",
+        "actors": ["generate-code"],
+        "why": "Một nửa của phép so sinh ra DRIFT. Không đọc thì `/generate-code` skip mọi row lỗi thời và không gì báo — spec đổi mà code không bao giờ theo."
+      },
+      {
+        "field": "gen_ver",
+        "actors": ["generate-code"],
+        "why": "Nửa còn lại. Thiếu một nửa thì phép so vô nghĩa, và nó vô nghĩa trong IM LẶNG."
+      },
+      {
+        "field": "implemented_by",
+        "actors": ["generate-code", "generate-bdd"],
+        "why": "Phân biệt UNTRACKED (chưa có code) với ORPHANED (code còn, spec mất). Đọc sai thì `/generate-bdd` xoá row của một scenario ĐÃ có code ⇒ method đó thành vô hình: không cờ nào, không report nào, mà vẫn được caller gọi."
+      },
+      {
+        "field": "test_count",
+        "actors": ["validate-traces"],
+        "why": "Quyết GAP vs OK. Không đọc thì mọi row có code đều thành OK ⇒ coverage báo xanh trên scenario chưa có một test nào."
+      }
+    ]
+  },
   "path_keys": {
     "$comment": "Key phải có trong templates/project-context.yaml VÀ được dùng bởi ít nhất một actor. Key khai mà không ai dùng = key chết (GAPS.md G17).",
     "config_file": "templates/project-context.yaml",

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.7.3
+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.3",
+  "version": "0.7.5",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"