@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/bin/self-check.js

@@ -8,7 +8,8 @@
  * 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.
  *
- * 7 rule — áp cho tags · tsv_columns · aux_tables (_seams.tsv) · queues (feedback/*):
+ * 12 rule — áp cho tags · tsv_columns · aux_tables (_seams.tsv) · queues (feedback/*),
+ * cộng gate · CI template · lint-trace · dòng changelog:
  *   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
@@ -20,6 +21,33 @@
  *       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
+ *   R9  cổng chặn PR neo vào counter/issues_key không
+ *       tồn tại trong report, hoặc cờ 🟠 lọt vào
+ *       gate.blocking                                    → ERROR  (bắt được G39)
+ *   R10 templates/ci/trace-gate.yml tụt lại sau danh
+ *       sách audit_invalidating_tags ⇒ job LUÔN XANH      → ERROR  (nợ #4 sau Wave 1)
+ *   R11 lệnh không tự khai mức chặn CHECKPOINT, hoặc
+ *       nhãn trong file lệch schema                       → ERROR  (nợ sau G41)
+ *   R12 dòng changelog — producer không có DÒNG TEMPLATE
+ *       mang {changelog_scope}, hoặc consumer không hiểu
+ *       [no-behavior] / phép phân giải BR/AC → UC sở hữu  → ERROR  (bắt được G52, G53, G58)
+ *
+ * R12 CỐ Ý là USE-check, không phải mention-check: nó đòi token nằm trên ĐÚNG dòng template
+ * (row 3-placeholder, ngoài blockquote), không chỉ "có xuất hiện đâu đó trong file". Vì
+ * `text.includes()` bị thoả mãn bởi một lần nhắc bất kỳ — kể cả trong phần giải thích — nên
+ * gỡ token khỏi đúng dòng format mà vẫn nhắc ở chỗ khác thì checker im lặng và G52 quay lại
+ * nguyên vẹn. Đây là điểm yếu đã biết của R3, không lặp lại. Ví dụ đã ĐIỀN CỤ THỂ
+ * (`| 1.4 | 2026-08-19 | UC5: … |`) không bị canh — nếu canh thì không ai dám viết ví dụ.
+ *
+ * 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/
@@ -100,6 +128,26 @@ function mentions(text, name) {
   return new RegExp(`${before}${esc}(?![A-Za-z0-9_])`).test(text);
 }
 
+/**
+ * `name` có xuất hiện trong PHẦN CODE THẬT của một file .js không — bỏ dòng comment.
+ *
+ * Vì sao cần (bài học lặp BỐN lần trong loạt G52–G57): một chú thích *giải thích* luật cũng
+ * chứa đúng tên/biểu thức mà rule đang tìm. Nên `text.includes("scope.kind")` vẫn ✅ sau khi
+ * ai đó thay điều kiện thật bằng `false` — chú thích "Nên: scope.kind !== all ⇒ FAIL" thoả mãn
+ * phép kiểm, và cổng chết trong im lặng.
+ *
+ * Cùng lớp với điểm yếu của R3 (`mentions()` không phân biệt "đọc" với "nhắc tên") — chỉ ở một
+ * trục khác: không phân biệt "code" với "chú thích VỀ code". R12/R13/R14/R9(h) đều đã phải
+ * chuyển sang use-check vì nó; helper này để lần sau không phải phát minh lại.
+ *
+ * Cố ý ĐƠN GIẢN: chỉ bỏ dòng bắt đầu bằng `//`. Không parse JS. Comment cuối dòng sau code
+ * thật vẫn được giữ — đúng ý, vì dòng đó CÓ code.
+ */
+const codeOf = text => text.split('\n').filter(l => !/^\s*\/\//.test(l)).join('\n');
+function mentionsInCode(text, name) {
+  return codeOf(text).includes(name);
+}
+
 // ── R1 + R2 + R3 — producer / consumer / prose khớp ───────────────────────────
 function checkField(kind, name, def) {
   const producers = [...(def.written_by || []), ...(def.bumped_by || [])];
@@ -318,6 +366,748 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
   }
 }
 
+// ── 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"');
+    // `"issues"` nằm SAU `"prds"` trong file, nên mốc kết thúc `"prds"` không tồn tại phía sau
+    // ⇒ slice() rơi về "tới hết file" và zone phình 4.6× (25790 ký tự thay vì 5625). Hệ quả:
+    // R9(a) sẽ PASS khi `issues_key` chỉ xuất hiện ở khối report terminal chứ không có trong
+    // `issues[]` — đúng lớp lỗi R7 đã phải siết ở G30 lô 8 ("tên xuất hiện Ở ĐÂU ĐÓ trong file").
+    // Dùng dấu đóng của chính object `issues` (2 space + `}`) làm mốc.
+    const issuesZone  = slice('"issues": {', '\n  }');
+
+    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(' | ')}`);
+        }
+      }
+
+      // (h) KEY Ở CẤP GỐC BIÊN BẢN — cả hai đầu, không đầu nào được lửng (G57).
+      //
+      // Vì sao cần: `report.domain` từng có 1 consumer (gate-trace CHẶN PR nếu nó khác 'all')
+      // và 0 producer — validate-traces không có cờ nào đặt nó, nên ô đó LUÔN 'all' và phần
+      // kiểm của gate chưa bao giờ chạy. Đúng hình dạng R1 fail build vì nó; sống được vì
+      // R1/R2 chỉ canh field trong SỔ TSV + tag trong CODE, không canh key cấp gốc BIÊN BẢN.
+      // Cùng điểm mù R13 vừa bịt cho `spec_baseline`, chỉ ở một key khác.
+      {
+        const RRK = gate.report_root_keys;
+        if (RRK) {
+          for (const k of RRK.keys || []) {
+            // Đầu PRODUCER: phải là một KEY THẬT trong skeleton JSON, không chỉ được nhắc tên.
+            // Dạng `"key":` chỉ xuất hiện ở skeleton — prose nhắc tên dùng backtick.
+            if (!vtText.includes(`"${k.key}":`)) {
+              err('R9', `\`report_root_keys\` khai \`${k.key}\` mà ${schema.actors[vtName]} không ghi nó`,
+                  `${k.read_by} ĐỌC \`report.${k.key}\` và phán theo nó. Không ai ghi ⇒ giá trị luôn\n`
+                + `        là mặc định ⇒ phần kiểm đó KHÔNG BAO GIỜ chạy, mà dấu ✅ vẫn đầy đủ.`);
+            }
+            // Đầu CONSUMER: phải thực sự đọc `report.{key}`, không phải chỉ có chữ đó ở đâu đó.
+            // Escape PHẢI double trong template literal: `\s` là "s" và `\b` là ký tự backspace.
+            // mentionsInCode: đầu consumer phải là CODE THẬT. Chú thích của khối này cũng nhắc
+            // `report.domain` (nó kể lại chính ca G57), nên một phép kiểm trên toàn văn sẽ được
+            // chú thích thoả mãn ngay cả khi gate đã thôi đọc field đó.
+            if (!mentionsInCode(gateText, `report.${k.key}`)) {
+              err('R9', `\`report_root_keys\` khai \`${k.read_by}\` đọc \`${k.key}\` mà ${GATE_REL} không đọc`,
+                  'Producer ghi một key mà consumer không đọc = field chết ở phía biên bản (R2 lộn\n'
+                + '        ngược). Hoặc consumer đã bỏ, hoặc key đổi tên — sửa schema cho khớp.');
+            }
+            if (!k.why) {
+              err('R9', `\`report_root_keys\` mục \`${k.key}\` thiếu \`why\``,
+                  'Một key ở cấp gốc biên bản không nói được vì sao tồn tại sẽ bị dọn đi.');
+            }
+          }
+          // Luật gate cho scope phải TUYỆT ĐỐI. `if (others.length)` là đúng ca false-green:
+          // repo MỘT domain ⇒ others rỗng ⇒ biên bản phiến diện được nhận là toàn bộ.
+          const SK = RRK.scope_kinds;
+          if (SK) {
+            if (!(SK.values || []).includes('all')) {
+              err('R9', '`scope_kinds.values` thiếu `all` — không có giá trị nào nghĩa là "toàn bộ"');
+            }
+            for (const v of SK.values || []) {
+              if (!vtText.includes(v)) {
+                err('R9', `\`scope_kinds\` khai giá trị \`${v}\` mà ${schema.actors[vtName]} không nhắc`,
+                    'Giá trị scope khai mà lệnh không biết ⇒ không bao giờ ghi ra được.');
+              }
+            }
+            for (const f of SK.flags || []) {
+              // mentions(): khớp ranh giới token. `--prdXX` CHỨA `--prd`, nên includes() trần
+              // vẫn ✅ sau khi ai đó đổi tên cờ và scoping đã chết.
+              if (!mentions(vtText, f.flag)) {
+                err('R9', `\`scope_kinds.flags\` khai \`${f.flag}\` mà ${schema.actors[vtName]} không parse`,
+                    'Đây chính là G57: biên bản có ô "phạm vi", gate biết đọc ô đó, mà lệnh KHÔNG có\n'
+                  + '        cờ nào để đặt nó. Sợi dây đấu một đầu, đầu kia bỏ lửng.');
+              }
+            }
+            // Neo vào PHÉP SO SÁNH, không phải truy cập thuộc tính: `scope.kind` còn xuất
+            // hiện ở chỗ dựng thông điệp (`${scope.kind}="…"`), nên kiểm tên thuộc tính vẫn ✅
+            // sau khi ai đó thay `if (scope.kind !== 'all')` bằng `if (false)`. Chuẩn hoá bỏ
+            // khoảng trắng để bền với format (`!==` giữ nguyên; ' hay " đều nhận).
+            const norm = codeOf(gateText).replace(/\s+/g, '');
+            if (!/scope\.kind!==['"]all['"]/.test(norm)) {
+              err('R9', `${GATE_REL} không kiểm \`scope.kind\``,
+                  'Thêm cờ scope mà không siết G2 là biến cổng thành SÂN KHẤU — đúng cái G39 dựng\n'
+                + '        lên để chống. Điều kiện phải TUYỆT ĐỐI: scope.kind !== "all" ⇒ FAIL, không\n'
+                + '        phụ thuộc trên đĩa có bao nhiêu domain (repo một domain ⇒ others rỗng ⇒\n'
+                + '        biên bản phiến diện lọt qua).');
+            }
+          }
+        }
+      }
+      // (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) {
+      // `_UNROUTED$` cũng thuộc nhóm nợ (G51): "chưa ai quyết repo" là trạng thái HỢP LỆ ở
+      // feature đầu tiên của một domain mới, không phải code hỏng. Chặn PR vì nó sẽ đỏ liên tục
+      // trên mọi feature mới ⇒ cổng bị tắt ⇒ mất cả 4 cờ 🔴 thật.
+      if (/_DRIFT$|_STALE_REF$|_PENDING$|_STALE_VS_|_UNROUTED$/.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`.');
+    }
+  }
+}
+
+// ── R12 — dòng changelog: producer phải khai scope, consumer phải HIỂU ────────
+//
+// Vì sao: dòng changelog là contract máy đọc (validate-traces Step 4/5 phân loại 🟠 vs ⓘ
+// dựa vào nó), nhưng trước G52/G53/G58 nó là contract DUY NHẤT có consumer được canh
+// (R1–R11 canh tên cột/field) mà KHÔNG producer nào được canh. Bốn producer, ba hình dạng,
+// hỏng theo cả hai hướng: /review-context --fix ghi 0 scope ⇒ 🟠 cho MỌI UC (ồn tới mức
+// cờ mất giá trị); /extend-prd ghi `sửa BR8` không nêu UC ⇒ UC đổi thật thành ⓘ và
+// `--realign-prd-version` dán nhãn lại (im lặng).
+//
+// R12 là phần "máy canh" — cùng khuôn R11: khai tường minh + để máy canh.
+// Điểm quan trọng nhất là R12d: một marker được GHI mà consumer không HIỂU thì TỆ HƠN
+// không có marker — nó bị đọc như văn xuôi và lọt im lặng, đúng hình dạng G1.
+{
+  const C = schema.changelog_row_contract;
+  if (C) {
+    const tok = C.scope_token;
+    if (!tok) {
+      err('R12', '`changelog_row_contract` thiếu `scope_token` — R12 không có gì để neo',
+          'Không có token thì "producer có khai scope không" là câu hỏi không kiểm được bằng máy.');
+    }
+    const readActor = (cmd, rule, label) => {
+      const rel = `commands/${cmd}.tmpl`;
+      const abs = path.join(ROOT, rel);
+      if (!fs.existsSync(abs)) {
+        err(rule, `\`changelog_row_contract.${label}\` khai lệnh \`${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à contract đó không áp cho ai.');
+        return null;
+      }
+      return { rel, text: fs.readFileSync(abs, 'utf8') };
+    };
+
+    // R12a/R12b — mỗi producer phải nhắc scope_token trong format nó ghi.
+    for (const p of C.producers || []) {
+      const f = readActor(p.cmd, 'R12', 'producers');
+      if (!f) continue;
+      // Canh DÒNG TEMPLATE THẬT, không phải "có nhắc token ở đâu đó trong file".
+      //
+      // Vì sao phân biệt: `text.includes(tok)` bị thoả mãn bởi MỘT lần nhắc bất kỳ — kể cả
+      // trong phần giải thích. Nên gỡ token khỏi ĐÚNG dòng format mà vẫn còn nhắc ở chỗ khác
+      // thì checker im lặng, và G52 quay lại nguyên vẹn. Đây đúng là điểm yếu của R3
+      // (`mentions()` không phân biệt "đọc" với "nhắc tên") — không lặp lại nó ở R12.
+      //
+      // "Dòng template changelog" = row markdown có PLACEHOLDER ở CẢ BA ô (version · ngày ·
+      // mô tả). Ví dụ đã điền cụ thể (`| 1.4 | 2026-08-19 | UC5: … |`) KHÔNG khớp — cố ý:
+      // chúng minh hoạ output, không phải khuôn để ghi. Blockquote `>` cũng bị loại — khối
+      // "vì sao đổi" được phép trích nguyên dòng cũ (cùng cách test rules/workflow.md làm).
+      const ROW_TEMPLATE = /\|[^|]*\{[^}]*\}[^|]*\|[^|]*\{[^}]*\}[^|]*\|[^|]*\{[^}]*\}[^|]*\|/;
+      const rows = f.text.split('\n')
+        .filter(l => !/^\s*>/.test(l))
+        .filter(l => ROW_TEMPLATE.test(l));
+      if (!rows.length) {
+        err('R12', `${f.rel} là producer dòng changelog nhưng không có DÒNG TEMPLATE nào`,
+            'Không có khuôn `| {version} | {ngày} | {mô tả} |` thì agent tự nghĩ ra format, và\n'
+          + '        mỗi lệnh nghĩ một kiểu — đúng trạng thái trước G52/G53/G58.');
+      }
+      for (const r of rows.filter(l => tok && !l.includes(tok))) {
+        err('R12', `${f.rel} có dòng template changelog KHÔNG chứa \`${tok}\``,
+            `Dòng: ${r.trim().slice(0, 90)}\n`
+          + '        Format phải có chỗ cho scope. Thiếu ⇒ row mơ hồ ⇒ consumer gắn 🟠 cho MỌI UC\n'
+          + '        (G52), hoặc nêu BR mà không nêu UC sở hữu ⇒ UC đổi thật thành ⓘ (G53).\n'
+          + '        Muốn minh hoạ output? Điền GIÁ TRỊ CỤ THỂ (`| 1.4 | 2026-08-19 | UC5: … |`)\n'
+          + '        — dòng đã điền không bị canh, dòng còn placeholder thì bị.');
+      }
+      if (!p.scope_source) {
+        err('R12', `\`changelog_row_contract.producers\` mục \`${p.cmd}\` thiếu \`scope_source\``,
+            'Không nói được scope LẤY TỪ ĐÂU thì người sửa sau sẽ ghi bừa cho đủ token.');
+      }
+      // R12c — producer nào khai tự phát marker trung tính thì phải nhắc nó.
+      if (p.emits_neutral_marker && C.neutral_marker && !f.text.includes(C.neutral_marker)) {
+        err('R12', `${f.rel} khai \`emits_neutral_marker\` nhưng KHÔNG nhắc \`${C.neutral_marker}\``,
+            'Khai tự phát một marker mà file không nói bao giờ phát ⇒ không bao giờ phát.');
+      }
+    }
+
+    // R12d — consumer phải hiểu ĐỦ: token + marker + phép phân giải BR/AC → UC.
+    for (const c of C.consumers || []) {
+      const f = readActor(c.cmd, 'R12', 'consumers');
+      if (!f) continue;
+      if (tok && !f.text.includes(tok)) {
+        err('R12', `${f.rel} là consumer dòng changelog nhưng KHÔNG nhắc \`${tok}\``,
+            'Consumer không biết token thì không parse được thứ producer vừa ghi.');
+      }
+      if (C.neutral_marker && !f.text.includes(C.neutral_marker)) {
+        err('R12', `${f.rel} KHÔNG nhắc \`${C.neutral_marker}\` — marker được GHI mà không ai HIỂU`,
+            'Đây là ca TỆ HƠN không có marker: producer ghi nó, consumer đọc như văn xuôi rồi\n'
+          + '        bỏ qua ⇒ hoặc mất tác dụng lọc, hoặc bị coi là mơ hồ. Hỏng im lặng (G1).');
+      }
+      const rq = C.resolve_to_uc || {};
+      if (rq.required && rq.anchor && !f.text.includes(rq.anchor)) {
+        err('R12', `${f.rel} KHÔNG nhắc phép phân giải \`${rq.anchor}\``,
+            'Thiếu bước này thì phép thử "UC này có trong tập?" luôn FALSE cho một row chỉ nêu\n'
+          + '        BR/AC ⇒ UC đổi thật bị xếp ⓘ và --realign dán nhãn lại. Đó là G53.');
+      }
+    }
+
+    // R12e — một check không được vừa trung tính vừa không trung tính.
+    const neu = new Set((C.neutral_checks || []).map(e => e.check));
+    for (const e of C.not_neutral_checks || []) {
+      if (neu.has(e.check)) {
+        err('R12', `check \`${e.check}\` khai ở CẢ \`neutral_checks\` LẪN \`not_neutral_checks\``,
+            'Mâu thuẫn trực tiếp — chọn một. Trung tính là lời khẳng định CHỨNG MINH ĐƯỢC.');
+      }
+    }
+    for (const e of [...(C.neutral_checks || []), ...(C.not_neutral_checks || [])]) {
+      if (!e.why) {
+        err('R12', `check \`${e.check}\` thiếu \`why\``,
+            'Xếp hạng trung tính mà không nói lý do sẽ bị người sau coi là tuỳ ý và đổi đi.');
+      }
+    }
+    // Có marker mà không có danh sách trung tính = marker dùng theo cảm tính.
+    if (C.neutral_marker && !(C.neutral_checks || []).length) {
+      err('R12', '`neutral_marker` được khai nhưng `neutral_checks` rỗng',
+          'Không liệt kê check nào ĐƯỢC PHÉP mang marker thì nó thành cửa sau: mọi thay đổi\n'
+        + '        đều tự khai "không đổi hành vi" và bộ lọc mất luôn tác dụng.');
+    }
+  }
+}
+
+// ── R13 — phát hiện sửa spec ngoài đường: nửa GHI MỐC phải có thật ────────────
+//
+// Vì sao cần một rule riêng (G54): R6 canh "giá trị enum có xuất hiện ở đâu không" và R7
+// canh "cờ có counter trong Step 7 + summary không" — cả hai đều là nửa BÁO CÁO. Không rule
+// nào canh nửa GHI MỐC. Nên có thể khai đủ cờ + counter + khối report mà KHÔNG BAO GIỜ ghi
+// `spec_baseline`, và cờ đó **không bao giờ bật**: dấu ✅ đầy đủ trên một detector đã chết.
+//
+// Đúng hình dạng G1 (`@trace.sc_version`: 3 consumer, 0 producer) — chỉ khác là lần này
+// "producer" không phải một field trong sổ mà là một khối trong report, nên R1 không thấy.
+{
+  const SED = schema.spec_edit_detection;
+  if (SED) {
+    const vtRel = schema.actors['validate-traces'];
+    const vt = vtRel ? actorText['validate-traces'] : null;
+    if (!vt) {
+      err('R13', '`spec_edit_detection` khai mà không định vị được validate-traces',
+          'Không đọc được actor thì R13 mù — sửa `actors` trong schema.');
+    } else {
+      const bf = SED.baseline_fields || {};
+      // (a) nửa GHI: khối baseline + mọi key của nó phải được validate-traces nhắc.
+      if (!bf.path) {
+        err('R13', '`spec_edit_detection.baseline_fields` thiếu `path` — R13 không có gì để neo');
+      } else {
+        if (!mentions(vt, bf.path)) {
+          err('R13', `${vtRel} KHÔNG nhắc \`${bf.path}\` — cờ \`${SED.flag}\` sẽ không bao giờ bật`,
+              'Nửa BÁO CÁO (cờ + counter + khối report) có thể đủ mà nửa GHI MỐC thì vắng, và\n'
+            + '        khi đó detector đã chết trong khi mọi rule khác vẫn ✅. R6 canh giá trị enum,\n'
+            + '        R7 canh counter — không rule nào canh việc mốc có được GHI.');
+        }
+        // Nửa GHI phải hiện diện như một KEY trong JSON skeleton của report, không chỉ được
+        // nhắc trong prose. Vì sao phân biệt: phần ĐỌC mốc (Step 3.9) cũng nhắc `spec_baseline`,
+        // nên một `mentions()` trần bị nửa-đọc thoả mãn và nửa-GHI có thể vắng hoàn toàn —
+        // detector chết trong khi R13 vẫn ✅. Đúng điểm yếu của R3, và của chính bản R12 đầu tiên.
+        // Dạng key JSON (`"spec_baseline"`, có ngoặc kép) chỉ xuất hiện ở skeleton report.
+        if (!vt.includes(`"${bf.path}"`)) {
+          err('R13', `${vtRel} không khai \`"${bf.path}"\` như một KEY trong JSON report`,
+              'Đọc mốc mà không GHI mốc thì lần chạy sau không có gì để so ⇒ cờ im lặng mãi.\n'
+            + '        Prose nhắc tên là chưa đủ — key phải có thật trong skeleton `trace-report.json`,\n'
+            + '        vì đó là thứ lần chạy sau đọc.');
+        }
+      }
+      for (const k of bf.keys || []) {
+        if (!mentions(vt, k)) {
+          err('R13', `${vtRel} KHÔNG nhắc key mốc \`${k}\``,
+              `\`${bf.path}\` thiếu key này ⇒ lần chạy sau không so được, và cờ im lặng.`);
+        }
+      }
+      // (a2) MỌI command khai là reader của mốc phải nhắc nó. Khai một consumer mà file của nó
+      //      không biết gì là đúng hình dạng G31/G32 (schema khai, thực tế không có) — và ở đây
+      //      nó còn im lặng theo hướng xấu: `sync` được khai đọc mốc để trả lời "đổi gì kể từ
+      //      lần AUDIT", mà không đọc thì nó rơi về câu "kể từ lần PULL" — reset mỗi lần pull.
+      for (const cmd of SED.read_by || []) {
+        const rel2 = schema.actors[cmd];
+        if (!rel2) {
+          err('R13', `\`spec_edit_detection.read_by\` khai \`${cmd}\` — không có trong \`actors\``,
+              'Không định vị được file thì R13 mù với consumer đó.');
+          continue;
+        }
+        if (!mentions(actorText[cmd] || '', bf.path)) {
+          err('R13', `${rel2} khai là reader của \`${bf.path}\` nhưng KHÔNG nhắc nó`,
+              'Khai một consumer mà file của nó không biết gì = schema nói một chuyện, thực tế một\n'
+            + '        chuyện khác. Ở đây còn hỏng theo hướng xấu: mốc audit tích luỹ đúng qua nhiều\n'
+            + '        lần pull, còn mốc pull-to-pull thì reset — dùng sai mốc là ẩn nợ đã tích.');
+        }
+      }
+
+      // (b) cờ phải nằm trong vocabulary — nếu không thì R6/R7 không phủ nó.
+      const flags = (schema.vocabularies.audit_flags || {}).values || [];
+      if (SED.flag && !flags.includes(SED.flag)) {
+        err('R13', `\`${SED.flag}\` không có trong \`vocabularies.audit_flags\``,
+            'Ngoài vocabulary thì R6 (giá trị chết) và R7 (đủ ba tầng quan sát) đều KHÔNG phủ nó.');
+      }
+      // (c) mỗi nguồn bằng chứng phải được nhắc — thiếu một nguồn là thiếu một lớp ca.
+      //     `git status` bắt ca sửa CHƯA commit, thường gặp hơn ca đã commit.
+      for (const e of SED.evidence || []) {
+        if (!vt.includes(e.source)) {
+          err('R13', `${vtRel} KHÔNG nhắc nguồn bằng chứng \`${e.source}\``,
+              `Nó bắt: ${e.catches}. Thiếu nguồn này là mù với cả lớp ca đó.`);
+        }
+      }
+      // (d) ca degraded phải được khai — im lặng khi không kiểm được là tệ nhất trong ba
+      //     lựa chọn (bịa cờ · im lặng · nói rõ đang mù).
+      if (!SED.degraded) {
+        err('R13', '`spec_edit_detection` thiếu `degraded`',
+            'Không phải git repo / history bị rewrite là ca THẬT. Không khai cách xử thì agent\n'
+          + '        tự chọn, và lựa chọn rẻ nhất là im lặng — tức detector tắt mà không ai biết.');
+      }
+      // (e) KHÔNG được lặng lẽ trôi vào gate.blocking. Nếu team muốn chặn thì đó là quyết
+      //     định có chủ ý của họ, và phải kèm lý do trong schema như mọi entry blocking khác.
+      const inBlocking = ((schema.gate || {}).blocking || [])
+        .some(b => b.counter === `${SED.flag.toLowerCase()}_count`);
+      if (inBlocking) {
+        const entry = schema.gate.blocking.find(b => b.counter === `${SED.flag.toLowerCase()}_count`);
+        if (!entry.why) {
+          err('R13', `\`${SED.flag}\` đã vào \`gate.blocking\` mà thiếu \`why\``,
+              'Đưa một cờ SPEC vào cổng "code đang hỏng" là mở rộng nghĩa của gate.blocking —\n'
+            + '        phải nói được vì sao, và phải chắc nợ tồn đã dọn (xem $comment của khối).');
+        }
+      }
+    }
+  }
+}
+
+// ── R14 — quyền khẳng định `pass`: chủ cột phải ĐỌC status, và T12 phải tồn tại ─
+//
+// Vì sao cần rule riêng (G55): schema khai cột 21 `status` có `read_by` gồm dev-run-test và
+// qc-run-test — và R3 xác nhận ✅ vì cả hai file CÓ nhắc `status`… trong đúng câu khai rằng
+// chúng "trực giao" với nó, tức cố ý KHÔNG dùng. Số lần đọc thật: 0.
+//
+// Đây là lần thứ ba cùng một điểm yếu xuất hiện (R3 `mentions()` không phân biệt "đọc" với
+// "nhắc tên"; R12 và R13 đều đã phải chuyển sang use-check vì nó). R14 neo vào một thứ chỉ
+// tồn tại khi guard được implement THẬT: file phải nhắc từng giá trị `status` bị chặn VÀ giá
+// trị hạ xuống — một câu tuyên bố "trực giao" không thể thoả mãn cả hai.
+{
+  const PAG = schema.positive_assertion_guards;
+  if (PAG) {
+    if (!PAG.blocked_when_status || !PAG.blocked_when_status.length) {
+      err('R14', '`positive_assertion_guards.blocked_when_status` rỗng — guard không chặn gì cả');
+    }
+    const statusVals = (schema.vocabularies.trace_status || {}).values || [];
+    for (const st of PAG.blocked_when_status || []) {
+      if (statusVals.length && !statusVals.includes(st)) {
+        err('R14', `\`blocked_when_status\` nêu "${st}" — không thuộc vocabulary \`trace_status\``,
+            `Giá trị cho phép: ${statusVals.join(' | ')}`);
+      }
+    }
+
+    for (const g of PAG.guards || []) {
+      const rel = `commands/${g.owner}.tmpl`;
+      const abs = path.join(ROOT, rel);
+      if (!fs.existsSync(abs)) {
+        err('R14', `\`positive_assertion_guards\` khai chủ cột \`${g.column}\` là \`${g.owner}\` — ${rel} không tồn tại`);
+        continue;
+      }
+      const text = fs.readFileSync(abs, 'utf8');
+      // (a) chủ cột phải nhắc TỪNG status bị chặn — bằng chứng nó thực sự rẽ nhánh theo status.
+      //     Dùng mentions() (khớp ranh giới token), KHÔNG includes(): `DRIFTED` CHỨA `DRIFT`,
+      //     nên một includes() trần vẫn ✅ sau khi ai đó đổi tên giá trị và guard đã chết.
+      //     Đây đúng cái bẫy mentions() được viết ra để chặn — xem doc-comment của nó.
+      for (const st of PAG.blocked_when_status || []) {
+        if (!mentions(text, st)) {
+          err('R14', `${rel} KHÔNG nhắc status \`${st}\` — nó ghi \`${g.column}\` mà không đọc \`status\``,
+              `Schema khai nó là consumer của cột \`status\`, và R3 xác nhận ✅ vì file có nhắc\n`
+            + `        chữ "status" — nhưng nhắc trong câu "trực giao" là cố ý KHÔNG dùng. Trên row\n`
+            + `        ${st}, "${g.positive_values.join('/')}" là lời khẳng định SAI: ${g.why}`);
+        }
+      }
+      // (b) phải nhắc giá trị HẠ XUỐNG — nếu không thì biết chặn mà không biết ghi gì thay.
+      if (g.downgrade_to && !mentions(text, g.downgrade_to)) {
+        err('R14', `${rel} KHÔNG nhắc giá trị hạ xuống \`${g.downgrade_to}\` cho \`${g.column}\``,
+            'Biết phải chặn mà không nói ghi gì thay thì agent tự chọn, và lựa chọn rẻ nhất là\n'
+          + '        giữ nguyên giá trị cũ — tức guard không có tác dụng.');
+      }
+      // (c) `fail` KHÔNG được nằm trong positive_values. Chặn tin xấu là biến một guard
+      //     chống-báo-cáo-sai thành một guard CHE tin xấu — hỏng theo hướng nguy hiểm hơn.
+      if ((g.positive_values || []).includes('fail')) {
+        err('R14', `\`${g.column}\`: \`fail\` nằm trong \`positive_values\``,
+            '`fail` là tin xấu THẬT, luôn hợp lệ trên mọi status. Chặn nó là che lỗi.');
+      }
+      if (!g.why) {
+        err('R14', `\`positive_assertion_guards\` mục \`${g.column}\` thiếu \`why\``,
+            'Một guard không nói được VÌ SAO sẽ bị người sau coi là tuỳ ý và gỡ đi.');
+      }
+    }
+
+    // (d) TẦNG HAI phải tồn tại: lint-trace thực sự phát ra rule id đã khai. Guard ở lệnh chỉ
+    //     chặn NGUỒN; sổ sửa tay / sổ sinh bởi version cũ / lệnh tương lai quên luật đều lọt.
+    if (PAG.lint_rule) {
+      const ltRel = 'bin/lint-trace.js';
+      const lt = fs.existsSync(path.join(ROOT, ltRel))
+        ? fs.readFileSync(path.join(ROOT, ltRel), 'utf8') : '';
+      const emits = new Set((lt.match(/\b(?:err|warn)\('(T\d+)'/g) || [])
+        .map(m => /T\d+/.exec(m)[0]));
+      if (!emits.has(PAG.lint_rule)) {
+        err('R14', `schema khai \`lint_rule: ${PAG.lint_rule}\` mà ${ltRel} KHÔNG phát ra rule đó`,
+            'Chỉ có guard ở lệnh là chỉ chặn được NGUỒN. Sổ ghi tay, sổ sinh bởi version cũ, hay\n'
+          + '        một lệnh tương lai quên luật đều lọt — và không gì bắt được, vì T1–T8 chỉ kiểm\n'
+          + '        hình dạng TỪNG Ô, không kiểm nhất quán GIỮA các ô.');
+      }
+      // Neo vào TRUY CẬP THUỘC TÍNH (`schema.positive_assertion_guards`), không phải tên
+      // xuất hiện ở đâu đó: doc-comment của T12 cũng nhắc tên khối, nên một includes() trần
+      // vẫn ✅ sau khi ai đó thay bằng danh sách hard-code. Lần thứ ba cùng một bẫy —
+      // R12 và R13 đều đã phải chuyển sang use-check vì nó.
+      if (!/schema\s*\.\s*positive_assertion_guards/.test(lt)) {
+        err('R14', `${ltRel} không ĐỌC \`schema.positive_assertion_guards\``,
+            'Hard-code lại danh sách cột/status trong lint = hai nguồn-sự-thật, và chúng sẽ lệch\n'
+          + '        âm thầm: thêm một cột nghiệm thu mới vào schema thì lint không biết, và T12\n'
+          + '        chỉ canh một nửa số cột trong khi dấu ✅ vẫn đầy đủ.');
+      }
+    }
+  }
+}
+
 // ── report ────────────────────────────────────────────────────────────────────
 const tagCount = schema.tags.length;
 const colCount = schema.tsv_columns.length;
@@ -337,7 +1127,19 @@ show(errors, '❌');
 show(warns,  '⚠️ ');
 
 if (!errors.length && !warns.length) {
-  console.log(`  ✅ ${tagCount} tag + ${colCount} cột TSV + ${auxCount} bảng phụ + ${queueCount} hàng đợi + ${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('');