@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/bin/self-check.js

@@ -8,16 +8,33 @@
  * 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)
+ * 7 rule — áp cho tags · tsv_columns · aux_tables (_seams.tsv) · queues (feedback/*):
+ *   R1  field/hàng đợi có read_by nhưng KHÔNG có producer → ERROR  (bắt được G1; queue: G26)
+ *   R2  field có producer nhưng KHÔNG ai đọc             → WARN   (bắt được G15, fe_phase, test_type)
  *   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)
+ *       nó KHÔNG nhắc tên field/cột/path_key             → ERROR  (bắt được G5, G12, G13, G31, G32)
  *   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)
+ *   R5  pattern bị cấm xuất hiện trở lại                 → ERROR  (bắt được G3, G8, G10, G18, G21, G11)
  *   R6  giá trị enum khai trong vocabulary mà không actor
  *       nào dùng                                         → WARN   (bắt được G19: integration vs integrated)
+ *   R7  audit flag thiếu counter {flag}_count trong CẢ
+ *       Step 7 LẪN khối `summary` của validate-traces     → ERROR  (bắt được G33)
+ *   R8  bin/lint-trace.js tụt lại sau schema             → ERROR  (bắt được G38)
+ *       R8a vocabulary không khai binding (neo vào đâu để kiểm sổ thật?)
+ *       R8b binding đã khai mà lint-trace không đọc key đó
+ *       R8c `n` của tsv_columns trùng/hổng — lint dựng header theo `n`, sai `n` = sai header
+ *       R8d bảng phụ nằm ngoài phạm vi lint
+ *
+ * RANH GIỚI R1–R7 vs R8: R1–R7 canh CONTRACT (đọc commands/*.tmpl — "lệnh có gọi đúng tên
+ * cột không"). Không rule nào mở một `.tsv` THẬT ra xem. Đó là G38: sổ 24 cột do LLM ghi tay,
+ * một dấu tab thiếu dồn mọi ô sang trái và ô `status` nhận một ngày tháng — không gì báo.
+ * bin/lint-trace.js canh DỮ LIỆU; R8 canh việc nó theo kịp contract.
+ *
+ * PHẠM VI (G30): trước đó schema chỉ phủ 16/44 tag — R1/R3 mù với 28 cái còn lại, và ĐÓ LÀ
+ * cách G31 (@trace.service: 2 consumer khai, 0 nơi chứa) cùng G32 (design-spec: 0 cột/0 tag/
+ * 0 cờ) sống qua nhiều version với dấu ✅. Dấu ✅ chỉ có nghĩa "phần ĐÃ KHAI thì đúng".
+ * Giữ phạm vi đầy đủ: thêm tag/cột/bảng/hàng đợi mới thì khai NGAY, đừng để dồn.
  *
  * Chạy: node bin/self-check.js            (exit 1 nếu có ERROR)
  *       node bin/self-check.js --warn-only (luôn exit 0)
@@ -126,6 +143,59 @@ function checkField(kind, name, def) {
 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);
 
+// Bảng phụ (_seams.tsv) — nguồn của 2 cờ 🔴 chặn PR nhưng nằm ngoài SoT tới G30.
+// Chạy CÙNG checkField, không cần rule mới: mỗi cột là một field có producer/consumer.
+for (const t of schema.aux_tables || []) {
+  checkField(`bảng phụ \`${t.name}\``, t.name, t);          // file phải được cả 2 đầu nhắc tên
+  // `column_actors` = actor thao tác ở MỨC CỘT (ghi/parse từng field). Actor chỉ dùng bảng ở
+  // MỨC BẢNG (vd review-code chỉ kiểm "có dòng PENDING không") KHÔNG phải nhắc đủ tên cột —
+  // đòi thế là báo oan. Không khai `column_actors` → mặc định mọi actor.
+  const colActors = t.column_actors || [...(t.written_by || []), ...(t.read_by || [])];
+  for (const col of t.columns || []) {
+    for (const actor of new Set(colActors)) {
+      const text = actorText[actor];
+      if (text === undefined) continue;
+      if (!mentions(text, col)) {
+        err('R3', `cột \`${t.name}:${col}\`: schema khai \`${actor}\` đụng bảng này nhưng ${schema.actors[actor]} KHÔNG nhắc cột \`${col}\``,
+            `Hoặc lệnh thiếu implement, hoặc cột đã đổi tên. Bảng này là NGUỒN của SEAM_UNWIRED/STUB_UNRESOLVED —\n`
+          + `        đổi tên cột mà không ai bắt được thì hai cờ 🔴 chặn PR sẽ mù trong im lặng.`);
+      }
+    }
+  }
+}
+
+// Hàng đợi feedback — bắt ca "hàng đợi có producer nhưng KHÔNG ai drain" (hình dạng của G26).
+//
+// KHÔNG dùng chung mentions() với tag/cột: path key luôn xuất hiện dưới dạng `{paths.X}`,
+// tức LUÔN có dấu `.` đứng trước — mà mentions() cố ý chặn ký tự đó (để `@trace.XXsc_version`
+// không bị coi là đã nhắc `sc_version`). Dùng thẳng thì 100% queue báo lỗi oan.
+// Ở đây chỉ cần chặn hậu tố: `bug_reports_dir` không được khớp `bug_reports_dirX`.
+const mentionsKey = (text, key) =>
+  new RegExp(`\\b${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![A-Za-z0-9_])`).test(text);
+
+for (const q of schema.queues || []) {
+  const producers = q.written_by || [];
+  const consumers = q.read_by || [];
+  const label = `hàng đợi \`${q.name}\``;
+
+  if (producers.length && !consumers.length) {
+    err('R1', `${label}: có producer nhưng KHÔNG ai đọc — file vào đó rồi nằm lại vĩnh viễn`,
+        `Đây là hình dạng của G26 (prd-change-requests: có producer, có storage, có commit,\n`
+      + `        có mặt trong /sync — nhưng 0 consumer, và không gì báo).`);
+  }
+  if (consumers.length && !producers.length) {
+    err('R1', `${label}: có consumer nhưng KHÔNG ai ghi vào — hàng đợi chết?`);
+  }
+  for (const actor of new Set([...producers, ...consumers])) {
+    const text = actorText[actor];
+    if (text === undefined) continue;
+    if (!mentionsKey(text, q.path_key)) {
+      err('R3', `${label}: schema khai \`${actor}\` đụng hàng đợi này nhưng ${schema.actors[actor]} KHÔNG nhắc \`${q.path_key}\``,
+          `Hoặc lệnh thiếu implement, hoặc schema khai sai.`);
+    }
+  }
+}
+
 // ── R4 — {paths.X} vs project-context.yaml ────────────────────────────────────
 const cfgPath = path.join(ROOT, schema.path_keys.config_file);
 if (!fs.existsSync(cfgPath)) {
@@ -202,9 +272,420 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
   }
 }
 
+// ── R7 — mỗi audit flag phải có counter trong summary ─────────────────────────
+// Vì sao tồn tại (G33): PRD_DRIFT / TECHDOC_DRIFT / FE_TECHDOC_DRIFT được TÍNH ở Step 4-5
+// và CÓ mảng chi tiết trong `issues`, nhưng KHÔNG có counter trong `summary`. Dashboard đọc
+// `summary` → ba cờ đó vô hình ở tầng tổng hợp. Bất đối xứng 7/10 còn tệ hơn thiếu cả 10:
+// người viết dashboard thấy có counter cho các cờ khác nên tưởng `summary` là đủ.
+//
+// CỐ Ý KHÔNG CÓ ESCAPE HATCH (không `allow_no_counter`). Một luật có cửa thoát dùng được
+// ngay là luật yếu — đó chính là cách G30 xảy ra (schema phủ 16/43 tag rồi dừng). Cờ nào
+// "chỉ để nhắc, chưa phải lỗi" (SEAM_PENDING/STUB_PENDING) thì counter của nó vẫn có giá
+// trị: PM đọc để xếp thứ tự gen UC. Thêm 2 dòng rẻ hơn nhiều so với một ngoại lệ vĩnh viễn.
+// SIẾT (G30 lô 8): bản đầu chỉ hỏi "tên counter có xuất hiện Ở ĐÂU ĐÓ trong file không".
+// Test G27 lộ ra lỗ: gỡ counter khỏi ĐÚNG hai chỗ luật đòi (Step 7 + `summary`) mà R7 vẫn PASS,
+// vì tên còn sót trong khối report terminal. Tức nó bắt được ca "quên hoàn toàn" (ca thật của
+// G33) nhưng KHÔNG bắt ca "có ở report mà quên ở summary" — mà đó CHÍNH LÀ ca làm dashboard mù.
+// Giờ kiểm từng khối riêng.
+{
+  const flagVocab = schema.vocabularies.audit_flags;
+  const vtName = 'validate-traces';
+  const vtText = actorText[vtName];
+  if (flagVocab && vtText !== undefined) {
+    /** Cắt lát văn bản giữa hai mốc; null nếu không tìm thấy mốc (đừng im lặng bỏ qua). */
+    const slice = (from, to) => {
+      const a = vtText.indexOf(from);
+      if (a < 0) return null;
+      const b = vtText.indexOf(to, a + from.length);
+      return vtText.slice(a, b < 0 ? undefined : b);
+    };
+    const zones = [
+      { label: 'Step 7 (aggregate)', text: slice('### Step 7 —', '### Step 7b') },
+      { label: '`summary` của trace-report.json', text: slice('"summary": {', '"prds"') },
+    ];
+
+    for (const z of zones) {
+      if (z.text === null) {
+        warn('R7', `Không định vị được khối "${z.label}" trong ${schema.actors[vtName]} — R7 bỏ qua khối này`,
+             'Mốc cắt đã đổi? Cập nhật `slice()` trong self-check.js, đừng để R7 mù trong im lặng.');
+      }
+    }
+
+    const missing = [];
+    for (const flag of flagVocab.values || []) {
+      const counter = `${flag.toLowerCase()}_count`;
+      const gone = zones.filter(z => z.text !== null && !mentions(z.text, counter));
+      if (gone.length) missing.push({ flag, counter, zones: gone.map(z => z.label) });
+    }
+    if (missing.length) {
+      err('R7', `${missing.length} audit flag thiếu counter trong ${schema.actors[vtName]}`,
+          missing.map(m => `${m.flag} → thiếu \`${m.counter}\` ở: ${m.zones.join(' + ')}`).join('\n        ')
+        + `\n        Counter PHẢI có ở CẢ HAI khối. Chỉ có ở report terminal là KHÔNG đủ —`
+        + `\n        dashboard đọc \`summary\`, nên cờ sẽ vô hình ở tầng tổng hợp (G33).`);
+    }
+  } else if (!flagVocab) {
+    warn('R7', 'Không tìm thấy vocabulary `audit_flags` — R7 không chạy được');
+  }
+}
+
+// ── R8 — lint-trace phải theo kịp schema ──────────────────────────────────────
+//
+// Vì sao (G38): R1–R7 canh CONTRACT — chúng đọc file lệnh và kiểm "lệnh có gọi đúng tên
+// cột không". Không rule nào mở một `.tsv` THẬT ra xem. bin/lint-trace.js làm việc đó,
+// nhưng nó chỉ canh được thứ nó BIẾT. Thêm cột 25 hay vocabulary mới vào schema mà quên
+// dạy nó → checker tụt lại sau contract, im lặng, và 6 tháng sau ta có G38 lần hai.
+// R8 là van đóng đường đó — cùng tinh thần R7: nợ không được phép tái sinh.
+{
+  const LINT_REL = 'bin/lint-trace.js';
+  const lintAbs  = path.join(ROOT, LINT_REL);
+
+  if (!fs.existsSync(lintAbs)) {
+    err('R8', `${LINT_REL} không tồn tại — không có gì kiểm DỮ LIỆU sổ trace`,
+        `Contract được canh bằng máy (R1–R7) nhưng sổ thật thì không. Đây chính là G38.`);
+  } else {
+    const lintText = fs.readFileSync(lintAbs, 'utf8');
+
+    // ── R8a — mọi vocabulary phải neo được vào một chỗ kiểm cụ thể ──
+    const BINDINGS = ['column', 'columns', 'aux_column', 'filename_segment'];
+    for (const [vocab, def] of Object.entries(schema.vocabularies)) {
+      if (vocab.startsWith('$') || !def || !def.values) continue;
+      const bound = BINDINGS.filter(b => def[b] !== undefined);
+      if (!bound.length && !def.$lint) {
+        err('R8', `vocabulary \`${vocab}\` không khai binding nào cho lint-trace`,
+            `Khai đúng một trong: ${BINDINGS.map(b => `\`${b}\``).join(' · ')} — hoặc \`$lint\` kèm LÝ DO\n`
+          + `        nếu nó cố ý ngoài phạm vi (như audit_flags: sống trong trace-report.json, R7 canh).\n`
+          + `        Không khai = ${lintText ? 'lint-trace' : 'checker'} không biết kiểm ở đâu, và enum đó chỉ là chữ trong schema.`);
+      }
+
+      // Cột được neo tới phải TỒN TẠI — neo vào một tên cột đã đổi/gõ sai thì lint
+      // im lặng bỏ qua cả vocabulary đó (hình dạng G1: consumer trỏ vào chỗ trống).
+      const colNames = new Set(schema.tsv_columns.map(c => c.name));
+      for (const c of (def.columns || (def.column ? [def.column] : []))) {
+        if (!colNames.has(c)) {
+          err('R8', `vocabulary \`${vocab}\` neo vào cột \`${c}\` — cột này KHÔNG có trong tsv_columns`,
+              `Cột đã đổi tên, hay gõ sai? Neo trỏ vào chỗ trống ⇒ lint bỏ qua enum này trong im lặng.`);
+        }
+      }
+      if (def.aux_column) {
+        const aux = (schema.aux_tables || []).find(t => t.name === def.aux_table);
+        if (!aux) {
+          err('R8', `vocabulary \`${vocab}\` khai \`aux_table: "${def.aux_table}"\` — không có bảng phụ nào tên đó`);
+        } else if (!aux.columns.includes(def.aux_column)) {
+          err('R8', `vocabulary \`${vocab}\` neo vào \`${def.aux_table}.${def.aux_column}\` — cột này không có trong bảng đó`,
+              `Cột hiện có: ${aux.columns.join(' · ')}`);
+        }
+      }
+
+      // ── R8b — kiểu binding đã khai thì lint-trace phải thực sự ĐỌC nó ──
+      for (const b of bound) {
+        if (!mentionsKey(lintText, b)) {
+          err('R8', `schema khai binding \`${b}\` (ở \`${vocab}\`) mà ${LINT_REL} KHÔNG đọc key đó`,
+              `Khai binding rồi mà checker không dùng = enum không được kiểm ở đâu cả.\n`
+            + `        Dạy lint-trace đọc \`${b}\`, hoặc đổi sang một binding nó đã hiểu.`);
+        }
+      }
+    }
+
+    // ── R8c — `n` phải là 1..N liền mạch, không trùng ──
+    //
+    // lint-trace dựng header bằng cách SORT theo `n` (thứ tự array KHÔNG phải thứ tự cột —
+    // ba entry cuối trong schema hiện là n:23, n:24, n:22). Nên `n` trùng hoặc hổng làm
+    // header dẫn xuất sai ⇒ lint đối chiếu sổ thật với một contract sai. Kiểm cơ học.
+    const ns = schema.tsv_columns.map(c => c.n);
+    const dupes = ns.filter((n, i) => ns.indexOf(n) !== i);
+    if (dupes.length) {
+      err('R8', `tsv_columns có \`n\` trùng: ${[...new Set(dupes)].join(', ')}`,
+          `\`n\` là thứ tự cột authoritative — lint-trace sort theo nó để dựng header.\n`
+        + `        Trùng ⇒ header dẫn xuất sai ⇒ lint đối chiếu sổ thật với contract sai.`);
+    }
+    const expected = Array.from({ length: schema.tsv_columns.length }, (_, i) => i + 1);
+    const missingN = expected.filter(n => !ns.includes(n));
+    if (missingN.length) {
+      err('R8', `tsv_columns hổng số thứ tự: thiếu n = ${missingN.join(', ')}`,
+          `${schema.tsv_columns.length} cột thì \`n\` phải là 1..${schema.tsv_columns.length} liền mạch.\n`
+        + `        Bỏ một cột thì đánh số lại, đừng để lỗ — lint dựng header theo \`n\`.`);
+    }
+
+    // ── R8d — bảng phụ cũng phải nằm trong phạm vi lint ──
+    for (const t of schema.aux_tables || []) {
+      if (!lintText.includes(t.name)) {
+        err('R8', `bảng phụ \`${t.name}\` không được ${LINT_REL} kiểm`,
+            `Nó là NGUỒN của SEAM_UNWIRED/STUB_UNRESOLVED (hai cờ 🔴 chặn PR).\n`
+          + `        Header lệch ở đây thì hai cờ đó mù — đúng lý do bảng này được đưa vào SoT ở G30.`);
+      }
+    }
+  }
+}
+
+// ── R9 — cổng chặn PR phải neo đúng vào report ────────────────────────────────
+//
+// Vì sao (G39): gate đọc `summary[counter]`. Counter bị đổi tên mà gate không biết →
+// `undefined > 0` là false → GATE PASS TRÊN CODE HỎNG, kèm dấu ✅. Đây là false-green
+// im lặng, đúng hình dạng G1 (consumer trỏ vào chỗ trống) nhưng hậu quả nặng hơn: một
+// PR hỏng được merge. gate-trace.js tự phòng bằng cách fail khi counter vắng mặt trong
+// REPORT; R9 canh đầu còn lại — schema có neo đúng vào thứ validate-traces THỰC SỰ ghi.
+{
+  const GATE_REL = 'bin/gate-trace.js';
+  const gateAbs  = path.join(ROOT, GATE_REL);
+  const gate     = schema.gate;
+
+  if (!gate) {
+    err('R9', 'schema thiếu khối `gate` — không khai được cờ nào chặn PR',
+        `README khai 4 cờ 🔴 "chặn PR". Không có khối này thì lời đó không có cơ chế nào (G39).`);
+  } else if (!fs.existsSync(gateAbs)) {
+    err('R9', `${GATE_REL} không tồn tại — cờ 🔴 không có gì chặn`,
+        `Khai blocking trong schema mà không có cổng đọc nó = vẫn honor-system.`);
+  } else {
+    const gateText = fs.readFileSync(gateAbs, 'utf8');
+    const vtName = 'validate-traces';
+    const vtText = actorText[vtName];
+
+    const slice = (from, to) => {
+      if (vtText === undefined) return null;
+      const a = vtText.indexOf(from);
+      if (a < 0) return null;
+      const b = vtText.indexOf(to, a + from.length);
+      return vtText.slice(a, b < 0 ? undefined : b);
+    };
+    const summaryZone = slice('"summary": {', '"prds"');
+    const issuesZone  = slice('"issues": {', '"prds"');
+
+    if (summaryZone === null || issuesZone === null) {
+      warn('R9', `Không định vị được khối \`summary\`/\`issues\` trong ${schema.actors[vtName]} — R9 bỏ qua`,
+           'Mốc cắt đã đổi? Cập nhật `slice()` trong self-check.js, đừng để R9 mù trong im lặng.');
+    } else {
+      // (a) counter + issues_key phải CÓ THẬT trong report mà validate-traces sinh ra
+      for (const b of gate.blocking || []) {
+        if (!mentionsKey(summaryZone, b.counter)) {
+          err('R9', `\`gate.blocking\` chờ counter \`${b.counter}\` mà khối \`summary\` của ${schema.actors[vtName]} KHÔNG có`,
+              `Gate đọc summary[${b.counter}]. Không có ⇒ gate MÙ với cờ này.\n`
+            + `        Hoặc counter đã đổi tên (sửa schema), hoặc validate-traces thiếu ghi nó.`);
+        }
+        if (!mentionsKey(issuesZone, b.issues_key)) {
+          err('R9', `\`gate.blocking\` chờ \`issues.${b.issues_key}\` mà khối \`issues\` KHÔNG có`,
+              `Không có ⇒ gate chặn được nhưng KHÔNG nêu được thủ phạm — người đọc CI thấy\n`
+            + `        một con số và không biết sửa gì. Cờ chặn phải kèm đường ra.`);
+        }
+      }
+
+      // (b) mốc đối chiếu độ tươi cũng phải tồn tại — thiếu thì G2 mất tác dụng và gate
+      //     quay về đọc một file có thể cũ, tức trở lại đúng thứ G39 định bịt.
+      for (const key of [...Object.keys((gate.reconcile || {}).hard || {}),
+                         ...Object.keys((gate.reconcile || {}).soft || {})]) {
+        if (!mentionsKey(summaryZone, key)) {
+          err('R9', `\`gate.reconcile\` dùng \`summary.${key}\` — khối \`summary\` không có key này`,
+              `Thiếu mốc đối chiếu ⇒ gate không phát hiện được report cũ.`);
+        }
+      }
+
+      // (c) soft map trỏ vào giá trị status có thật
+      const statusVals = (schema.vocabularies.trace_status || {}).values || [];
+      for (const [key, val] of Object.entries((gate.reconcile || {}).soft || {})) {
+        if (!statusVals.includes(val)) {
+          err('R9', `\`gate.reconcile.soft.${key}\` trỏ tới status "${val}" — không thuộc vocabulary \`trace_status\``,
+              `Giá trị cho phép: ${statusVals.join(' | ')}`);
+        }
+      }
+
+      // (f) per_sc (G48) — mọi field dùng làm khoá/so sánh phải CÓ THẬT trong khối
+      //     `scenarios[]` mà validate-traces sinh ra. Neo vào field không tồn tại thì
+      //     gate im lặng rơi về so tổng số — tức G48 quay lại y nguyên mà dấu vẫn ✅.
+      const perSc = (gate.reconcile || {}).per_sc;
+      if (perSc) {
+        const scZone = slice('"scenarios": [', '"issues"');
+        if (scZone === null) {
+          warn('R9', `Không định vị được khối \`scenarios[]\` trong ${schema.actors[vtName]} — R9(f) bỏ qua`,
+               'Mốc cắt đã đổi? Cập nhật `slice()`, đừng để R9 mù trong im lặng.');
+        } else {
+          const needed = [...(perSc.key_fields || []), perSc.compare, perSc.orphaned_flag]
+            .filter(Boolean);
+          for (const f of needed) {
+            if (!mentionsKey(scZone, f)) {
+              err('R9', `\`gate.reconcile.per_sc\` dùng field \`${f}\` mà khối \`scenarios[]\` KHÔNG có`,
+                  `Gate sẽ im lặng rơi về so tổng số ⇒ mất chính thứ G48 vừa thêm,\n`
+                + `        mà report vẫn hiện ✅. Thêm field vào Step 8, hoặc sửa schema.`);
+            }
+          }
+          if (perSc.orphaned_status && !statusVals.includes(perSc.orphaned_status)) {
+            err('R9', `\`per_sc.orphaned_status\` = "${perSc.orphaned_status}" không thuộc \`trace_status\``,
+                `Giá trị cho phép: ${statusVals.join(' | ')}`);
+          }
+          // Khoá KHÔNG có platform = quay lại đúng ca G48 (sc_id nhập nhằng giữa platform).
+          if (!(perSc.key_fields || []).includes('platform')) {
+            err('R9', '`per_sc.key_fields` thiếu `platform` — sc_id một mình không định danh được scenario',
+                `validate-traces Step 2: "sc_id trùng số giữa các platform là 2 scenario khác nhau".\n`
+              + `        Khoá thiếu platform ⇒ web và app đè nhau khi đối chiếu (G48).`);
+          }
+        }
+      }
+    }
+
+    // (g) config_preconditions (tầng G0) — rule được NÂNG thành chặn phải TỒN TẠI THẬT
+    //     trong lint-trace.js. Neo vào một rule id không có ⇒ `warns.filter(...)` không
+    //     khớp gì ⇒ G0 luôn xanh ⇒ cổng mù, im lặng. Cùng hình dạng false-green của R9(a).
+    const precond = (gate.config_preconditions || {}).promote_lint_rules || [];
+    if (precond.length) {
+      const lintRuleIds = new Set(
+        (fs.readFileSync(gateAbs.replace(/gate-trace\.js$/, 'lint-trace.js'), 'utf8')
+          .match(/\b(?:err|warn)\('(T\d+)'/g) || []).map(m => /T\d+/.exec(m)[0]));
+      for (const p of precond) {
+        if (!lintRuleIds.has(p.rule)) {
+          err('R9', `\`gate.config_preconditions\` nâng rule \`${p.rule}\` mà bin/lint-trace.js KHÔNG phát ra rule đó`,
+              `Rule id đổi tên? Gate filter theo id, không khớp ⇒ G0 LUÔN XANH ⇒ cổng mù.\n`
+            + `        Rule lint hiện có: ${[...lintRuleIds].sort().join(' · ')}`);
+        }
+        if (!p.why) {
+          err('R9', `\`config_preconditions\` rule \`${p.rule}\` thiếu \`why\``,
+              `Cổng chặn phải nói được VÌ SAO nó chặn — không thì người bị chặn chỉ thấy một id.`);
+        }
+      }
+      if (!mentionsKey(gateText, 'config_preconditions')) {
+        err('R9', `schema khai \`gate.config_preconditions\` mà ${GATE_REL} KHÔNG đọc nó`,
+            'Khai trong schema rồi hard-code lại trong code = hai nguồn-sự-thật, và chúng sẽ lệch.');
+      }
+    }
+
+    // (d) gate-trace.js phải thực sự ĐỌC khối gate, không hard-code danh sách cờ
+    for (const key of ['blocking', 'reconcile', 'report_path']) {
+      if (!mentionsKey(gateText, key)) {
+        err('R9', `schema khai \`gate.${key}\` mà ${GATE_REL} KHÔNG đọc nó`,
+            `Khai trong schema rồi hard-code lại trong code = hai nguồn-sự-thật, và chúng sẽ lệch.`);
+      }
+    }
+
+    // (e) cờ 🟠 không được lọt vào danh sách chặn — chặn PR vì NỢ là cách làm cổng bị tắt
+    const blockingFlags = new Set((gate.blocking || [])
+      .map(b => b.counter.replace(/_count$/, '').toUpperCase()));
+    for (const f of blockingFlags) {
+      if (/_DRIFT$|_STALE_REF$|_PENDING$|_STALE_VS_/.test(f)) {
+        err('R9', `\`${f}\` nằm trong \`gate.blocking\` nhưng nó là cờ NỢ (🟠), không phải code hỏng (🔴)`,
+            `README §Traceability: 🟠 = "code chưa theo kịp spec", cố ý KHÔNG chặn.\n`
+          + `        Chặn PR vì nợ ⇒ cổng đỏ liên tục ⇒ người ta tắt cổng ⇒ mất cả 🔴.`);
+      }
+    }
+  }
+}
+
+// ── R10 — file CI phải theo kịp danh sách tag làm audit hết tươi ──────────────
+//
+// Vì sao (nợ #4 sau Wave 1): job `require-fresh-audit` grep 7 tag trong diff để biết
+// "PR có đổi thứ report đang khẳng định không". Danh sách đó nằm HAI chỗ: schema (nguồn)
+// và file YAML (nơi grep thật chạy). Tag đổi tên mà YAML không biết ⇒ grep không khớp gì
+// ⇒ job LUÔN XANH ⇒ cổng mù trong im lặng. Đúng hình dạng false-green của R9(a)/R9(g),
+// chỉ ở một file khác loại.
+//
+// Không gộp một nguồn được: YAML chạy trong CI, không đọc JSON lúc runtime mà không thêm
+// một lệnh CLI chỉ để phục vụ nó. Nên chấp nhận hai chỗ, và canh chúng khớp bằng máy.
+{
+  const inv = (schema.gate || {}).audit_invalidating_tags;
+  if (inv) {
+    const rel = inv.ci_template;
+    if (!rel) {
+      err('R10', '`gate.audit_invalidating_tags` thiếu `ci_template` — không biết canh file nào');
+    } else {
+      const abs = path.join(ROOT, rel);
+      if (!fs.existsSync(abs)) {
+        err('R10', `\`audit_invalidating_tags.ci_template\` trỏ tới ${rel} — file không tồn tại`,
+            'Template đổi tên/bị xoá? Không có nó thì lỗ "sửa code mà không audit lại" hở lại.');
+      } else {
+        const yml = fs.readFileSync(abs, 'utf8');
+        const declared = (inv.tags || []).map(t => t.tag);
+        if (!declared.length) {
+          err('R10', '`audit_invalidating_tags.tags` rỗng — job sẽ không grep gì và LUÔN XANH');
+        }
+        // YAML viết tag trong một alternation regex (`implements|verifies|…`), nên so theo
+        // phần sau `@trace.` thay vì so nguyên chuỗi có dấu chấm.
+        for (const full of declared) {
+          const bare = full.replace(/^@trace\./, '');
+          if (!new RegExp(`\\b${bare}\\b`).test(yml)) {
+            err('R10', `${rel} KHÔNG nhắc tag \`${full}\``,
+                `Job grep theo danh sách này. Thiếu một tag ⇒ đổi tag đó không bị đòi audit lại,\n`
+              + `        và không gì báo. Tag phải canh: ${declared.join(' · ')}`);
+          }
+        }
+        // Ngược lại: cờ mà tag khai là nguồn phải có thật trong vocabulary audit_flags,
+        // else danh sách này đang neo vào một cờ không tồn tại.
+        const flagVals = new Set(((schema.vocabularies.audit_flags || {}).values) || []);
+        const statusVals2 = new Set(((schema.vocabularies.trace_status || {}).values) || []);
+        for (const t of inv.tags || []) {
+          for (const f of t.flags || []) {
+            if (!flagVals.has(f) && !statusVals2.has(f)) {
+              err('R10', `tag \`${t.tag}\` khai sinh ra cờ \`${f}\` — cờ này không có trong vocabulary`,
+                  `audit_flags: ${[...flagVals].join(' · ')}\n        trace_status: ${[...statusVals2].join(' · ')}`);
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+// ── R11 — mức chặn CHECKPOINT phải được KHAI, không để agent tự suy ──────────
+//
+// Vì sao: G41 viết ba mức vào gate.md Bước 3a nhưng không lệnh nào tự khai mình thuộc
+// mức nào ⇒ agent tự suy mỗi lần đọc. Suy sai một lần theo hướng nhẹ hơn thì `--yes` bỏ
+// qua được một cổng đáng ra KHÔNG BAO GIỜ được bỏ.
+//
+// Đây là hình dạng đã gặp bốn lần: luật ĐÚNG, viết RÕ, KHÔNG AI CANH — G1, G28, G41, và
+// cái này. Ba lần trước đều chữa bằng "khai tường minh + để máy canh". R11 là phần sau.
+{
+  const CL = (schema.gate || {}).checkpoint_levels;
+  if (CL) {
+    const marker = CL.label_marker || 'Checkpoint:';
+    const check = (list, levelWord, label) => {
+      for (const e of list || []) {
+        const rel = `commands/${e.cmd}.tmpl`;
+        const abs = path.join(ROOT, rel);
+        if (!fs.existsSync(abs)) {
+          err('R11', `\`checkpoint_levels.${label}\` khai lệnh \`${e.cmd}\` — ${rel} không tồn tại`,
+              'Lệnh bị đổi tên/bỏ? Khai một lệnh không có nghĩa là mức chặn đó không áp cho ai.');
+          continue;
+        }
+        const text = fs.readFileSync(abs, 'utf8');
+        if (!text.includes(marker)) {
+          err('R11', `${rel} thiếu dòng khai mức checkpoint (\`${marker}\`)`,
+              `Schema xếp nó vào \`${label}\`. Không khai trong file thì agent phải TỰ SUY từ\n`
+            + `        bảng ở gate Bước 3a — và suy sai theo hướng nhẹ hơn thì --yes bỏ qua được\n`
+            + `        một cổng đáng ra không bao giờ được bỏ.`);
+          continue;
+        }
+        if (!new RegExp(levelWord).test(text)) {
+          err('R11', `${rel} khai mức checkpoint KHÁC với schema (schema: \`${label}\`)`,
+              `File phải nói "${levelWord.replace(/\\/g, '')}". Hai nguồn nói khác nhau thì\n`
+            + `        agent theo cái nào là tuỳ lúc — đúng hình dạng mâu thuẫn G41 vừa vá.`);
+        }
+        if (!e.why) {
+          err('R11', `\`checkpoint_levels.${label}\` mục \`${e.cmd}\` thiếu \`why\``,
+              'Một mức chặn không nói được VÌ SAO sẽ bị người sau coi là tuỳ ý và gỡ đi.');
+        }
+      }
+    };
+    check(CL.hard, 'chặn CỨNG', 'hard');
+    check(CL.none, 'không chặn', 'none');
+
+    // Một lệnh không được vừa `hard` vừa `none`.
+    const hardSet = new Set((CL.hard || []).map(e => e.cmd));
+    for (const e of CL.none || []) {
+      if (hardSet.has(e.cmd)) {
+        err('R11', `lệnh \`${e.cmd}\` khai ở CẢ \`hard\` LẪN \`none\``,
+            'Mâu thuẫn trực tiếp — chọn một.');
+      }
+    }
+    // Mức `normal` cố ý KHÔNG liệt kê (nó là mặc định). Nếu ai thêm khoá đó vào schema,
+    // báo ngay: một danh sách phải bảo trì mãi là chỗ nợ sẽ tích lại.
+    if (CL.normal) {
+      err('R11', '`checkpoint_levels.normal` không nên tồn tại',
+          '`normal` là MẶC ĐỊNH. Liệt kê nó ra tạo một danh sách phải bảo trì mãi — thêm lệnh\n'
+        + '        mới mà quên thêm vào đó là sai lần nữa. Chỉ khai `hard` và `none`.');
+    }
+  }
+}
+
 // ── report ────────────────────────────────────────────────────────────────────
 const tagCount = schema.tags.length;
 const colCount = schema.tsv_columns.length;
+const auxCount = (schema.aux_tables || []).length;
+const queueCount = (schema.queues || []).length;
 console.log('');
 console.log('Self-check (bin/trace-schema.json) ...');
 console.log('');
@@ -219,7 +700,19 @@ 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`);
+  // Đếm bằng cách LOẠI key `$…` (metadata/comment), không phải `- 1`: schema có nhiều hơn
+  // một key `$` kể từ khi thêm `$lint_binding_comment`, nên hằng số cũ sẽ đếm lố.
+  const vocabCount = Object.keys(schema.vocabularies).filter(k => !k.startsWith('$')).length;
+  console.log(`  ✅ ${tagCount} tag + ${colCount} cột TSV + ${auxCount} bảng phụ + ${queueCount} hàng đợi + ${vocabCount} vocabulary — contract khớp mọi lệnh`);
+  // ĐẾM rule từ chính lint-trace.js, không hard-code: một con số phát biểu ở hai chỗ rồi
+  // lệch nhau là đúng lớp lỗi G23 được dựng lên để chặn. Đếm id `Tn` mà nó thực sự phát ra.
+  let lintRules = '?';
+  try {
+    const txt = fs.readFileSync(path.join(ROOT, 'bin/lint-trace.js'), 'utf8');
+    lintRules = new Set((txt.match(/\b(?:err|warn)\('(T\d+)'/g) || [])
+      .map(m => /T\d+/.exec(m)[0])).size;
+  } catch {}
+  console.log(`     + sổ trace thật được canh bởi bin/lint-trace.js (${lintRules} rule) — R8 giữ nó theo kịp schema`);
 }
 console.log('');