@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/bin/gate-trace.js

@@ -0,0 +1,487 @@
+#!/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ờ 🔴 ở phần chưa audit 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.
+  //
+  // G57 — LUẬT TUYỆT ĐỐI, không phụ thuộc trên đĩa có bao nhiêu domain.
+  // Bản cũ hỏi "còn domain NÀO KHÁC không": `if (others.length) fail`. Trong repo MỘT domain,
+  // `others` là RỖNG ⇒ KHÔNG fail ⇒ một report hẹp-theo-PRD (hoặc theo-UC) được nhận là "toàn
+  // bộ". Lúc chưa có cờ scope thì vô hại; nó BẬT NGAY khi scoping thành khả dụng — tức bản fix
+  // G57 sẽ tự tay mở đúng cái false-green mà chú thích ngay trên cảnh báo.
+  // Nên: scope.kind !== 'all' ⇒ FAIL. Hết.
+  const scope = report.scope;
+  if (scope && typeof scope === 'object') {
+    if (scope.kind !== 'all') {
+      const what = scope.value && scope.value !== 'all'
+        ? `${scope.kind}="${scope.value}"` : String(scope.kind);
+      fail('G2', `report chỉ phủ ${what} — đây KHÔNG phải một audit đầy đủ`,
+           ['Cờ 🔴 ngoài phạm vi đó hoàn toàn vô hình với gate.',
+            '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/--prd/--uc, rồi commit report.'].join('\n        '));
+    }
+  } else if (domain !== 'all') {
+    // TƯƠNG THÍCH NGƯỢC: report sinh trước G57 không có `scope`. Rơi về logic cũ theo `domain`
+    // và nói rõ kiểm đang ở mức YẾU — KHÔNG fail vì thiếu field. Người dùng chưa chạy lại
+    // /validate-traces không phải là lỗi của họ. Cùng khuôn G48 đã dùng cho `platform`.
+    warn('G2', 'report không có field `scope` (sinh trước G57) — kiểm độ phủ đang ở mức YẾU',
+         'Chạy lại /validate-traces để report mang `scope`; chỉ khi đó gate mới chặn được mọi\n'
+       + '        loại audit phiến diện, kể cả hẹp-theo-PRD trong repo một domain.');
+    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);