@educa-corp/sdd-framework 0.9.1 → 0.9.3

package/bin/self-check.js

@@ -61,6 +61,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');   // R16(b) — băm file snapshot để đối chiếu base_sha
 
 const ROOT = path.join(__dirname, '..');
 const WARN_ONLY = process.argv.includes('--warn-only');
@@ -1182,6 +1183,151 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
   }
 }
 
+// ── R16 — snapshot upstream và framework không được trôi khỏi nhau trong im lặng ─
+//
+// Hai sự cố thật đã xảy ra trong lúc port bộ QC, và KHÔNG tầng nào bắt được:
+//
+// (1) 35 file skill QC bị xoá khỏi skills/. self-check ✅ · build ✅ 41/41 · .agent vẫn
+//     chạy được (mirror KHÔNG prune nên bản cũ còn nằm đó) — nhưng core/ thì rỗng, và
+//     bin/index.js prune sẽ CHỦ ĐỘNG xoá chúng ở project người dùng khi nâng cấp (đúng
+//     luật: có trong manifest + không còn ship + hash khớp). Ba tầng che nhau; hỏng chỉ
+//     lộ ở phía người dùng. → R16(d).
+//
+// (2) Một `upstream_sha` được GÕ BỪA vào frontmatter thay vì tính. Tự phát hiện, nhưng
+//     nếu lọt thì nó là BASE sai cho mọi lần merge ba chiều về sau — tức mọi lần đồng bộ
+//     sau đều đoán. Đây đúng loại việc con người không làm đáng tin bằng sự cẩn thận.
+//     → R16(b).
+//
+// (a) là cái quan trọng nhất về lâu dài: file upstream KHÔNG có entry trong bản đồ =
+// bị bỏ quên trong im lặng. `state: skipped` (có lý do) là câu trả lời hợp lệ; VẮNG MẶT
+// thì không. Cùng khuôn với `checkpoint_levels` và `strict_use_check`: khai tường minh
+// từng cái, rồi để máy canh — thay vì tin rằng ai đó sẽ nhớ.
+//
+// R16 tự bỏ qua nếu chưa có bin/qc-base-map.json (repo chưa port bộ QC) — không ép
+// mọi consumer phải có bản đồ này.
+{
+  const MAP_PATH  = path.join(ROOT, 'bin/qc-base-map.json');
+  const SNAP_DIR  = path.join(ROOT, 'upstream/qc-base');
+  const hasMap    = fs.existsSync(MAP_PATH);
+  const hasSnap   = fs.existsSync(SNAP_DIR);
+
+  // ── (d) lệnh qc-* trỏ vào skill nào thì skill đó phải tồn tại ────────────────
+  // Chạy ĐỘC LẬP với bản đồ: đây là lớp lỗi (1) ở trên, và nó không cần snapshot.
+  const SKILLS_QC = path.join(ROOT, 'skills/qc');
+  if (fs.existsSync(SKILLS_QC)) {
+    const cmdDir = path.join(ROOT, 'commands');
+    for (const f of fs.readdirSync(cmdDir).filter(n => /^qc-.*\.tmpl$/.test(n))) {
+      const txt = fs.readFileSync(path.join(cmdDir, f), 'utf8');
+      // `{paths.qc_skills_dir}/<đường dẫn>` — lấy phần sau dấu / đầu tiên
+      const refs = new Set();
+      for (const m of txt.matchAll(/\{paths\.qc_skills_dir\}\/([A-Za-z0-9._\/-]+)/g)) {
+        refs.add(m[1].replace(/[.,)`]+$/, ''));
+      }
+      for (const ref of refs) {
+        const abs = path.join(SKILLS_QC, ref);
+        if (!fs.existsSync(abs)) {
+          err('R16', `${f} trỏ vào \`{paths.qc_skills_dir}/${ref}\` — KHÔNG TỒN TẠI trong skills/qc/`,
+              'Lệnh vẫn chạy, vẫn ghi file, nhưng phân tích rỗng logic và KHÔNG cờ nào bật. ' +
+              'Khôi phục skill, hoặc sửa lệnh nếu đã cố ý bỏ.');
+        }
+      }
+    }
+  }
+
+  if (hasMap && hasSnap) {
+    let map;
+    try { map = JSON.parse(fs.readFileSync(MAP_PATH, 'utf8')); }
+    catch (e) { err('R16', `bin/qc-base-map.json không parse được: ${e.message}`); map = null; }
+
+    if (map) {
+      const entries = map.map || [];
+      const byUp = new Map(entries.map(e => [e.upstream, e]));
+
+      // liệt kê file snapshot thật
+      const walk = (dir, base = '') => {
+        let out = [];
+        for (const n of fs.readdirSync(dir)) {
+          const p = path.join(dir, n), rel = base ? `${base}/${n}` : n;
+          out = out.concat(fs.statSync(p).isDirectory() ? walk(p, rel) : [rel]);
+        }
+        return out;
+      };
+      const snap = walk(SNAP_DIR).sort();
+
+      // ── (a) mọi file snapshot phải có entry ───────────────────────────────────
+      const missing = snap.filter(r => !byUp.has(r));
+      if (missing.length) {
+        err('R16', `${missing.length} file trong upstream/qc-base/ KHÔNG có entry trong bin/qc-base-map.json`,
+            `Bị bỏ quên trong im lặng. Thêm entry với state \`skipped\` + \`why\` nếu cố ý không lấy.\n` +
+            `        ${missing.slice(0, 5).join('\n        ')}${missing.length > 5 ? `\n        … và ${missing.length - 5} file nữa` : ''}`);
+      }
+      const orphan = entries.filter(e => !snap.includes(e.upstream));
+      if (orphan.length) {
+        err('R16', `${orphan.length} entry trỏ vào file KHÔNG còn trong snapshot: ${orphan.map(e => e.upstream).join(', ')}`,
+            'Snapshot đã đổi mà bản đồ chưa theo — chạy lại bước dựng bản đồ.');
+      }
+
+      // ── (b) entry `ported` phải có base_sha, và base_sha phải KHỚP file thật ──
+      const sha1 = b => crypto.createHash('sha1').update(b).digest('hex');
+      for (const e of entries.filter(x => x.state === 'ported')) {
+        if (!e.base_sha) {
+          err('R16', `entry \`${e.upstream}\` là \`ported\` nhưng THIẾU base_sha`,
+              'Không có base thì merge ba chiều lần sau mất một chiều — mọi đồng bộ thành đoán.');
+          continue;
+        }
+        const abs = path.join(SNAP_DIR, e.upstream);
+        if (!fs.existsSync(abs)) continue;             // đã báo ở orphan
+        const real = sha1(fs.readFileSync(abs));
+        if (real !== e.base_sha) {
+          err('R16', `base_sha của \`${e.upstream}\` KHÔNG khớp file snapshot`,
+              `khai=${e.base_sha.slice(0, 12)}… thật=${real.slice(0, 12)}… — sha bịa, hoặc snapshot đã bị sửa tay sau khi port.`);
+        }
+        // frontmatter của file đích phải khai đúng cùng một sha VÀ cùng một upstream_path
+        for (const t of (e.targets || [])) {
+          const tp = path.join(ROOT, t);
+          if (!fs.existsSync(tp)) continue;            // đã báo ở (c)
+          const txt = fs.readFileSync(tp, 'utf8');
+          const m = /^upstream_sha: (.+)$/m.exec(txt);
+          if (m && m[1].trim() !== e.base_sha) {
+            err('R16', `${t} khai upstream_sha khác base_sha trong bản đồ`,
+                `file=${m[1].trim().slice(0, 12)}… map=${e.base_sha.slice(0, 12)}… — hai chỗ nói về cùng một sự thật mà lệch nhau.`);
+          }
+          // ── (e) upstream_path trong frontmatter phải trỏ vào file snapshot CÓ THẬT ──
+          //
+          // Vì sao cần nhánh riêng: (b) so sha, và sha vẫn khớp khi đường dẫn bị sửa sai —
+          // nên (b) mù với ca này. Ca thật (B9): một script đổi tên `DOC_GAPS.md → DOC_GAP.md`
+          // chạy quét cả frontmatter, sửa luôn `upstream_path` thành tên KHÔNG tồn tại ở
+          // upstream. self-check vẫn xanh; chỉ lộ ra khi kiểm tay. Mất `upstream_path` là mất
+          // nửa BASE của merge ba chiều — biết "sha nào" mà không biết "của file nào".
+          const mp = /^upstream_path: (.+)$/m.exec(txt);
+          if (mp) {
+            const declared = mp[1].trim();
+            if (declared !== e.upstream) {
+              err('R16', `${t} khai upstream_path "${declared}" ≠ bản đồ "${e.upstream}"`,
+                  'Hai chỗ cùng khai một sự thật mà lệch nhau — sửa cho khớp.');
+            }
+            if (!fs.existsSync(path.join(SNAP_DIR, declared))) {
+              err('R16', `${t} khai upstream_path "${declared}" — KHÔNG TỒN TẠI trong snapshot`,
+                  'Đường dẫn bị sửa sai (vd một lần đổi tên hàng loạt quét cả frontmatter), ' +
+                  'hoặc upstream đã đổi tên. sha có thể vẫn khớp nên nhánh (b) không bắt được.');
+            }
+          }
+        }
+      }
+
+      // ── (c) mọi target của entry `ported` phải tồn tại ────────────────────────
+      for (const e of entries.filter(x => x.state === 'ported')) {
+        for (const t of (e.targets || [])) {
+          if (!fs.existsSync(path.join(ROOT, t))) {
+            err('R16', `entry \`${e.upstream}\` là \`ported\` nhưng target \`${t}\` không tồn tại`,
+                'Bản đồ lỗi thời sau khi đổi tên/xoá file đích.');
+          }
+        }
+      }
+    }
+  }
+}
+
 // ── report ────────────────────────────────────────────────────────────────────
 const tagCount = schema.tags.length;
 const colCount = schema.tsv_columns.length;

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.9.1
+0.9.3

package/core/commands/propose-scenario.md

@@ -1,7 +1,7 @@
 # /propose-scenario — Đề xuất một BDD Scenario mới (cho Tester & QC)
 
 Dành cho **tester và QC** phát hiện edge case chưa được BDD hiện tại phủ (vd một gap missing-coverage
-`DOC_GAPS` từ `/qc-analyze`). Draft một Gherkin scenario vào **khu proposal** để
+`DOC_GAP` từ `/qc-analyze`). Draft một Gherkin scenario vào **khu proposal** để
 PO/Dev review và promote.
 
 **KHÔNG sửa file `.feature` canonical.** BDD do PO/Dev sở hữu — lệnh này chỉ ghi