@educa-corp/sdd-framework 0.5.0 → 0.6.0

package/bin/lint-trace.js

@@ -0,0 +1,602 @@
+#!/usr/bin/env node
+/**
+ * lint-trace — kiểm SỔ SÁCH THẬT (.trace/**) đối chiếu bin/trace-schema.json.
+ *
+ * Vì sao tồn tại (GAPS-v3 G38): bin/self-check.js canh CONTRACT — nó mở commands/*.tmpl
+ * và kiểm "lệnh có gọi đúng tên cột không". Nó không bao giờ mở một file .tsv thật.
+ * Trong khi đó sổ trace 24 cột được một LLM ghi BẰNG TAY, hàng chục lần mỗi feature,
+ * rồi được đọc lại bởi CÙNG một loại tác nhân (/validate-traces cũng là lệnh LLM).
+ * Không có mắt xác định nào trong vòng đó.
+ *
+ * Ca thuần khiết nhất: LLM quên một dấu `—` ở ô 17 (fe_tech_doc_revision — ô hay rỗng,
+ * nằm sát một ô revision khác). Mọi ô sau đó dồn sang trái một bậc. Ô 21 `status` —
+ * ô quyết định tô xanh/đỏ trên dashboard — nhận giá trị `2026-08-16`. Không gì báo lỗi.
+ * /validate-traces đọc tiếp, tính lại status, GHI NGƯỢC VÀO FILE → nướng vĩnh viễn phần
+ * dồn lệch, và giờ trông còn hợp lệ hơn trước. Sổ này "không regenerate được"
+ * (validate-traces.tmpl:645) nên phát hiện muộn là khôi phục bằng tay.
+ *
+ * Rule:
+ *   T1  header khớp tsv_columns (cho phép vắng cột ở ĐUÔI — backward-compat)  → ERROR
+ *       + dòng giữa file LẶP LẠI header (artifact union merge)                → ERROR
+ *   T2  mọi row đúng số ô bằng header (+ chẩn đoán chỗ lệch)                  → ERROR
+ *   T3  ô có enum ∈ vocabularies (theo binding khai trong schema)             → ERROR
+ *   T4  sc_id unique trong mỗi sổ                                            → ERROR
+ *   T5  tên file khớp {UC-ID}-{platform}.tsv                                 → ERROR
+ *   T6  ô ngày parse được thành ngày hợp lệ                                   → ERROR
+ *   T7  không có marker conflict git trong bất kỳ file .trace/**             → ERROR
+ *   T8  trace-history*.jsonl: mỗi dòng một JSON object đủ key bắt buộc        → ERROR
+ *   T9  mỗi sổ TSV có .feature đúng platform tồn tại (sổ mồ côi)             → WARN
+ *   T10 sổ có luật merge (merge=union + text eol=lf) — hỏi `git check-attr`   → WARN
+ *
+ * T4 + T7 + T10 là cụm G40 (luật merge git): `merge=union` đổi *mất-row-im-lặng* thành
+ * *trùng-row-bắt-được*, nên union KHÔNG được bật mà thiếu T4. T10 canh chính luật đó — đặt
+ * ở đây chứ không chỉ ở /sync để CI kiểm được, thay vì phụ thuộc ai tự nguyện chạy lệnh chat.
+ *
+ * KHÔNG phát biểu lại contract: header, enum, tên bảng phụ đều DẪN XUẤT từ
+ * bin/trace-schema.json. Thêm cột/vocabulary mới vào schema mà quên dạy file này →
+ * self-check.js R8 fail build.
+ *
+ * Chạy: node bin/lint-trace.js [--trace DIR[,DIR]] [--specs DIR] [--warn-only] [--json]
+ *       exit 1 nếu có ERROR (0 với --warn-only)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_PATH = path.join(__dirname, 'trace-schema.json');
+const schema = JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8'));
+
+// ── 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 TRACE_DIRS = flag('--trace', '.trace').split(',').map(s => s.trim()).filter(Boolean);
+const SPECS_DIR  = flag('--specs', 'specs');
+
+// ── Contract dẫn xuất từ schema ───────────────────────────────────────────────
+//
+// tsv_columns KHÔNG xếp theo thứ tự cột trong file schema (ba entry cuối là n:23,
+// n:24, n:22). `n` là thứ tự authoritative — sort theo nó, đừng dùng thứ tự array.
+// self-check.js R8c canh việc `n` là 1..N liền mạch, không trùng.
+const CANON = schema.tsv_columns
+  .slice()
+  .sort((a, b) => a.n - b.n)
+  .map(c => c.name);
+
+const AUX = schema.aux_tables.find(t => t.name === '_seams.tsv') || null;
+
+/**
+ * Binding enum → nơi kiểm, đọc từ vocabularies. Mỗi vocabulary khai một trong:
+ *   column           → một cột TSV chính
+ *   columns          → nhiều cột TSV chính
+ *   aux_table + aux_column → một cột của bảng phụ
+ *   filename_segment → một đoạn trong tên file
+ *   $lint: "n/a — …" → cố ý không thuộc phạm vi lint (phải nêu lý do)
+ * Thiếu tất cả → self-check.js R8a fail build.
+ */
+function buildEnumBindings() {
+  const mainCols = new Map();   // tên cột → { values, vocab }
+  const auxCols  = new Map();
+  let platformValues = null;
+
+  for (const [vocab, def] of Object.entries(schema.vocabularies)) {
+    if (vocab.startsWith('$') || !def || !def.values) continue;
+    const cols = def.columns || (def.column ? [def.column] : []);
+    for (const c of cols) mainCols.set(c, { values: def.values, vocab });
+    if (def.aux_column) auxCols.set(def.aux_column, { values: def.values, vocab });
+    if (def.filename_segment) platformValues = def.values;
+  }
+  return { mainCols, auxCols, platformValues };
+}
+const ENUMS = buildEnumBindings();
+
+// Ô "chưa biết" — framework dùng `—` (em dash) làm placeholder ở mọi cột.
+// Rỗng cũng chấp nhận: TSV cũ có cột vắng, và union merge có thể để ô trống.
+const UNKNOWN = new Set(['—', '-', '', 'n/a', 'N/A']);
+const isUnknown = v => UNKNOWN.has(String(v).trim());
+
+// Cột mang ngày: hậu tố _at, hoặc last_updated. Dẫn xuất từ tên, không hard-code danh sách.
+const isDateCol  = name => /_at$/.test(name) || name === 'last_updated';
+const isCountCol = name => /_count$/.test(name);
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+function isValidDate(v) {
+  const s = String(v).trim();
+  if (!DATE_RE.test(s)) return false;
+  const [y, m, d] = s.slice(0, 10).split('-').map(Number);
+  const dt = new Date(Date.UTC(y, m - 1, d));
+  return dt.getUTCFullYear() === y && dt.getUTCMonth() === m - 1 && dt.getUTCDate() === d;
+}
+
+// ── Thu findings ──────────────────────────────────────────────────────────────
+
+const errors = [];
+const warns  = [];
+const infos  = [];
+const err  = (rule, where, msg, hint) => errors.push({ rule, where, msg, hint });
+const warn = (rule, where, msg, hint) => warns.push({ rule, where, msg, hint });
+
+// ── Đi cây thư mục ────────────────────────────────────────────────────────────
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, out);
+    else out.push(p);
+  }
+  return out;
+}
+
+const rel = p => path.relative(process.cwd(), p).replace(/\\/g, '/');
+
+// Tách dòng, giữ số dòng thật (1-based) để báo lỗi trỏ đúng chỗ.
+function readLines(file) {
+  return fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n').split('\n');
+}
+
+// ── T7 — marker conflict git ──────────────────────────────────────────────────
+//
+// Chạy TRƯỚC mọi rule khác và trên MỌI file: một marker lọt vào TSV làm T1/T2 báo
+// một lỗi vô nghĩa ("row có 1 ô") che mất nguyên nhân thật. Có marker thì nói thẳng.
+const CONFLICT_RE = /^(<{7}|={7}|>{7})(\s|$)/;
+
+function lintConflictMarkers(file) {
+  const lines = readLines(file);
+  const hits = [];
+  lines.forEach((ln, i) => { if (CONFLICT_RE.test(ln)) hits.push({ line: i + 1, text: ln.slice(0, 60) }); });
+  if (!hits.length) return false;
+  err('T7', `${rel(file)}:${hits[0].line}`,
+      `${hits.length} marker conflict git còn trong sổ trace`,
+      [`Dòng: ${hits.map(h => h.line).join(', ')}`,
+       `Sổ trace là dữ liệu KHÔNG regenerate được. Giải conflict bằng cách GIỮ CẢ HAI BÊN,`,
+       `rồi chạy lại lint (T4 bắt row trùng) và /validate-traces để reconcile về một row.`,
+       `Đừng bao giờ giải conflict trace bằng "take mine/theirs" — mất row là mất vĩnh viễn.`].join('\n        '));
+  return true;
+}
+
+// ── T1/T2/T3/T4/T6 — sổ TSV chính ─────────────────────────────────────────────
+
+/**
+ * Chẩn đoán chỗ lệch khi số ô sai: tìm ô ĐẦU TIÊN mang giá trị không đúng kiểu của
+ * cột đó. Đây gần như luôn là chỗ ngay sau dấu tab bị thiếu/thừa. Không đoán chắc,
+ * chỉ chỉ hướng — người đọc còn phải so với row lành bên cạnh.
+ */
+function diagnoseShift(header, fields) {
+  const delta = fields.length - header.length;
+  const gap = delta < 0
+    ? `Thiếu ${-delta} ô — nghi quên một dấu tab (hoặc quên placeholder \`—\` cho một ô rỗng).`
+    : `Thừa ${delta} ô — nghi một giá trị có chứa tab, hoặc thừa dấu tab.`;
+
+  for (let i = 0; i < Math.min(header.length, fields.length); i++) {
+    const col = header[i];
+    const v = fields[i];
+    if (isUnknown(v)) continue;
+    const enumDef = ENUMS.mainCols.get(col);
+    const bad =
+      (enumDef && !enumDef.values.includes(String(v).trim())) ||
+      (isDateCol(col) && !isValidDate(v)) ||
+      (isCountCol(col) && !/^\d+$/.test(String(v).trim()));
+    if (bad) {
+      return `${gap}\n` +
+             `        Dấu hiệu đầu tiên: ô ${i + 1} (${col}) đang chứa "${String(v).slice(0, 30)}" —` +
+             ` không đúng kiểu của cột đó,\n` +
+             `        nên chỗ lệch nằm ở đâu đó TRƯỚC ô ${i + 1}. So với một row lành trong cùng file.`;
+    }
+  }
+  return `${gap}\n        So với một row lành trong cùng file để thấy chỗ thiếu/thừa tab.`;
+}
+
+function lintBook(file) {
+  const lines = readLines(file);
+  const nonEmpty = lines.map((t, i) => ({ t, n: i + 1 })).filter(x => x.t.trim() !== '');
+  if (!nonEmpty.length) {
+    warn('T1', rel(file), 'Sổ rỗng — không có cả header');
+    return;
+  }
+
+  // ── T1 — header ─────────────────────────────────────────────────────────────
+  const header = nonEmpty[0].t.split('\t').map(s => s.trim());
+
+  if (header.length > CANON.length) {
+    err('T1', `${rel(file)}:${nonEmpty[0].n}`,
+        `header có ${header.length} cột, contract khai ${CANON.length}`,
+        `Cột lạ: ${header.slice(CANON.length).join(', ')}\n` +
+        `        Thêm cột thật thì khai vào bin/trace-schema.json TRƯỚC (rules/workflow.md §Trace Contract).`);
+    return;   // header sai thì mọi kiểm theo cột bên dưới đều vô nghĩa
+  }
+
+  let headerOk = true;
+  for (let i = 0; i < header.length; i++) {
+    if (header[i] !== CANON[i]) {
+      err('T1', `${rel(file)}:${nonEmpty[0].n}`,
+          `cột ${i + 1} tên là "${header[i]}", contract khai "${CANON[i]}"`,
+          `Header đúng (${CANON.length} cột, cho phép vắng ở ĐUÔI):\n        ${CANON.join(' → ')}`);
+      headerOk = false;
+      break;
+    }
+  }
+  if (!headerOk) return;
+
+  if (header.length < CANON.length) {
+    infos.push(`${rel(file)} — header ${header.length}/${CANON.length} cột ` +
+               `(vắng ở đuôi: ${CANON.slice(header.length).join(', ')}). Backward-compat OK; ` +
+               `/validate-traces sẽ nâng header ở lần ghi tới.`);
+  }
+
+  // ── T2/T3/T4/T6 — từng row ─────────────────────────────────────────────────
+  const headerLine = nonEmpty[0].t.trim();
+  const seen = new Map();
+
+  for (const { t, n } of nonEmpty.slice(1)) {
+    const f = t.split('\t');
+    const at = `${rel(file)}:${n}`;
+
+    // Header lặp lại giữa file — artifact union merge thường gặp NHẤT. Không có check
+    // riêng thì nó hiện ra dưới dạng 5-6 lỗi T3/T6 rời rạc ("ô 21 (status) = 'status'"),
+    // đúng nhưng người đọc phải tự ghép lại mới hiểu chuyện gì đã xảy ra.
+    if (t.trim() === headerLine) {
+      err('T1', at,
+          `dòng này LẶP LẠI header — sổ đã bị gộp nhân đôi`,
+          `Gần như luôn là union merge trên file có line-ending lệch: một máy ghi CRLF,\n` +
+          `        git thấy MỌI dòng đã đổi, union giữ cả hai bản ⇒ nhân đôi cả file.\n` +
+          `        Sửa: xoá phần lặp (T4 bên dưới chỉ ra row nào trùng), rồi CHẶN tái diễn bằng\n` +
+          `        \`text eol=lf\` trong ${path.dirname(rel(file)).split('/')[0]}/.gitattributes —\n` +
+          `        /sync Step 4c kiểm và tạo hộ.`);
+      continue;   // đừng báo thêm 6 lỗi T3/T6 cho cùng một dòng này
+    }
+
+    // T2
+    if (f.length !== header.length) {
+      err('T2', at,
+          `row có ${f.length} ô, header có ${header.length}`,
+          diagnoseShift(header, f));
+      continue;   // ô đã lệch cột — kiểm enum/ngày theo vị trí sẽ báo lỗi rác
+    }
+
+    // T4
+    const scIdIdx = header.indexOf('sc_id');
+    if (scIdIdx !== -1) {
+      const id = f[scIdIdx].trim();
+      if (id && !isUnknown(id)) {
+        if (seen.has(id)) {
+          err('T4', at,
+              `sc_id "${id}" trùng với dòng ${seen.get(id)}`,
+              `Một sc_id = một row trong mỗi sổ. Nguyên nhân thường gặp: union merge vừa gộp\n` +
+              `        hai nhánh cùng ghi scenario này (đúng như thiết kế — xem .gitattributes).\n` +
+              `        Giữ row mới hơn theo last_updated, rồi /validate-traces reconcile.`);
+        } else {
+          seen.set(id, n);
+        }
+      }
+    }
+
+    // T3 + T6
+    for (let i = 0; i < header.length; i++) {
+      const col = header[i];
+      const v = f[i];
+      if (isUnknown(v)) continue;
+
+      const enumDef = ENUMS.mainCols.get(col);
+      if (enumDef && !enumDef.values.includes(String(v).trim())) {
+        err('T3', at,
+            `ô ${i + 1} (${col}) = "${String(v).slice(0, 40)}" không thuộc vocabulary "${enumDef.vocab}"`,
+            `Giá trị cho phép: ${enumDef.values.join(' | ')} (hoặc — nếu chưa biết)`);
+      }
+
+      if (isDateCol(col) && !isValidDate(v)) {
+        err('T6', at,
+            `ô ${i + 1} (${col}) = "${String(v).slice(0, 40)}" không phải ngày hợp lệ`,
+            `Định dạng: YYYY-MM-DD hoặc ISO-8601 đầy đủ (hoặc — nếu chưa biết)`);
+      }
+    }
+  }
+}
+
+// ── T3 — bảng phụ _seams.tsv ──────────────────────────────────────────────────
+
+function lintSeams(file) {
+  if (!AUX) return;
+  const lines = readLines(file).map((t, i) => ({ t, n: i + 1 })).filter(x => x.t.trim() !== '');
+  if (!lines.length) return;
+
+  const header = lines[0].t.split('\t').map(s => s.trim());
+  const canon = AUX.columns;
+
+  if (header.length !== canon.length || header.some((h, i) => h !== canon[i])) {
+    err('T1', `${rel(file)}:${lines[0].n}`,
+        `header _seams.tsv lệch contract`,
+        `Đang có : ${header.join(' → ')}\n        Contract: ${canon.join(' → ')}`);
+    return;
+  }
+
+  for (const { t, n } of lines.slice(1)) {
+    const f = t.split('\t');
+    const at = `${rel(file)}:${n}`;
+    if (f.length !== canon.length) {
+      err('T2', at, `row có ${f.length} ô, header có ${canon.length}`, diagnoseShift(header, f));
+      continue;
+    }
+    for (let i = 0; i < canon.length; i++) {
+      const enumDef = ENUMS.auxCols.get(canon[i]);
+      if (!enumDef || isUnknown(f[i])) continue;
+      if (!enumDef.values.includes(String(f[i]).trim())) {
+        err('T3', at,
+            `ô ${i + 1} (${canon[i]}) = "${String(f[i]).slice(0, 40)}" không thuộc vocabulary "${enumDef.vocab}"`,
+            `Giá trị cho phép: ${enumDef.values.join(' | ')}`);
+      }
+    }
+  }
+}
+
+// ── T5 — tên file sổ ──────────────────────────────────────────────────────────
+//
+// Tên sổ mang platform, và đó là thứ DUY NHẤT nói row này thuộc platform nào
+// (validate-traces.tmpl Step 2 lấy platform từ tên file TSV). Thiếu đoạn đó thì
+// /validate-traces không tìm ra .feature tương ứng và cả sổ trở nên vô hình.
+function lintBookName(file) {
+  const base = path.basename(file);
+  const pf = ENUMS.platformValues;
+  if (!pf) return null;   // schema chưa khai binding — R8a của self-check lo việc đó
+
+  const m = base.match(new RegExp(`^(.+)-(${pf.join('|')})\\.tsv$`));
+  if (!m) {
+    err('T5', rel(file),
+        `tên sổ không khớp {UC-ID}-{platform}.tsv`,
+        `platform phải là một trong: ${pf.join(' | ')}\n` +
+        `        Thiếu đoạn platform → /validate-traces không resolve được .feature và bỏ qua cả sổ.`);
+    return null;
+  }
+  return { ucId: m[1], platform: m[2] };
+}
+
+// ── T8 — trace-history*.jsonl ─────────────────────────────────────────────────
+
+const HISTORY_KEYS = ['at', 'domain', 'summary', 'changed', 'flags_opened', 'flags_closed'];
+
+function lintHistory(file) {
+  const lines = readLines(file);
+  lines.forEach((ln, i) => {
+    if (ln.trim() === '') return;
+    const at = `${rel(file)}:${i + 1}`;
+    let rec;
+    try {
+      rec = JSON.parse(ln);
+    } catch (e) {
+      err('T8', at, `dòng không phải JSON hợp lệ: ${e.message}`,
+          `Mỗi dòng là MỘT bản ghi trọn vẹn trên MỘT dòng (JSONL).\n` +
+          `        Đây là lịch sử tích luỹ — không regenerate được. Sửa tay, đừng xoá dòng.`);
+      return;
+    }
+    if (rec === null || typeof rec !== 'object' || Array.isArray(rec)) {
+      err('T8', at, 'dòng phải là một JSON object', null);
+      return;
+    }
+    const missing = HISTORY_KEYS.filter(k => !(k in rec));
+    if (missing.length) {
+      err('T8', at, `thiếu key bắt buộc: ${missing.join(', ')}`,
+          `Contract: {"at","domain","summary","changed","flags_opened","flags_closed"}\n` +
+          `        (validate-traces.tmpl Step 8c)`);
+    }
+    if ('at' in rec && !isValidDate(rec.at)) {
+      err('T8', at, `"at" = "${String(rec.at).slice(0, 40)}" không phải ISO-8601 hợp lệ`, null);
+    }
+  });
+}
+
+// ── T10 — luật merge cho sổ ───────────────────────────────────────────────────
+//
+// Vì sao ở đây và không chỉ ở /sync Step 4c (G40): luật merge là thứ giữ cho sổ không
+// mất row khi hai nhánh gặp nhau. Nếu chỉ /sync kiểm thì nó phụ thuộc việc có người
+// TỰ NGUYỆN chạy một lệnh chat — đúng lớp vấn đề G39. Ở đây thì CI canh được.
+//
+// KHÔNG tự đọc .gitattributes: luật có thể nằm ở gốc repo, trong {trace_dir}, hay bất kỳ
+// cấp thư mục nào ở giữa, và git có thứ tự ưu tiên riêng. Hỏi thẳng git bằng check-attr —
+// đó là câu trả lời authoritative, và nó đúng bất kể luật được đặt ở đâu.
+function lintMergeAttr(sampleFile) {
+  let out;
+  try {
+    out = require('child_process')
+      .execSync(`git check-attr merge eol -- "${sampleFile}"`,
+                { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch {
+    return;   // không có git, hoặc không nằm trong repo — không phán gì
+  }
+
+  const merge = /merge:\s*(\S+)/.exec(out);
+  const eol   = /eol:\s*(\S+)/.exec(out);
+  const mergeVal = merge ? merge[1] : 'unspecified';
+  const eolVal   = eol ? eol[1] : 'unspecified';
+
+  const missing = [];
+  if (mergeVal !== 'union') missing.push('merge=union');
+  if (eolVal !== 'lf')      missing.push('text eol=lf');
+  if (!missing.length) return;
+
+  warn('T10', rel(sampleFile),
+       `sổ trace chưa có luật merge (${missing.join(' + ')} — git đang báo merge:${mergeVal} eol:${eolVal})`,
+       [`Sổ trace PHẢI commit và được nhiều người ghi trên nhiều nhánh song song. Không có luật:`,
+        `  • thiếu merge=union → merge song song CONFLICT, và giải bằng "take mine" là MẤT ROW`,
+        `    của người kia, im lặng. Với trace-history.jsonl thì MỌI cặp nhánh đều conflict.`,
+        `  • thiếu text eol=lf → một máy ghi CRLF, git thấy MỌI dòng đã đổi, union giữ cả hai`,
+        `    bản ⇒ NHÂN ĐÔI CẢ FILE (gồm dòng header).`,
+        `Sửa — tạo ${path.dirname(rel(sampleFile)).split('/')[0]}/.gitattributes:`,
+        `  *.tsv    text eol=lf merge=union`,
+        `  *.jsonl  text eol=lf merge=union`,
+        `(union là driver built-in của git — không ai cần chạy git config gì thêm.)`,
+        `KHÔNG thêm *.json: trace-report.json nằm cùng chỗ và union trên JSON tạo JSON không hợp lệ.`,
+        `Hoặc để /sync Step 4c tạo hộ.`].join('\n        '));
+}
+
+// ── T11 — sổ có nằm trong git không ───────────────────────────────────────────
+//
+// Cách mất sổ TỆ NHẤT, và tệ hơn T10 hẳn một bậc: sổ không được đưa vào git ngay từ
+// đầu. Máy người viết vẫn có sổ, dashboard vẫn hiện số — nhìn hoàn toàn bình thường.
+// Người thứ hai clone repo về thì KHÔNG THẤY GÌ, và lịch sử tích luỹ mất vĩnh viễn.
+//
+// Phép kiểm này ĐÃ tồn tại trong `/sync` Step 4b từ G29 — nhưng chỉ ở đó, tức chỉ chạy
+// khi có người tự nguyện gõ một lệnh chat. Không máy nào canh. Đưa vào đây để
+// `--gate-trace` nâng nó thành cổng chặn (xem `gate.config_preconditions` trong schema).
+//
+// Hỏi thẳng git thay vì đọc .gitignore: luật ignore có thể đến từ .gitignore ở bất kỳ
+// cấp thư mục nào, từ .git/info/exclude, hay từ core.excludesFile toàn cục.
+function lintGitTracked(traceRoot) {
+  const cp = require('child_process');
+  const rel_ = rel(traceRoot);
+  let out;
+  try {
+    // check-ignore: exit 0 = ĐANG bị ignore. Dùng spawnSync để đọc được exit code.
+    out = cp.spawnSync('git', ['check-ignore', '-q', '--', traceRoot],
+                       { encoding: 'utf8', stdio: ['ignore', 'ignore', 'ignore'] });
+  } catch {
+    return;   // không có git — không phán gì
+  }
+  if (out.error || out.status === 128) return;   // không nằm trong git repo
+  if (out.status !== 0) return;                  // exit 1 = không bị ignore → sạch
+
+  warn('T11', rel_,
+       'SỔ TRACE ĐANG BỊ GITIGNORE — nó không được lưu vào git',
+       [`Đây là cách mất sổ tệ nhất, và nó KHÔNG ỒN ÀO:`,
+        `  • máy bạn vẫn có sổ, dashboard vẫn hiện số → nhìn như bình thường`,
+        `  • người thứ hai clone repo về → KHÔNG THẤY GÌ`,
+        `  • trace-history.jsonl (lịch sử tích luỹ) → mất VĨNH VIỄN, không dựng lại được`,
+        `Sửa:`,
+        `  1. gỡ dòng khớp "${rel_}" khỏi .gitignore (hoặc .git/info/exclude)`,
+        `  2. git add -f ${rel_} && git commit -m "restore trace state"`,
+        `Nguyên nhân thường gặp: bản trước v0.4.3 gọi panel mirror là ".trace" (trùng tên sổ`,
+        `gốc), nên một luật gitignore theo TÊN đã nhắm trúng sổ gốc. Xem GAPS-v2 G29.`].join('\n        '));
+}
+
+// ── T9 — sổ mồ côi ────────────────────────────────────────────────────────────
+//
+// WARN không ERROR: có ca hợp lệ — scenario bị xoá nhưng row được GIỮ LẠI với
+// status ORPHANED để người quyết định (G4). Sổ mồ côi thật thì cũng nên biết.
+function lintOrphanBook(file, meta, traceRoot) {
+  if (!meta || !fs.existsSync(SPECS_DIR)) return;
+
+  const relPath = path.relative(traceRoot, file).replace(/\\/g, '/').split('/');
+  if (relPath.length < 3) return;   // không theo {domain}/{prd-slug}/ — bố cục cũ, để migrate lo
+  const [domain, prdSlug] = relPath;
+
+  const bddDir = path.join(SPECS_DIR, domain, prdSlug, 'bdd', meta.platform);
+  if (!fs.existsSync(bddDir)) {
+    warn('T9', rel(file),
+         `không tìm thấy thư mục BDD tương ứng`,
+         `Mong đợi: ${rel(bddDir)}/\n` +
+         `        Sổ có thể mồ côi (feature đã đổi tên/xoá), hoặc --specs đang trỏ sai chỗ.`);
+    return;
+  }
+  const hasFeature = fs.readdirSync(bddDir)
+    .some(f => f.endsWith('.feature') && f.includes(meta.ucId));
+  if (!hasFeature) {
+    warn('T9', rel(file),
+         `không có file .feature nào cho ${meta.ucId} trong ${meta.platform}`,
+         `Đã tìm ở: ${rel(bddDir)}/\n` +
+         `        Sổ mồ côi, hoặc UC-ID đã đổi. /validate-traces sẽ báo ORPHANED/TRACE_ORPHAN.`);
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+let scanned = { books: 0, seams: 0, history: 0, files: 0 };
+const foundDirs = [];
+
+for (const dir of TRACE_DIRS) {
+  const abs = path.resolve(dir);
+  if (!fs.existsSync(abs)) continue;
+  foundDirs.push(dir);
+
+  let sampleForAttr = null;
+
+  for (const file of walk(abs)) {
+    scanned.files++;
+    const base = path.basename(file);
+
+    // Phân loại + ĐẾM trước khi có thể short-circuit: một file bị T7 chặn vẫn LÀ một sổ
+    // đã quét. Đếm sau nhánh `continue` thì report nói "đã quét 0 sổ" trong đúng lúc nó
+    // vừa tìm ra lỗi nặng nhất — tự làm mình mất tin cậy.
+    const kind = base === '_seams.tsv'                                 ? 'seams'
+               : base.endsWith('.tsv')                                 ? 'book'
+               : /^trace-history(\.\d{4}-\d{2})?\.jsonl$/.test(base)   ? 'history'
+               : null;
+    if (kind === 'seams')   scanned.seams++;
+    if (kind === 'book')    scanned.books++;
+    if (kind === 'history') scanned.history++;
+
+    // Một file mẫu là đủ cho T10: luật áp theo pattern, không theo từng file.
+    if ((kind === 'book' || kind === 'history') && !sampleForAttr) sampleForAttr = file;
+
+    // T7 trước mọi rule khác — marker che mất nguyên nhân thật của T1/T2
+    if (lintConflictMarkers(file)) continue;
+
+    if (kind === 'seams') {
+      lintSeams(file);
+    } else if (kind === 'book') {
+      const meta = lintBookName(file);
+      lintBook(file);
+      lintOrphanBook(file, meta, abs);
+    } else if (kind === 'history') {
+      lintHistory(file);
+    }
+  }
+
+  if (sampleForAttr) lintMergeAttr(sampleForAttr);
+  lintGitTracked(abs);
+}
+
+// ── Report ────────────────────────────────────────────────────────────────────
+
+if (AS_JSON) {
+  console.log(JSON.stringify({
+    ok: errors.length === 0,
+    scanned, trace_dirs: foundDirs, errors, warns, infos,
+  }, null, 2));
+  process.exit(errors.length && !WARN_ONLY ? 1 : 0);
+}
+
+console.log('');
+console.log('Lint trace (bin/trace-schema.json) ...');
+console.log('');
+
+if (!foundDirs.length) {
+  console.log(`  ℹ️  Không tìm thấy trace dir nào (đã thử: ${TRACE_DIRS.join(', ')}).`);
+  console.log(`      Chưa có sổ trace thì chưa có gì để kiểm — chạy /generate-bdd để khởi tạo.`);
+  console.log('');
+  process.exit(0);
+}
+
+const show = (list, icon) => {
+  for (const f of list) {
+    console.log(`  ${icon} ${f.where}`);
+    console.log(`      ${f.rule}: ${f.msg}`);
+    if (f.hint) console.log(`        ${f.hint}`);
+    console.log('');
+  }
+};
+
+show(errors, '🔴');
+show(warns, '⚠️ ');
+
+for (const i of infos) console.log(`  ℹ️  ${i}\n`);
+
+const tally = `${scanned.books} sổ + ${scanned.seams} bảng phụ + ${scanned.history} file lịch sử`;
+
+if (errors.length === 0 && warns.length === 0) {
+  console.log(`  ✅ ${tally} — khớp contract (${CANON.length} cột)`);
+} else {
+  console.log(`  ${errors.length} error · ${warns.length} warning — đã quét ${tally}`);
+  if (errors.length) {
+    console.log('');
+    console.log('  Sổ trace là dữ liệu KHÔNG regenerate được. Sửa file rồi chạy lại;');
+    console.log('  `git log -p {file}` để tìm lần ghi làm hỏng.');
+  }
+}
+console.log('');
+
+process.exit(errors.length && !WARN_ONLY ? 1 : 0);