@educa-corp/sdd-framework 0.3.0 → 0.4.2

package/bin/build.js

@@ -215,6 +215,15 @@ for (const { src, dest, filter } of coreMappings) {
 fs.writeFileSync(path.join(CORE_DIR, 'FRAMEWORK_VERSION'), VERSION + '\n', 'utf8');
 console.log(`  ✅ core/FRAMEWORK_VERSION  (v${VERSION})`);
 
+// .agent/README.md — which paths under .agent/ a project may edit, and which the
+// upgrade overwrites (see GAPS.md G24). Source lives at repo root so it does not
+// land inside .agent/templates/.
+const agentReadmeSrc = path.join(ROOT, 'AGENT_README.md');
+if (fs.existsSync(agentReadmeSrc)) {
+  fs.copyFileSync(agentReadmeSrc, path.join(CORE_DIR, 'README.md'));
+  console.log('  ✅ core/README.md  (← AGENT_README.md)');
+}
+
 // ── 4. Sync local dogfood .agent/ (dev repo only) ────────────────────────────
 //
 // In THIS framework repo, .agent/ is a pure mirror of core/ used to dogfood the

package/bin/index.js

@@ -9,8 +9,15 @@ const ROOT = path.join(__dirname, '..');
 const pkg      = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
 const VERSION  = pkg.version;
 
+// Records the hash of exactly what the last install wrote into .agent/, so the next
+// install can tell a user-edited file from a framework-changed one (see G24 below).
+// Declared up here, not next to installCore(): that function runs before the bottom
+// of this file is evaluated, and `const` does not hoist.
+const MANIFEST_NAME = '.install-manifest.json';
+
 const args = process.argv.slice(2);
 const isMigrateSpecs = args.includes('--migrate-specs');
+const isMigrateBddPf = args.includes('--migrate-bdd-platform');
 const isRenamePrd    = args.includes('--rename-prd-files');
 const isInit     = args.includes('--init');
 const isProject  = args.includes('--project');
@@ -85,6 +92,13 @@ if (showHelp) {
   console.log('                            spec layout (specs/prd, specs/bdd, ...) to the feature-package');
   console.log('                            layout (specs/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md,bdd/,...}).');
   console.log('                            DRY-RUN by default; add --apply to execute. Uses git mv when possible.');
+  console.log('  --migrate-bdd-platform    Move flat BDD files into the per-platform layout:');
+  console.log('                            specs/{domain}/{slug}/bdd/*.feature → bdd/{platform}/*.feature.');
+  console.log('                            For projects whose umbrella-mode runs produced the flat layout');
+  console.log('                            (pre-v0.4.1). Resolves platform from @trace.platform, else @trace.module,');
+  console.log('                            else step vocabulary; inserts @trace.platform when missing. Reports');
+  console.log('                            filename COLLISION and LOST SPEC instead of guessing.');
+  console.log('                            DRY-RUN by default; add --apply to execute. Uses git mv when possible.');
   console.log('  --rename-prd-files        Rename feature-package PRD files from the old fixed name prd.md to the');
   console.log('                            {TICKET-ID}-{prd-slug}.md convention (e.g. SEG01-segment-scoring-service.md).');
   console.log('                            For projects already on the feature-package layout. DRY-RUN by default;');
@@ -122,6 +136,13 @@ if (isMigrateSpecs) {
   return; // migrate-specs.js calls process.exit itself
 }
 
+// ── --migrate-bdd-platform: flat bdd/*.feature → bdd/{platform}/*.feature ──
+// Also operates on the user's specs, so it runs BEFORE the build step. See GAPS.md G3.
+if (isMigrateBddPf) {
+  require(path.join(__dirname, '..', 'scripts', 'migrate-bdd-platform.js'));
+  return; // migrate-bdd-platform.js calls process.exit itself
+}
+
 // ── --rename-prd-files: rename feature-package prd.md → {TICKET-ID}-{slug}.md ──
 if (isRenamePrd) {
   require(path.join(__dirname, '..', 'scripts', 'rename-prd-files.js'));
@@ -165,18 +186,20 @@ if (isInit) {
   if (moduleName) console.log(`Module : ${moduleName}`);
   console.log('');
 
-  // 1. Copy core/** → .agent/**
+  // 1. Copy core/** → .agent/**  (backs up + reports locally edited files — G24)
   console.log('Installing framework files to .agent/ ...');
   console.log('');
-  copyDirRecursive(coreDir, agentDir);
+  const agentInstall = installCore(coreDir, agentDir, frameworkVersion);
 
   const agentSubdirs = fs.readdirSync(agentDir, { withFileTypes: true })
     .filter(e => e.isDirectory())
+    .filter(e => !e.name.startsWith('.overwritten-'))
     .map(e => e.name);
   for (const sub of agentSubdirs) {
     console.log(`  ✅ .agent/${sub}/`);
   }
   console.log(`  ✅ .agent/FRAMEWORK_VERSION  (v${frameworkVersion})`);
+  reportOverwritten(agentInstall, '.agent/');
 
   // 2. Create .claude/commands/ shortcuts that delegate to .agent/commands/
   console.log('');
@@ -340,9 +363,10 @@ if (isInit) {
       // Create service dir if needed
       fs.mkdirSync(svcDir, { recursive: true });
 
-      // Copy core → service/.agent/
-      copyDirRecursive(coreDir, svcAgentDir);
+      // Copy core → service/.agent/  (backs up + reports locally edited files — G24)
+      const svcInstall = installCore(coreDir, svcAgentDir, frameworkVersion);
       console.log(`  ✅ ${svc.name}/.agent/`);
+      reportOverwritten(svcInstall, `${svc.name}/.agent/`);
 
       // Install module
       if (svc.module) {
@@ -595,6 +619,93 @@ function copyDirRecursive(src, dest) {
   }
 }
 
+// ── Overwrite-aware install of core/ → .agent/ ───────────────────────────────
+// .agent/ is a GENERATED mirror: --init (and therefore /update-framework) copies
+// core/ over it unconditionally. Anything a project edited in there is destroyed
+// silently. This wrapper makes that visible: it backs up the edited files and
+// reports them. It does NOT change the overwrite behaviour. See GAPS.md G24.
+//
+// The hard part is telling "the USER edited this file" apart from "the FRAMEWORK
+// changed this file between versions" — a plain core-vs-.agent content diff flags
+// both, so every upgrade would report dozens of files that nobody touched.
+// Hence a manifest: each install records the hash of exactly what it wrote, so
+// the next install can tell a pristine file (hash matches) from an edited one.
+function sha1(file) {
+  return require('crypto').createHash('sha1').update(fs.readFileSync(file)).digest('hex');
+}
+
+function readManifest(agentDir) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(agentDir, MANIFEST_NAME), 'utf8'));
+    return raw && raw.files ? raw : null;
+  } catch { return null; }
+}
+
+/**
+ * Copy core/ → .agent/, backing up any file the project edited since the last install.
+ * @returns {{ edited: string[], backupDir: string|null, firstRun: boolean }}
+ *   edited   — repo-relative paths (posix) that were overwritten AND had local edits
+ *   firstRun — no manifest existed, so edits could not be detected this time
+ */
+function installCore(coreDir, agentDir, version) {
+  const manifest = readManifest(agentDir);
+  const firstRun = !manifest && fs.existsSync(path.join(agentDir, 'commands'));
+  const stamp    = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+  const backupDir = path.join(agentDir, `.overwritten-${version}-${stamp}`);
+  const edited = [];
+  const written = {};
+
+  const walk = (src, dst) => {
+    fs.mkdirSync(dst, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      const s = path.join(src, entry.name);
+      const d = path.join(dst, entry.name);
+      if (entry.isDirectory()) { walk(s, d); continue; }
+
+      const rel = path.relative(agentDir, d).replace(/\\/g, '/');
+      // Locally edited == exists, we have a record of what we last wrote, and the
+      // file no longer matches that record. Framework-only changes never match here.
+      if (manifest && fs.existsSync(d) && manifest.files[rel] && sha1(d) !== manifest.files[rel]) {
+        const bak = path.join(backupDir, rel);
+        fs.mkdirSync(path.dirname(bak), { recursive: true });
+        fs.copyFileSync(d, bak);
+        edited.push(rel);
+      }
+      fs.copyFileSync(s, d);
+      written[rel] = sha1(d);
+    }
+  };
+  walk(coreDir, agentDir);
+
+  fs.writeFileSync(
+    path.join(agentDir, MANIFEST_NAME),
+    JSON.stringify({ version, generated_at: new Date().toISOString(), files: written }, null, 2),
+    'utf8'
+  );
+
+  return { edited, backupDir: edited.length ? backupDir : null, firstRun };
+}
+
+function reportOverwritten(result, agentLabel) {
+  if (result.firstRun) {
+    console.log('');
+    console.log(`  ℹ️  ${agentLabel}${MANIFEST_NAME} created. Từ lần nâng cấp SAU, mọi file bạn`);
+    console.log(`     sửa trong ${agentLabel} mà bị ghi đè sẽ được backup + liệt kê.`);
+    return;
+  }
+  if (!result.edited.length) return;
+
+  const rel = path.relative(process.cwd(), result.backupDir).replace(/\\/g, '/');
+  console.log('');
+  console.log(`  ⚠️  ${result.edited.length} file trong ${agentLabel} đã bị bạn sửa và VỪA BỊ GHI ĐÈ:`);
+  for (const f of result.edited.slice(0, 12)) console.log(`        ${agentLabel}${f}`);
+  if (result.edited.length > 12) console.log(`        … và ${result.edited.length - 12} file nữa`);
+  console.log(`      Bản cũ đã lưu ở: ${rel}/`);
+  console.log(`      ${agentLabel} là bản mirror SINH RA — sửa trực tiếp ở đó không bền.`);
+  console.log(`      Muốn giữ thay đổi: chuyển nó vào repo framework rồi phát hành,`);
+  console.log(`      hoặc áp lại thủ công sau khi xem diff. Xoá thư mục backup khi xong.`);
+}
+
 function installDataGuardHook() {
   const projectRoot = process.cwd();
   const hooksDir    = path.join(projectRoot, '.claude', 'hooks');

package/bin/self-check.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * self-check — đối chiếu bin/trace-schema.json với các file lệnh/step/template thật.
+ *
+ * Vì sao tồn tại: 19/23 GAP trong GAPS.md là CÙNG một lỗi — contract (field, path,
+ * giá trị enum) được phát biểu lại bằng prose ở nhiều lệnh rồi lệch nhau qua từng
+ * lần sửa, và KHÔNG có gì phát hiện. Ca thuần khiết nhất là @trace.sc_version:
+ * 3 consumer, 0 producer, sống qua nhiều version mà không lệnh nào, không cổng
+ * nào, không test nào bắt được. Đây là cái bắt lớp lỗi đó một cách mechanical.
+ *
+ * 6 rule:
+ *   R1  field có read_by nhưng KHÔNG có producer         → ERROR  (bắt được G1)
+ *   R2  field có producer nhưng KHÔNG ai đọc             → WARN   (bắt được G15, fe_phase)
+ *   R3  actor được khai là producer/consumer mà file của
+ *       nó KHÔNG nhắc tên field                          → ERROR  (bắt được G5, G12, G13)
+ *   R4  {paths.X} dùng trong lệnh mà X không có trong
+ *       project-context.yaml, và ngược lại key chết      → ERROR / WARN (bắt được G17)
+ *   R5  pattern bị cấm xuất hiện trở lại                 → ERROR  (bắt được G3, G8, G10, G18, G21)
+ *   R6  giá trị enum khai trong vocabulary mà không actor
+ *       nào dùng                                         → WARN   (bắt được G19: integration vs integrated)
+ *
+ * Chạy: node bin/self-check.js            (exit 1 nếu có ERROR)
+ *       node bin/self-check.js --warn-only (luôn exit 0)
+ * Được `npm run build` gọi sau khi assemble template.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const WARN_ONLY = process.argv.includes('--warn-only');
+
+const schema = JSON.parse(fs.readFileSync(path.join(__dirname, 'trace-schema.json'), 'utf8'));
+
+const errors = [];
+const warns = [];
+const err  = (rule, msg, hint) => errors.push({ rule, msg, hint });
+const warn = (rule, msg, hint) => warns.push({ rule, msg, hint });
+
+// ── nạp nội dung actor ────────────────────────────────────────────────────────
+const actorText = {};
+const missingActors = [];
+for (const [name, rel] of Object.entries(schema.actors)) {
+  if (name.startsWith('$')) continue;
+  const abs = path.join(ROOT, rel);
+  if (!fs.existsSync(abs)) { missingActors.push(`${name} → ${rel}`); continue; }
+  actorText[name] = fs.readFileSync(abs, 'utf8');
+}
+if (missingActors.length) {
+  err('R0', `${missingActors.length} actor trong schema trỏ tới file không tồn tại`,
+      missingActors.join('\n        '));
+}
+
+/** Mọi file .tmpl + step + template — dùng cho R4/R5/R6 (quét rộng). */
+function allSourceFiles() {
+  const out = [];
+  const push = (dir, filter) => {
+    if (!fs.existsSync(dir)) return;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) push(p, filter);
+      else if (filter(e.name)) out.push(p);
+    }
+  };
+  push(path.join(ROOT, 'commands'), f => f.endsWith('.tmpl'));
+  push(path.join(ROOT, 'steps'),    f => f.endsWith('.md'));
+  push(path.join(ROOT, 'templates'), () => true);
+  push(path.join(ROOT, 'rules'),    f => f.endsWith('.md'));
+  push(path.join(ROOT, 'modules'),  f => f.endsWith('.yaml') || f.endsWith('.md'));
+  return out;
+}
+const sources = allSourceFiles().map(p => ({
+  rel: path.relative(ROOT, p).replace(/\\/g, '/'),
+  text: fs.readFileSync(p, 'utf8'),
+}));
+const allText = sources.map(s => s.text).join('\n');
+
+/**
+ * Field `name` có được nhắc trong `text` như một TOKEN TRỌN VẸN không?
+ *
+ * Phải khớp theo ranh giới token, không phải substring. Hai bẫy thật:
+ *   - `@trace.XXsc_version` CHỨA chuỗi `sc_version` → một phép so substring sẽ coi là
+ *     "có nhắc" và R3 im lặng đúng lúc contract vừa bị gỡ producer. (Chính test tái
+ *     tạo G1 đã lộ ra bug này trong bản đầu của checker.)
+ *   - `dev_selftest_at` CHỨA `dev_selftest` → lệnh chỉ nhắc cột này sẽ được coi là
+ *     đã implement cả cột kia.
+ */
+function mentions(text, name) {
+  const esc = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Trước: không được là phần đuôi của một token dài hơn (chặn `XXsc_version`).
+  // Sau: không được là phần đầu của token dài hơn (chặn `dev_selftest` khớp `..._at`).
+  const before = name.startsWith('@') ? '' : '(?<![A-Za-z0-9_.])';
+  return new RegExp(`${before}${esc}(?![A-Za-z0-9_])`).test(text);
+}
+
+// ── R1 + R2 + R3 — producer / consumer / prose khớp ───────────────────────────
+function checkField(kind, name, def) {
+  const producers = [...(def.written_by || []), ...(def.bumped_by || [])];
+  const consumers = def.read_by || [];
+
+  // R1 — có người đọc mà không ai ghi
+  if (consumers.length && !producers.length) {
+    err('R1', `${kind} \`${name}\`: có ${consumers.length} consumer nhưng KHÔNG có producer`,
+        `Ai ghi/bump nó? Thêm written_by hoặc bumped_by vào schema, và implement ở lệnh đó.\n`
+      + `        Đây chính là hình dạng của G1 (@trace.sc_version) — DRIFT chết mà không ai báo.`);
+  }
+
+  // R2 — có người ghi mà không ai đọc
+  if (producers.length && !consumers.length && !def.allow_no_reader) {
+    warn('R2', `${kind} \`${name}\`: có producer nhưng KHÔNG ai đọc — field chết?`,
+         `Hoặc thêm consumer, hoặc bỏ field, hoặc khai allow_no_reader kèm lý do.`);
+  }
+
+  // R3 — actor được khai nhưng file của nó không nhắc field
+  for (const actor of new Set([...producers, ...consumers])) {
+    const text = actorText[actor];
+    if (text === undefined) continue;                       // đã báo ở R0
+    if (!mentions(text, name)) {
+      err('R3', `${kind} \`${name}\`: schema khai \`${actor}\` là producer/consumer nhưng ${schema.actors[actor]} KHÔNG nhắc tới nó`,
+          `Hoặc lệnh đó thiếu implement, hoặc schema khai sai. Prose lệch schema chính là\n`
+        + `        cách 19/23 GAP phát sinh.`);
+    }
+  }
+}
+
+for (const t of schema.tags)        checkField('tag', t.name, t);
+for (const c of schema.tsv_columns) checkField('cột TSV', c.name, c);
+
+// ── R4 — {paths.X} vs project-context.yaml ────────────────────────────────────
+const cfgPath = path.join(ROOT, schema.path_keys.config_file);
+if (!fs.existsSync(cfgPath)) {
+  err('R4', `Không tìm thấy ${schema.path_keys.config_file}`, 'path_keys.config_file trong schema trỏ sai?');
+} else {
+  const cfg = fs.readFileSync(cfgPath, 'utf8');
+  // key khai: dòng thụt 2 space dưới `paths:` dạng `  key: "value"` (bỏ comment)
+  const declared = new Set();
+  let inPaths = false;
+  for (const line of cfg.split(/\r?\n/)) {
+    if (/^paths:\s*$/.test(line)) { inPaths = true; continue; }
+    if (inPaths && /^\S/.test(line)) break;                 // sang section khác
+    const m = inPaths && line.match(/^ {2}([a-z_][a-z0-9_]*):/);
+    if (m) declared.add(m[1]);
+  }
+
+  // CHỈ quét commands/ + steps/ — đó là những file thực sự phân giải {paths.X} lúc chạy.
+  // templates/*.md là prose (vd templates/README.md giải thích các key ĐÃ BỎ) — tính nó
+  // vào "used" sẽ báo oan chính đoạn văn nói rằng key đó không còn nữa.
+  const runtimeText = sources
+    .filter(s => s.rel.startsWith('commands/') || s.rel.startsWith('steps/'))
+    .map(s => s.text).join('\n');
+  const used = new Set();
+  for (const m of runtimeText.matchAll(/\{paths\.([a-z_][a-z0-9_]*)\}/g)) used.add(m[1]);
+  // context-loader tham chiếu vài key không qua ngoặc nhọn (vd `paths.lessons_file`)
+  for (const m of runtimeText.matchAll(/\bpaths\.([a-z_][a-z0-9_]*)\b/g)) used.add(m[1]);
+
+  const undeclared = [...used].filter(k => !declared.has(k));
+  if (undeclared.length) {
+    err('R4', `${undeclared.length} key \`{paths.X}\` được dùng nhưng KHÔNG khai trong project-context.yaml`,
+        undeclared.join(', '));
+  }
+
+  const ignore = new Set(schema.path_keys.ignore_unused || []);
+  const dead = [...declared].filter(k => !used.has(k) && !ignore.has(k));
+  if (dead.length) {
+    warn('R4', `${dead.length} key khai trong project-context.yaml mà KHÔNG lệnh nào dùng — key chết?`,
+         `${dead.join(', ')}\n        (Đây là hình dạng của G17. Nếu cố ý giữ, thêm vào path_keys.ignore_unused.)`);
+  }
+}
+
+// ── R5 — pattern bị cấm ───────────────────────────────────────────────────────
+for (const fp of schema.forbidden_patterns) {
+  // `except` = file được phép chứa pattern vì nó đang TRÍCH DẪN pattern trong một cảnh
+  // báo ("đừng glob X"). Mỗi entry phải kèm lý do trong schema — không phải ignore mù.
+  const except = new Set(Object.keys(fp.except || {}));
+  const hits = sources.filter(s => s.text.includes(fp.pattern) && !except.has(s.rel));
+  if (hits.length) {
+    err('R5', `Pattern bị cấm quay lại: \`${fp.pattern}\`  (${fp.gap})`,
+        `${fp.reason}\n        Thấy ở: ${hits.map(h => h.rel).join(', ')}`);
+  }
+  // Cảnh báo nếu một except trở nên vô nghĩa — cảnh báo đã bị xoá thì except cũng nên bỏ
+  for (const f of except) {
+    const src = sources.find(s => s.rel === f);
+    if (!src || !src.text.includes(fp.pattern)) {
+      warn('R5', `\`${fp.pattern}\`: except \`${f}\` không còn chứa pattern — bỏ except này khỏi schema`);
+    }
+  }
+}
+
+// ── R6 — giá trị enum chết ────────────────────────────────────────────────────
+// GIỚI HẠN ĐÃ BIẾT của R6: nó bắt "giá trị khai mà KHÔNG xuất hiện ở đâu" — tức là ca
+// một giá trị bị đổi tên/xoá khỏi toàn bộ codebase. Nó KHÔNG bắt được typo ở MỘT chỗ
+// khi giá trị đúng vẫn còn ở chỗ khác (vd `fe_phase: integration` lọt vào một lệnh trong
+// khi các lệnh còn lại vẫn ghi `integrated`). Cho lớp đó, dùng forbidden_patterns — chính
+// xác hơn và không có false positive.
+// Khớp theo ranh giới token: `fe_integrated` KHÔNG được coi là đã dùng `integrated`.
+for (const [vocab, def] of Object.entries(schema.vocabularies)) {
+  if (vocab.startsWith('$')) continue;
+  const unused = (def.values || []).filter(v => !mentions(allText, v));
+  if (unused.length) {
+    warn('R6', `vocabulary \`${vocab}\`: ${unused.length} giá trị không xuất hiện ở đâu — sai chính tả hay giá trị chết?`,
+         `${unused.join(', ')}\n        (G19 là ca này: doc ghi fe_phase "integration" còn lệnh ghi "integrated".)`);
+  }
+}
+
+// ── report ────────────────────────────────────────────────────────────────────
+const tagCount = schema.tags.length;
+const colCount = schema.tsv_columns.length;
+console.log('');
+console.log('Self-check (bin/trace-schema.json) ...');
+console.log('');
+
+const show = (list, icon) => {
+  for (const e of list) {
+    console.log(`  ${icon} [${e.rule}] ${e.msg}`);
+    if (e.hint) console.log(`        ${e.hint}`);
+  }
+};
+show(errors, '❌');
+show(warns,  '⚠️ ');
+
+if (!errors.length && !warns.length) {
+  console.log(`  ✅ ${tagCount} tag + ${colCount} cột TSV + ${Object.keys(schema.vocabularies).length - 1} vocabulary — contract khớp mọi lệnh`);
+}
+console.log('');
+
+if (errors.length && !WARN_ONLY) {
+  console.log(`❌ Self-check FAIL: ${errors.length} error, ${warns.length} warning.`);
+  console.log('   Sửa contract ở bin/trace-schema.json TRƯỚC, rồi sửa lệnh cho khớp.');
+  console.log('   (Bỏ qua tạm: node bin/self-check.js --warn-only)');
+  console.log('');
+  process.exit(1);
+}
+if (errors.length) {
+  console.log(`⚠️  ${errors.length} error bị bỏ qua do --warn-only.`);
+  console.log('');
+}