@educa-corp/sdd-framework 0.5.0 → 0.6.0

package/bin/build.js

@@ -23,6 +23,41 @@ const SKILLS_DIR = path.join(ROOT, 'skills');
 // Cache for step file contents
 const stepCache = {};
 
+// ── Step nào ĐỌC LÚC CHẠY thay vì nướng vào từng lệnh (GAPS-v3 G45) ──────────
+//
+// Vì sao: build inline `{{include:}}` vào TỪNG file lệnh, nên 32 lệnh = 2069 KB mà chỉ
+// 580 KB là nội dung riêng của chúng — 72% là vài step giống hệt nhau, chép 30 lần.
+// `/generate-code` = 108 KB ≈ 27.000 token đọc TRƯỚC khi làm gì; gần một nửa không nói
+// gì về việc sinh code. `/refine-prd` thì 75% là nội dung dùng chung.
+//
+// Cái giá thật không phải tiền: trên PRD nhiều UC, nạp 27k token chỉ để đọc chỉ dẫn làm
+// tăng rủi ro CẠN CONTEXT GIỮA CHỪNG — mà thứ đang được ghi lúc đó là sổ trace.
+//
+// PHẠM VI CÓ CHỦ Ý — chỉ hai step, không phải tất cả:
+//   context-loader (64% lãng phí) · report-footer (16%)  → đọc lúc chạy
+//   gate (15%)                                            → GIỮ INLINE
+// Gate là lưới an toàn (model check · resolve target · CHECKPOINT). Bỏ sót gate thì lệnh
+// VẪN CHẠY, chỉ là không còn cổng nào — hỏng ÂM THẦM. Bỏ sót context-loader thì lệnh dừng
+// ngay vì thiếu path/config — hỏng ỒN ÀO, thấy liền. Đổi 15% lấy một lưới an toàn là lỗ.
+//
+// MỘT biến thể duy nhất kể từ khi G50 gỡ legacy mode. Trước đó phải build hai bản —
+// `commands/*.md` inline đầy đủ cho legacy (nó copy thẳng file đó mà KHÔNG cài `.agent/`,
+// nên không có `.agent/steps/` để đọc) và `core/commands/*.md` slim cho `--init`. Legacy
+// đi rồi thì mọi bản cài đều có `.agent/steps/`, và nhánh build thứ hai là nợ chờ lệch.
+const RUNTIME_READ = {
+  'steps/context-loader.md':
+    '**BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,\n' +
+    'rồi mới tiếp tục phần bên dưới.\n' +
+    '\n' +
+    'Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, guardrail từ\n' +
+    '`project-lessons`, và routing service (chế độ umbrella) đều **chưa được phân giải** — mọi\n' +
+    'placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.',
+
+  'steps/report-footer.md':
+    '**Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·\n' +
+    'Output Artifacts · Next) cho report cuối, kèm khối bên dưới.',
+};
+
 /**
  * Load a step file by name, caching the result.
  * @param {string} stepPath - e.g. "steps/gate.md"
@@ -54,10 +89,11 @@ function buildTemplate(tmplFile, label) {
   try {
     let content = fs.readFileSync(tmplFile, 'utf8');
 
-    // Replace all {{include:...}} markers
+    // Replace all {{include:...}} markers — trừ những step nằm trong RUNTIME_READ,
+    // chúng được thay bằng một chỉ dẫn ĐỌC LÚC CHẠY thay vì nướng 33 KB vào đây (G45).
     content = content.replace(/\{\{include:([^}]+)\}\}/g, (match, includePath) => {
-      const trimmed = includePath.trim();
-      return loadStep(trimmed);
+      const key = includePath.trim();
+      return RUNTIME_READ[key] !== undefined ? RUNTIME_READ[key] : loadStep(key);
     });
 
     fs.writeFileSync(outFile, content, 'utf8');
@@ -155,6 +191,8 @@ if (skillTmplFiles.length === 0) {
 // It is gitignored but included in the npm package (via "files" whitelist).
 
 const CORE_DIR = path.join(ROOT, 'core');
+const CORE_TMP = path.join(ROOT, 'core.tmp');
+const CORE_BAK = path.join(ROOT, 'core.bak');
 const pkg      = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
 const VERSION  = pkg.version;
 
@@ -162,11 +200,48 @@ console.log('');
 console.log('Populating core/ (distributable) ...');
 console.log('');
 
-// Clean and recreate core/
-if (fs.existsSync(CORE_DIR)) {
-  fs.rmSync(CORE_DIR, { recursive: true });
+// Dựng vào core.tmp/ rồi SWAP — không bao giờ xoá core/ trước khi có bản thay thế
+// hoàn chỉnh (GAPS-v3 G43).
+//
+// Bản cũ làm `rmSync(core/)` rồi mới dựng lại. Nếu bước dựng fail nửa đường — đĩa đầy,
+// thư mục read-only, Ctrl-C — thì core/ ĐÃ MẤT và không có gì thay thế. Với consumer thì
+// hậu quả nặng hơn hẳn: `--init` chạy build ngay trong thư mục npx cache, nên một lần fail
+// làm hỏng package trong cache VĨNH VIỄN, và mọi lần chạy sau đều báo "core/ not found.
+// The package may not have been built correctly" — một thông điệp dẫn sai hướng, vì package
+// được build đúng, chính installer đã xoá nó.
+//
+// Dọn rác của lần chạy trước (nếu có) — không thì swap sẽ trượt vào thư mục cũ.
+for (const stale of [CORE_TMP, CORE_BAK]) {
+  if (fs.existsSync(stale)) fs.rmSync(stale, { recursive: true, force: true });
+}
+
+// Kiểm quyền ghi TRƯỚC khi làm gì cả: fail ở đây thì chưa có gì bị đụng tới.
+try {
+  fs.mkdirSync(CORE_TMP, { recursive: true });
+} catch (err) {
+  console.error('');
+  console.error(`❌ Không ghi được vào thư mục package: ${ROOT}`);
+  console.error(`   (${err.code || err.message})`);
+  console.error('');
+  console.error('   Đây là bản cài read-only. core/ hiện tại KHÔNG bị đụng tới.');
+  console.error('   Thử:  npx -y @educa-corp/sdd-framework@latest --init');
+  console.error('   Hoặc xoá cache npx:  rm -rf ~/.npm/_npx');
+  console.error('');
+  process.exit(1);
+}
+
+/** Đưa core.tmp/ vào chỗ core/. Fail ở bất kỳ đâu thì khôi phục bản cũ. */
+function swapCoreIntoPlace() {
+  const hadOld = fs.existsSync(CORE_DIR);
+  if (hadOld) fs.renameSync(CORE_DIR, CORE_BAK);
+  try {
+    fs.renameSync(CORE_TMP, CORE_DIR);
+  } catch (err) {
+    if (hadOld) fs.renameSync(CORE_BAK, CORE_DIR);   // core/ trở lại nguyên trạng
+    throw err;
+  }
+  if (hadOld) fs.rmSync(CORE_BAK, { recursive: true, force: true });
 }
-fs.mkdirSync(CORE_DIR, { recursive: true });
 
 /**
  * Recursively copy src → dest, optionally filtering files by name.
@@ -190,29 +265,31 @@ function copyDirToCore(src, dest, fileFilter) {
 
 const coreMappings = [
   // Built command .md files (not .tmpl sources)
-  { src: COMMANDS_DIR,              dest: path.join(CORE_DIR, 'commands'),  filter: f => f.endsWith('.md') },
+  { src: COMMANDS_DIR,              dest: path.join(CORE_TMP, 'commands'),  filter: f => f.endsWith('.md') },
   // Step files (gate, context-loader, spawn-agent, report-footer)
-  { src: path.join(ROOT, 'steps'),  dest: path.join(CORE_DIR, 'steps'),    filter: null },
+  { src: path.join(ROOT, 'steps'),  dest: path.join(CORE_TMP, 'steps'),    filter: null },
   // Hook scripts
-  { src: path.join(ROOT, 'hooks'),  dest: path.join(CORE_DIR, 'hooks'),    filter: null },
+  { src: path.join(ROOT, 'hooks'),  dest: path.join(CORE_TMP, 'hooks'),    filter: null },
   // Data-protection and workflow rules
-  { src: path.join(ROOT, 'rules'),  dest: path.join(CORE_DIR, 'rules'),    filter: null },
+  { src: path.join(ROOT, 'rules'),  dest: path.join(CORE_TMP, 'rules'),    filter: null },
   // PRD / architecture templates
-  { src: path.join(ROOT, 'templates'), dest: path.join(CORE_DIR, 'templates'), filter: null },
+  { src: path.join(ROOT, 'templates'), dest: path.join(CORE_TMP, 'templates'), filter: null },
   // Stack module profiles
-  { src: path.join(ROOT, 'modules'),   dest: path.join(CORE_DIR, 'modules'),   filter: null },
+  { src: path.join(ROOT, 'modules'),   dest: path.join(CORE_TMP, 'modules'),   filter: null },
   // Built skill .md files (not .tmpl sources)
-  { src: SKILLS_DIR,                dest: path.join(CORE_DIR, 'skills'),   filter: f => !f.endsWith('.tmpl') },
+  { src: SKILLS_DIR,                dest: path.join(CORE_TMP, 'skills'),   filter: f => !f.endsWith('.tmpl') },
 ];
 
 for (const { src, dest, filter } of coreMappings) {
   copyDirToCore(src, dest, filter);
-  const rel = path.relative(ROOT, dest);
-  console.log(`  ✅ ${rel}/`);
+  // Báo theo ĐÍCH CUỐI (core/…), không phải thư mục dựng trung gian. core.tmp/ là chi
+  // tiết của bước swap (G43) — người đọc log quan tâm cái gì được cài, không quan tâm
+  // nó đi qua đâu.
+  console.log(`  ✅ core/${path.basename(dest)}/`);
 }
 
-// Write FRAMEWORK_VERSION so upgrade.sh can compare installed vs latest
-fs.writeFileSync(path.join(CORE_DIR, 'FRAMEWORK_VERSION'), VERSION + '\n', 'utf8');
+// Write FRAMEWORK_VERSION so /update-framework can compare installed vs latest
+fs.writeFileSync(path.join(CORE_TMP, '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
@@ -220,10 +297,27 @@ console.log(`  ✅ core/FRAMEWORK_VERSION  (v${VERSION})`);
 // 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'));
+  fs.copyFileSync(agentReadmeSrc, path.join(CORE_TMP, 'README.md'));
   console.log('  ✅ core/README.md  (← AGENT_README.md)');
 }
 
+// ── 3b. Swap core.tmp/ → core/ ───────────────────────────────────────────────
+//
+// Tới đây core.tmp/ đã hoàn chỉnh. Đây là điểm duy nhất core/ bị thay, và nó là
+// một phép rename — gần như nguyên tử, không có cửa sổ nào core/ vắng mặt-và-không-
+// có-bản-thay-thế. Fail thì swapCoreIntoPlace() khôi phục bản cũ (G43).
+try {
+  swapCoreIntoPlace();
+} catch (err) {
+  console.error('');
+  console.error(`❌ Không thay được core/: ${err.code || err.message}`);
+  console.error('   core/ cũ đã được khôi phục — package vẫn dùng được.');
+  console.error(`   Bản vừa dựng còn ở: ${path.relative(ROOT, CORE_TMP)}/`);
+  console.error('   Nguyên nhân thường gặp: file trong core/ đang bị process khác giữ (antivirus, editor).');
+  console.error('');
+  process.exit(1);
+}
+
 // ── 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/gate-trace.js

@@ -0,0 +1,464 @@
+#!/usr/bin/env node
+/**
+ * gate-trace — CỔNG CHẶN PR. Exit 1 khi trace có cờ 🔴.
+ *
+ * Vì sao tồn tại (GAPS-v3 G39): README khai bằng chữ in đậm rằng 4 cờ (ORPHANED ·
+ * TRACE_ORPHAN · SEAM_UNWIRED · STUB_UNRESOLVED) "chặn PR", kèm câu "build xanh + test
+ * từng-UC xanh KHÔNG phát hiện được" — đó là điểm bán hàng cốt lõi của framework.
+ * Nhưng trước file này KHÔNG CÓ GÌ CHẶN: 0 CI, 0 git hook, 0 exit code. /validate-traces
+ * in report vào terminal Claude Code, nơi không CI nào đọc được. Kỷ luật là honor-system,
+ * và cái gì không chặn thì sau sprint thứ ba không ai làm.
+ *
+ * Bốn tầng, theo thứ tự — mỗi tầng vô nghĩa nếu tầng trước chưa xanh:
+ *
+ *   G0  Sổ có ĐƯỢC BẢO VỆ không?      → nằm trong git? git biết cách gộp?
+ *       Kiểm cấu trúc của một quyển sổ không nằm trong git thì vô nghĩa. Hai điều kiện
+ *       này lint đã phát hiện dưới dạng WARN; ở đây chúng được NÂNG thành lỗi chặn —
+ *       cố ý: pre-push nhắc, CI chặn (chặn push vì một dòng cấu hình sẽ dạy dev gõ
+ *       --no-verify, và mất luôn phần lint thật).
+ *   G1  Sổ có ĐÚNG HÌNH DẠNG không?   → gọi bin/lint-trace.js (G38)
+ *       Phán trạng thái trên sổ lệch cột là phán trên dữ liệu rác.
+ *   G2  Report có TƯƠI không?          → đối chiếu report ↔ sổ TSV
+ *       Không có tầng này thì gate là sân khấu: chạy /validate-traces một lần, commit
+ *       report, rồi sửa gì cũng được — CI đọc report cũ và cho qua mãi mãi.
+ *   G3  Có cờ 🔴 nào không?            → đếm counter khai trong schema `gate.blocking`
+ *
+ * PHẠM VI — nói thẳng để không ai tin quá:
+ *   Gate chứng minh "report khớp SỔ". Chỉ /validate-traces chứng minh được "sổ khớp CODE"
+ *   (nó cần quét tag trong source, đọc .feature, so version — việc của LLM, không phải
+ *   của file này). Nên gate bắt được ca phổ biến "quên chạy lại", nhưng KHÔNG bắt được
+ *   ca "sửa code mà không đụng sổ". Đường bịt: CI chạy /validate-traces, hoặc yêu cầu
+ *   report có trong diff khi src đổi. §Output in ra đúng giới hạn này mỗi lần chạy.
+ *
+ * Cờ 🟠 (PRD_DRIFT, BDD_DRIFT, TECHDOC_DRIFT…) KHÔNG chặn — cố ý. Chúng là "code chưa
+ * theo kịp spec", một loại nợ khác. Chặn PR vì nợ là làm cổng bị tắt.
+ *
+ * Chạy: node bin/gate-trace.js [--trace DIR[,DIR]] [--report PATH]
+ *                              [--skip-lint] [--no-reconcile] [--warn-only] [--json]
+ *       exit 1 nếu FAIL (0 với --warn-only)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const schema = JSON.parse(fs.readFileSync(path.join(__dirname, 'trace-schema.json'), 'utf8'));
+const GATE = schema.gate;
+
+if (!GATE || !Array.isArray(GATE.blocking) || !GATE.blocking.length) {
+  console.error('❌ bin/trace-schema.json thiếu khối `gate.blocking` — không biết chặn cờ nào.');
+  process.exit(1);
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2);
+const flag = (name, def) => {
+  const i = argv.indexOf(name);
+  return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : def;
+};
+const WARN_ONLY    = argv.includes('--warn-only');
+const AS_JSON      = argv.includes('--json');
+const SKIP_LINT    = argv.includes('--skip-lint');
+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);
+
+const fails = [];
+const warns = [];
+const oks   = [];
+const fail = (stage, msg, hint) => fails.push({ stage, msg, hint });
+const warn = (stage, msg, hint) => warns.push({ stage, msg, hint });
+
+const rel = p => path.relative(process.cwd(), p).replace(/\\/g, '/');
+
+// ── Chạy lint MỘT LẦN — G0 và G1 cùng đọc kết quả này ─────────────────────────
+
+let lintSummary = 'bỏ qua (--skip-lint)';
+let lintParsed = null;
+let lintStderr = '';
+
+if (!SKIP_LINT) {
+  const lintPath = path.join(__dirname, 'lint-trace.js');
+  const args = ['--trace', TRACE_DIRS.join(','), '--json'];
+  const r = require('child_process').spawnSync(process.execPath, [lintPath, ...args],
+    { encoding: 'utf8' });
+  lintStderr = r.stderr || '';
+  try { lintParsed = JSON.parse(r.stdout); } catch {}
+}
+
+// ── Tầng G0 — sổ có ĐƯỢC BẢO VỆ không (GAPS-v3 T10-debt) ──────────────────────
+//
+// Hỏi TRƯỚC G1 có lý do: G1 kiểm rất kỹ cấu trúc của một quyển sổ mà có thể KHÔNG NẰM
+// TRONG GIT. Kiểm cấu trúc của thứ sắp mất thì vô nghĩa.
+//
+// Hai điều kiện đều đã được lint phát hiện dưới dạng WARN; ở đây chúng được NÂNG thành
+// lỗi chặn. Một implementation, hai mức nghiêm trọng — cố ý: pre-push nhắc, CI chặn.
+// Danh sách rule đọc từ schema (`gate.config_preconditions`), không hard-code — R9 canh.
+const PRECOND = (GATE.config_preconditions || {}).promote_lint_rules || [];
+
+if (SKIP_LINT) {
+  warn('G0', 'bỏ qua kiểm cấu hình (--skip-lint) — không biết sổ có được bảo vệ hay không');
+} else if (!lintParsed) {
+  fail('G0', 'không chạy được bin/lint-trace.js — không xác nhận được sổ có được bảo vệ',
+       lintStderr.trim().split('\n').slice(0, 3).join('\n        ')
+       || `Chạy tay để xem lỗi: node bin/lint-trace.js --trace ${TRACE_DIRS.join(',')}`);
+} else {
+  const byRule = new Map(PRECOND.map(p => [p.rule, p.why]));
+  const hits = (lintParsed.warns || []).filter(w => byRule.has(w.rule));
+
+  for (const h of hits) {
+    fail('G0', `${h.where} — ${h.msg}`,
+         [`Vì sao chặn: ${byRule.get(h.rule)}`,
+          h.hint || ''].filter(Boolean).join('\n        '));
+  }
+  if (!hits.length) {
+    oks.push(`G0 sổ được bảo vệ — nằm trong git · git biết cách gộp (${PRECOND.length}/${PRECOND.length} điều kiện)`);
+  }
+}
+
+// ── Tầng G1 — sổ có đúng hình dạng không (G38) ────────────────────────────────
+
+if (!SKIP_LINT) {
+  const parsed = lintParsed;
+  if (!parsed) {
+    // G0 đã báo lý do — đừng nhân đôi thông điệp, chỉ ghi là không kiểm được.
+    fail('G1', 'không xác nhận được sổ có đúng hình dạng (lint không chạy được — xem G0)');
+  } else if (!parsed.ok) {
+    fail('G1', `sổ trace HỎNG CẤU TRÚC — ${parsed.errors.length} lỗi, gate không phán được`,
+         parsed.errors.slice(0, 6).map(e => `${e.where} — ${e.rule}: ${e.msg}`).join('\n        ')
+         + (parsed.errors.length > 6 ? `\n        … và ${parsed.errors.length - 6} lỗi nữa` : '')
+         + `\n        Chi tiết: node bin/lint-trace.js --trace ${TRACE_DIRS.join(',')}`);
+  } else {
+    const rest = (parsed.warns || []).filter(w => !PRECOND.some(p => p.rule === w.rule));
+    lintSummary = `${parsed.scanned.books} sổ + ${parsed.scanned.seams} bảng phụ`
+                + (rest.length ? ` (${rest.length} warning)` : '');
+    oks.push(`G1 sổ đúng hình dạng — ${lintSummary}`);
+    // Warn đã được G0 nâng thành fail thì KHÔNG in lại ở đây.
+    for (const w of rest) warn('G1', `${w.where} — ${w.rule}: ${w.msg}`);
+  }
+}
+
+// ── Định vị report ────────────────────────────────────────────────────────────
+
+const REPORT_BASENAME = path.basename(GATE.report_path.replace(/^.*[/\\]/, ''));
+
+function findReport() {
+  if (REPORT_ARG) return fs.existsSync(REPORT_ARG) ? path.resolve(REPORT_ARG) : null;
+  for (const d of TRACE_DIRS) {
+    const p = path.resolve(d, REPORT_BASENAME);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+const reportPath = findReport();
+let report = null;
+
+if (!reportPath) {
+  fail('G2', `không tìm thấy ${REPORT_BASENAME} — trace CHƯA TỪNG được audit`,
+       [`Đã tìm ở: ${TRACE_DIRS.map(d => rel(path.resolve(d, REPORT_BASENAME))).join(' · ')}`,
+        `Gate không thể cho qua khi không có gì để đọc — "không có report" ≠ "không có lỗi".`,
+        `Chạy /validate-traces trong Claude Code, rồi commit ${REPORT_BASENAME}.`].join('\n        '));
+} else {
+  try {
+    report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+  } catch (e) {
+    fail('G2', `${rel(reportPath)} không phải JSON hợp lệ: ${e.message}`,
+         `Nghi conflict merge chưa giải. trace-report.json là file SINH LẠI ĐƯỢC —\n`
+       + `        đừng merge tay, chạy lại /validate-traces.`);
+  }
+}
+
+// ── Tầng G2 — report có tươi không ────────────────────────────────────────────
+
+/**
+ * Đọc mọi row dữ liệu của các sổ TSV (bỏ _seams.tsv — nó không mang scenario).
+ * Mỗi row kèm `platform` lấy từ TÊN FILE (`{UC-ID}-{platform}.tsv`) — đó là nơi duy
+ * nhất sổ mang platform, và là thứ làm khoá {sc_id, platform} của G48 dựng được.
+ */
+function readBooks(dirs, domainFilter) {
+  const rows = [];
+  const pf = (schema.vocabularies.platform || {}).values || [];
+  const nameRe = pf.length ? new RegExp(`-(${pf.join('|')})\\.tsv$`) : null;
+
+  const walk = (d) => {
+    if (!fs.existsSync(d)) return;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) { walk(p); continue; }
+      if (!e.name.endsWith('.tsv') || e.name === '_seams.tsv') continue;
+      const m = nameRe && nameRe.exec(e.name);
+      const platform = m ? m[1] : '';
+      const lines = fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n').split('\n')
+        .filter(l => l.trim() !== '');
+      if (lines.length < 2) continue;
+      const header = lines[0].split('\t').map(s => s.trim());
+      const si = header.indexOf('status');
+      const ii = header.indexOf('sc_id');
+      for (const l of lines.slice(1)) {
+        const f = l.split('\t');
+        rows.push({
+          file: p, platform,
+          sc_id:  ii !== -1 ? (f[ii] || '').trim() : '',
+          status: si !== -1 ? (f[si] || '').trim() : '',
+        });
+      }
+    }
+  };
+  for (const d of dirs) {
+    const abs = path.resolve(d);
+    // Report chỉ phủ một domain → chỉ đọc sổ của domain đó, else so lệch là chắc chắn.
+    walk(domainFilter && domainFilter !== 'all' ? path.join(abs, domainFilter) : abs);
+  }
+  return rows;
+}
+
+/** Duỗi cây prds[].ucs[].scenarios[] của report thành danh sách phẳng. */
+function flattenReportScenarios(report) {
+  const out = [];
+  for (const prd of report.prds || []) {
+    for (const uc of prd.ucs || []) {
+      for (const sc of uc.scenarios || []) out.push(sc);
+    }
+  }
+  return out;
+}
+
+/** Domain nào có sổ trên đĩa — để bắt ca report chỉ phủ một phần repo. */
+function domainsOnDisk(dirs) {
+  const out = new Set();
+  for (const d of dirs) {
+    const abs = path.resolve(d);
+    if (!fs.existsSync(abs)) continue;
+    for (const e of fs.readdirSync(abs, { withFileTypes: true })) {
+      if (e.isDirectory() && !e.name.startsWith('.')) out.add(e.name);
+    }
+  }
+  return [...out];
+}
+
+if (report && !NO_RECONCILE) {
+  const domain = report.domain || 'all';
+  const summary = report.summary || {};
+
+  // (a) Report phủ một phần repo → cờ 🔴 ở domain khác hoàn toàn vô hình với gate.
+  //     Cho qua ở đây là cấp một tờ giấy xanh cho thứ chưa ai xem.
+  if (domain !== 'all') {
+    const others = domainsOnDisk(TRACE_DIRS).filter(d => d !== domain);
+    if (others.length) {
+      fail('G2', `report chỉ phủ domain "${domain}" — còn ${others.length} domain có sổ mà chưa được audit`,
+           [`Chưa phủ: ${others.join(' · ')}`,
+            `Gate cho qua lúc này là khẳng định sạch cho thứ chưa ai xem.`,
+            `Chạy /validate-traces KHÔNG kèm domain để audit toàn bộ, rồi commit report.`].join('\n        '));
+    }
+  }
+
+  const rows = readBooks(TRACE_DIRS, domain);
+
+  // (b) hard — số row là tuyệt đối, không nhập nhằng quy ước.
+  const hardKeys = Object.keys(GATE.reconcile.hard || {});
+  for (const key of hardKeys) {
+    if (!(key in summary)) {
+      fail('G2', `report thiếu \`summary.${key}\` — không đối chiếu được độ tươi`,
+           `Counter bị đổi tên? Sửa bin/trace-schema.json \`gate.reconcile\` cho khớp\n`
+         + `        (và commands/validate-traces.tmpl khối \`summary\`).`);
+      continue;
+    }
+    if (summary[key] !== rows.length) {
+      fail('G2', `report CŨ — \`summary.${key}\` = ${summary[key]} nhưng sổ TSV đang có ${rows.length} scenario`,
+           [`Sổ đã thay đổi sau lần audit cuối (${report.generated_at || 'không rõ thời điểm'}).`,
+            `Mọi con số dưới đây — gồm cả các cờ 🔴 — nói về một trạng thái đã qua.`,
+            `Chạy /validate-traces rồi commit lại ${REPORT_BASENAME}.`].join('\n        '));
+    }
+  }
+
+  // (c) soft — phụ thuộc quy ước đếm, nên WARN chứ không FAIL. Sai ở đây thì tệ nhất là
+  //     ồn; ép cứng mà lệch quy ước thì cổng bị tắt — hỏng nặng hơn nhiều.
+  const byStatus = {};
+  for (const r of rows) byStatus[r.status] = (byStatus[r.status] || 0) + 1;
+
+  for (const [key, statusVal] of Object.entries(GATE.reconcile.soft || {})) {
+    if (!(key in summary)) continue;
+    const onDisk = byStatus[statusVal] || 0;
+    if (summary[key] !== onDisk) {
+      warn('G2', `\`summary.${key}\` = ${summary[key]} nhưng sổ có ${onDisk} row status=${statusVal}`,
+           `Report cũ, hoặc quy ước đếm khác. Không chặn — chạy /validate-traces để chắc.`);
+    }
+  }
+
+  // (d) per-SC (G48) — đối chiếu TỪNG scenario, không chỉ tổng số.
+  //
+  // So tổng bỏ lọt ca thường gặp nhất khi spec tiến hoá: một SC bị xoá + một SC được
+  // thêm trong cùng một lần ⇒ total_scs KHÔNG đổi ⇒ report cũ vẫn được coi là tươi.
+  // Khoá phải gồm platform: sc_id một mình không định danh được scenario.
+  const PS = GATE.reconcile.per_sc;
+  if (PS) {
+    const scs = flattenReportScenarios(report);
+    const hasPlatform = scs.length > 0 && scs.every(s => s[PS.key_fields[1]]);
+
+    if (!scs.length) {
+      warn('G2', 'report không kèm `prds[].ucs[].scenarios[]` — chỉ đối chiếu được tổng số',
+           'Kiểm độ tươi đang ở mức yếu: một SC bị xoá + một SC được thêm sẽ không bị phát hiện.');
+    } else if (!hasPlatform) {
+      // Backward-compat: report sinh bởi version trước G48. Không fail — người dùng chưa
+      // chạy lại /validate-traces không phải lỗi của họ.
+      warn('G2', 'report thiếu `platform` trong `scenarios[]` — đối chiếu chỉ ở mức tổng số',
+           [`Report sinh bởi version trước G48. sc_id một mình không phân biệt được web/app,`,
+            `nên không khoá được từng scenario.`,
+            `Chạy lại /validate-traces bằng version hiện tại để bật đối chiếu đầy đủ.`].join('\n        '));
+    } else {
+      const key = (o) => PS.key_fields.map(f => o[f]).join('@');
+      // Quy đổi ORPHANED: JSON cố ý chỉ có 4 giá trị status; row ORPHANED xuất ra là
+      // `status: DRIFT` + `orphaned: true` (validate-traces §Rules). Phải quy đổi TRƯỚC
+      // khi so, không thì mọi row ORPHANED đều báo lệch giả.
+      const norm = (s) => (s[PS.orphaned_flag] === true ? PS.orphaned_status : s[PS.compare]);
+
+      const inReport = new Map(scs.map(s => [key(s), norm(s)]));
+      const inBook   = new Map(rows.map(r => [key(r), r[PS.compare]]));
+
+      const missing = [...inBook.keys()].filter(k => !inReport.has(k));
+      const extra   = [...inReport.keys()].filter(k => !inBook.has(k));
+      const differ  = [...inBook.entries()]
+        .filter(([k, v]) => inReport.has(k) && inReport.get(k) !== v)
+        .map(([k, v]) => `${k}: sổ=${v} report=${inReport.get(k)}`);
+
+      const show = (a) => a.slice(0, 6).join(' · ') + (a.length > 6 ? ` … +${a.length - 6}` : '');
+
+      if (missing.length || extra.length) {
+        fail('G2', `report CŨ — lệch ${missing.length + extra.length} scenario so với sổ`,
+             [missing.length ? `Có trong sổ, thiếu ở report: ${show(missing)}` : null,
+              extra.length   ? `Có ở report, không còn trong sổ: ${show(extra)}` : null,
+              `Sổ đã thay đổi sau lần audit cuối (${report.generated_at || 'không rõ'}).`,
+              `Chạy /validate-traces rồi commit lại ${REPORT_BASENAME}.`].filter(Boolean).join('\n        '));
+      } else if (differ.length) {
+        fail('G2', `report CŨ — ${differ.length} scenario khác trạng thái so với sổ`,
+             [show(differ),
+              `Cùng tập scenario nhưng status đã đổi ⇒ audit cuối nói về một trạng thái đã qua.`,
+              `Chạy /validate-traces rồi commit lại ${REPORT_BASENAME}.`].join('\n        '));
+      }
+    }
+  }
+
+  if (!fails.some(f => f.stage === 'G2')) {
+    // `[].every()` là true — nên phải đòi CÓ scenario, không thì report rỗng sẽ khoe
+    // "đối chiếu từng SC" trong khi nó chẳng đối chiếu gì.
+    const scsNow = PS ? flattenReportScenarios(report) : [];
+    const PSok = scsNow.length > 0 && scsNow.every(s => s[PS.key_fields[1]]);
+    oks.push(`G2 report tươi — ${rows.length} scenario khớp sổ`
+           + (PSok ? ' (đối chiếu từng SC)' : ' (chỉ tổng số)')
+           + ` · audit lúc ${report.generated_at || '?'}`
+           + (domain !== 'all' ? ` · domain "${domain}"` : ''));
+  }
+} else if (report && NO_RECONCILE) {
+  warn('G2', 'bỏ qua kiểm độ tươi (--no-reconcile) — report có thể đã cũ',
+       'Cờ 🔴 dưới đây có thể nói về một trạng thái đã qua.');
+}
+
+// ── Tầng G3 — cờ 🔴 ───────────────────────────────────────────────────────────
+
+const blocking = [];
+
+if (report) {
+  const summary = report.summary || {};
+  const issues  = report.issues  || {};
+
+  for (const b of GATE.blocking) {
+    // Counter VẮNG MẶT không được coi là 0. `undefined > 0` là false ⇒ gate sẽ PASS trên
+    // code hỏng, im lặng. Đúng hình dạng G1 (consumer trỏ vào chỗ trống), và ở đây hậu quả
+    // là một PR hỏng được merge kèm dấu ✅.
+    if (!(b.counter in summary)) {
+      fail('G3', `report thiếu \`summary.${b.counter}\` — cờ này KHÔNG được kiểm`,
+           [`Không suy ra là 0: counter vắng mặt nghĩa là gate MÙ với cờ này, không phải sạch.`,
+            `Nguyên nhân: report sinh bởi version cũ, hoặc counter đã đổi tên.`,
+            `Sửa: chạy lại /validate-traces bằng version framework hiện tại. Nếu counter đổi tên`,
+            `thật thì cập nhật bin/trace-schema.json \`gate.blocking\` — self-check R9 canh chỗ đó.`].join('\n        '));
+      continue;
+    }
+
+    const n = Number(summary[b.counter]) || 0;
+    if (n === 0) continue;
+
+    const rows = Array.isArray(issues[b.issues_key]) ? issues[b.issues_key] : [];
+    blocking.push({
+      counter: b.counter, count: n, why: b.why, issues_key: b.issues_key,
+      items: rows.map(r => ({
+        label: (b.label_fields || []).map(f => r[f]).filter(Boolean).join(' · ') || '(không rõ)',
+        fix: r.fix || null,
+      })),
+    });
+  }
+
+  if (blocking.length) {
+    const total = blocking.reduce((s, b) => s + b.count, 0);
+    fail('G3', `${total} vấn đề 🔴 — code đang hỏng, KHÔNG merge`, null);
+  } else if (!fails.length) {
+    oks.push(`G3 không có cờ 🔴 — ${GATE.blocking.map(b => b.counter).length}/${GATE.blocking.length} cờ chặn đều bằng 0`);
+  }
+}
+
+// ── Output ────────────────────────────────────────────────────────────────────
+
+const passed = fails.length === 0;
+
+if (AS_JSON) {
+  console.log(JSON.stringify({
+    ok: passed,
+    report: reportPath ? rel(reportPath) : null,
+    generated_at: report && report.generated_at || null,
+    blocking, fails, warns,
+  }, null, 2));
+  process.exit(passed || WARN_ONLY ? 0 : 1);
+}
+
+console.log('');
+console.log('Trace gate (bin/trace-schema.json → gate) ...');
+console.log('');
+
+for (const o of oks) console.log(`  ✅ ${o}`);
+if (oks.length) console.log('');
+
+for (const w of warns) {
+  console.log(`  ⚠️  [${w.stage}] ${w.msg}`);
+  if (w.hint) console.log(`        ${w.hint}`);
+}
+if (warns.length) console.log('');
+
+for (const f of fails) {
+  console.log(`  🔴 [${f.stage}] ${f.msg}`);
+  if (f.hint) console.log(`        ${f.hint}`);
+  console.log('');
+}
+
+for (const b of blocking) {
+  console.log(`  🔴 ${b.counter} = ${b.count}  — ${b.why}`);
+  for (const it of b.items.slice(0, 8)) {
+    console.log(`       • ${it.label}`);
+    if (it.fix) console.log(`         → ${it.fix}`);
+  }
+  if (b.items.length > 8) console.log(`       … và ${b.items.length - 8} nữa`);
+  if (!b.items.length) {
+    console.log(`       (report không kèm chi tiết trong \`issues.${b.issues_key}\` — chạy /validate-traces để xem)`);
+  }
+  console.log('');
+}
+
+if (passed) {
+  console.log('  ✅ TRACE GATE PASSED');
+  console.log('');
+  // In giới hạn MỖI LẦN, kể cả khi xanh. Một cổng không nói rõ nó chưa chứng minh gì
+  // sẽ được người đọc hiểu là đã chứng minh mọi thứ — và đó là cách một cổng thật biến
+  // thành một cổng giả mà không ai sửa dòng code nào.
+  console.log('  Cổng này chứng minh: report khớp SỔ, và sổ không có cờ 🔴.');
+  console.log('  Cổng này KHÔNG chứng minh: sổ khớp CODE — việc đó cần /validate-traces');
+  console.log('  (quét tag trong source, đọc .feature, so version). Sửa code mà không đụng');
+  console.log('  sổ thì cổng vẫn xanh. Cho CI đầy đủ: chạy /validate-traces trước bước này.');
+} else {
+  console.log('  🔴 TRACE GATE FAILED');
+  console.log('');
+  console.log('  Đây là lớp lỗi mà build xanh + test từng-UC xanh KHÔNG phát hiện được:');
+  console.log('  luồng ghép chạy vào hàm rỗng, hoặc code trỏ vào scenario đã bị xoá.');
+  if (WARN_ONLY) console.log('  (--warn-only: exit 0 dù có lỗi)');
+}
+console.log('');
+
+process.exit(passed || WARN_ONLY ? 0 : 1);