@educa-corp/sdd-framework 0.7.2 → 0.7.4

package/bin/index.js

@@ -5,6 +5,21 @@ const path = require('path');
 
 const ROOT = path.join(__dirname, '..');
 
+// NGUỒN ASSET ĐỂ CÀI — luôn là `core/`, không bao giờ là dir ở gốc.
+//
+// `core/` là bản dựng sẵn và là thứ DUY NHẤT được ship (package.json → files:
+// bin/ core/ scripts/ docs/). Các dir `modules/`, `hooks/`, `steps/`, `templates/`,
+// `rules/`, `skills/` ở gốc là NGUỒN BUILD — chúng chỉ tồn tại trong dev checkout.
+//
+// Vì sao khai một hằng số cho việc này (hồi quy 0.7.0 / G59): đợt dọn tập publish bỏ
+// `modules/` + `hooks/` khỏi `files`, nhưng BA chỗ trong file này vẫn đọc
+// `path.join(ROOT, 'modules'|'hooks')`. Trong dev checkout chúng vẫn có nên test và
+// `npm run build` đều xanh; trong tarball thì KHÔNG, và `--module` crash cứng bằng
+// ENOENT giữa `--init` — chết TRƯỚC bước `--hooks`, nên một cờ hỏng làm chết cờ kia và
+// project bị cài dở (thiếu .claude/settings.json).
+// Test `bin/ chỉ đọc dir CÓ trong package.json files` canh việc này từ nay.
+const CORE_DIR = path.join(ROOT, 'core');
+
 const pkg      = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
 const VERSION  = pkg.version;
 
@@ -14,6 +29,12 @@ const VERSION  = pkg.version;
 // of this file is evaluated, and `const` does not hoist.
 const MANIFEST_NAME = '.install-manifest.json';
 
+// Asset được YÊU CẦU tường minh (--module, --hooks, module của service) mà bản cài không
+// có. Gom lại thay vì crash giữa `--init`: crash để lại project cài DỞ — đúng ca hồi quy
+// 0.7.0, nơi ENOENT ở bước --module làm bước --hooks không bao giờ chạy. Nhưng cũng KHÔNG
+// im lặng: exit 1 ở cuối, vì người dùng đã xin thứ họ không nhận được.
+const assetErrors = [];
+
 const args = process.argv.slice(2);
 const isMigrateSpecs = args.includes('--migrate-specs');
 const isMigrateBddPf = args.includes('--migrate-bdd-platform');
@@ -301,11 +322,20 @@ if (isInit) {
       console.log(`⚠️  Unknown module: "${moduleName}"`);
       console.log(`   Available: ${AVAILABLE_MODULES.join(', ')}`);
     } else {
-      const srcModuleDir  = path.join(ROOT, 'modules', moduleName);
+      const srcModuleDir  = path.join(CORE_DIR, 'modules', moduleName);
       const destModuleDir = path.join(agentDir, 'modules', moduleName);
-      fs.mkdirSync(destModuleDir, { recursive: true });
-      copyDirRecursive(srcModuleDir, destModuleDir);
-      console.log(`✅ Module "${moduleName}" installed to: .agent/modules/${moduleName}`);
+      // Guard TRƯỚC khi copy. Bản cũ gọi thẳng copyDirRecursive và ENOENT làm chết cả
+      // `--init` giữa đường — bước `--hooks` ngay dưới không bao giờ chạy, project bị cài
+      // dở. Một cờ hỏng không được phép làm chết cờ khác.
+      if (!fs.existsSync(srcModuleDir)) {
+        console.log(`❌ Module "${moduleName}" không có trong bản cài: ${path.relative(ROOT, srcModuleDir)}`);
+        console.log(`   Bản cài thiếu/hỏng — cài lại, hoặc xoá cache npx rồi chạy lại.`);
+        assetErrors.push(`module ${moduleName}`);
+      } else {
+        fs.mkdirSync(destModuleDir, { recursive: true });
+        copyDirRecursive(srcModuleDir, destModuleDir);
+        console.log(`✅ Module "${moduleName}" installed to: .agent/modules/${moduleName}`);
+      }
     }
   }
 
@@ -440,12 +470,18 @@ if (isInit) {
         if (!AVAILABLE_MODULES.includes(svc.module)) {
           console.log(`  ⚠️  Unknown module "${svc.module}" — skipped`);
         } else {
-          const srcMod  = path.join(ROOT, 'modules', svc.module);
+          const srcMod  = path.join(CORE_DIR, 'modules', svc.module);
           const destMod = path.join(svcAgentDir, 'modules', svc.module);
           if (fs.existsSync(srcMod)) {
             fs.mkdirSync(destMod, { recursive: true });
             copyDirRecursive(srcMod, destMod);
             console.log(`  ✅ ${svc.name}/.agent/modules/${svc.module}/`);
+          } else {
+            // Bản cũ bỏ qua ÂM THẦM ở đây: người dùng khai module cho service, không nhận
+            // được gì, và không dòng nào báo. Cùng nguồn lỗi với ca --module ở trên nhưng
+            // hỏng theo hướng im lặng — tệ hơn.
+            console.log(`  ❌ ${svc.name}: module "${svc.module}" không có trong bản cài`);
+            assetErrors.push(`${svc.name}/module ${svc.module}`);
           }
         }
       }
@@ -577,6 +613,12 @@ if (isInit) {
   console.log('To upgrade later:  /update-framework   (trong Claude Code)');
   console.log('                   (or: npx @educa-corp/sdd-framework@latest --init)');
   console.log('');
+  if (assetErrors.length) {
+    console.log('');
+    console.log(`❌ ${assetErrors.length} asset được yêu cầu nhưng bản cài không có: ${assetErrors.join(' · ')}`);
+    console.log('   Phần còn lại của --init đã hoàn tất — nhưng exit 1 vì bạn đã xin thứ không nhận được.');
+    process.exit(1);
+  }
   process.exit(0);
 }
 
@@ -963,7 +1005,7 @@ function installDataGuardHook() {
 
   // 1. Copy hook script
   fs.mkdirSync(hooksDir, { recursive: true });
-  const srcHook  = path.join(ROOT, 'hooks', 'data-guard.js');
+  const srcHook  = path.join(CORE_DIR, 'hooks', 'data-guard.js');
   const destHook = path.join(hooksDir, 'data-guard.js');
   fs.copyFileSync(srcHook, destHook);
   console.log(`  ✅ Hook copied to: .claude/hooks/data-guard.js`);

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.2
+0.7.4

package/package.json

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