@educa-corp/sdd-framework 0.6.0 → 0.7.1

package/bin/gate-trace.js

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

package/bin/index.js

@@ -201,21 +201,48 @@ try {
   corePrebuilt = fs.readFileSync(coreVersionFile, 'utf8').trim() === VERSION;
 } catch { /* không có file = chưa build */ }
 
-if (!corePrebuilt && fs.existsSync(buildScript)) {
+// `hasSources` LÀ phép phân biệt dev-checkout vs bản cài từ npm — đặt tên MỘT LẦN.
+//
+// Vì sao gọi tên nó (GAPS-v4 G59): trước đó cùng một `existsSync(commands/*.tmpl)` được viết
+// ở hai chỗ với hai ý khác nhau, và `package.json → files` thì SHIP `commands/` — nên phép thử
+// LUÔN đúng và consumer nhìn thấy một lời nhắc mà chú thích của chính nó nói là
+// "consumer không cần biết bước này tồn tại". Đã kiểm bằng cách pack rồi chạy tarball thật.
+// Giờ `files` chỉ còn bin/ core/ scripts/ docs/, nên `hasSources` phân biệt đúng.
+const hasSources = fs.existsSync(path.join(ROOT, 'commands', 'generate-code.tmpl'));
+
+if (!corePrebuilt && hasSources && fs.existsSync(buildScript)) {
+  // DEV CHECKOUT, core/ vắng hoặc lệch version → dựng lại từ nguồn.
   try {
     require(buildScript);
   } catch (err) {
     console.error('Build step failed:', err.message);
     process.exit(1);
   }
-} else if (corePrebuilt && fs.existsSync(path.join(ROOT, 'commands', 'generate-code.tmpl'))) {
-  // Chỉ nói trong DEV CHECKOUT (có .tmpl nguồn). Consumer không cần biết bước này tồn tại.
-  // Cần thiết vì trước G43 thì `--init` luôn build, nên "sửa .tmpl rồi --init" từng có tác
-  // dụng. Giờ không — và một thay đổi lặng lẽ như thế sẽ tốn của ai đó nửa tiếng.
+} else if (!corePrebuilt) {
+  // BẢN CÀI TỪ NPM mà core/ vắng hoặc lệch version — KHÔNG có nguồn để dựng lại.
+  //
+  // Trước G59, nhánh này rơi vào `require(buildScript)` và build.js chết với một ENOENT trên
+  // `commands/` — thông báo không nói được vấn đề thật. Cố build ở đây còn tệ hơn: G43 đã nêu
+  // rõ là nó ghi vào THƯ MỤC PACKAGE (npx cache / node_modules global), có thể read-only, và
+  // hai `--init` song song sẽ đua nhau. Nên: dừng với một câu nói đúng việc cần làm.
+  console.error('');
+  console.error(`❌ Bản cài này thiếu core/ dựng sẵn cho v${VERSION}.`);
+  console.error('   Package đã tải về bị thiếu/hỏng — KHÔNG thể dựng lại vì tarball không mang');
+  console.error('   commands/*.tmpl (có chủ ý: nguồn chỉ có trong dev checkout).');
+  console.error('');
+  console.error('   Xử:  npx clear-npx-cache   (hoặc xoá thủ công cache npx) rồi chạy lại');
+  console.error(`        npm i -g @educa-corp/sdd-framework@${VERSION}   nếu dùng bản global`);
+  process.exit(1);
+} else if (hasSources) {
+  // corePrebuilt && hasSources → DEV CHECKOUT, core/ đã khớp version.
+  // Cần lời nhắc này vì trước G43 thì `--init` LUÔN build, nên "sửa .tmpl rồi --init" từng có
+  // tác dụng. Giờ không — và một thay đổi lặng lẽ như thế sẽ tốn của ai đó nửa tiếng.
   console.log('');
   console.log(`ℹ️  core/ đã build sẵn (v${VERSION}) — bỏ qua bước build.`);
   console.log('   Vừa sửa commands/*.tmpl · steps/ · templates/ ? Chạy `npm run build` trước.');
 }
+// corePrebuilt && !hasSources → bản cài từ npm, mọi thứ đúng chỗ. IM LẶNG — đây là đường của
+// consumer, và họ không cần biết bước build tồn tại.
 
 // ── --init mode: install to .agent/ + create .claude/commands/ shortcuts ─────
 if (isInit) {

package/bin/lint-trace.js

@@ -95,6 +95,20 @@ function buildEnumBindings() {
 }
 const ENUMS = buildEnumBindings();
 
+// ── T12 — quyền khẳng định `pass` (G55) ───────────────────────────────────────
+//
+// T1–T8 kiểm HÌNH DẠNG TỪNG Ô (đủ cột · giá trị trong vocabulary · ngày parse được). Không
+// rule nào kiểm NHẤT QUÁN GIỮA CÁC Ô — nên `status=DRIFT` + `dev_selftest=pass` là một sổ
+// HOÀN TOÀN HỢP LỆ với cả 11 rule cũ. T12 là rule đầu tiên nhìn nhiều ô cùng lúc.
+//
+// Vì sao cần dù /dev-run-test đã có guard: guard đó chặn NGUỒN. T12 bắt TRẠNG THÁI, bất kể
+// ai ghi ra — sổ sửa tay, sổ sinh bởi version framework cũ, hay một lệnh tương lai quên luật.
+// Hai tầng độc lập; đây là tầng chạy được trong CI mà không cần LLM.
+//
+// Đọc từ schema, KHÔNG hard-code: self-check R14 canh việc rule id ở đây khớp
+// `positive_assertion_guards.lint_rule`.
+const PAG = schema.positive_assertion_guards || null;
+
 // Ô "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']);
@@ -296,6 +310,33 @@ function lintBook(file) {
             `Định dạng: YYYY-MM-DD hoặc ISO-8601 đầy đủ (hoặc — nếu chưa biết)`);
       }
     }
+
+    // T12 — row không được vừa `status` ∈ {DRIFT, ORPHANED} vừa mang một giá trị KHẲNG ĐỊNH
+    // ở cột nghiệm thu. `fail`/`skip` KHÔNG bị chặn: chúng không phải lời khẳng định, và
+    // chặn chúng là biến guard chống-báo-cáo-sai thành guard che-tin-xấu.
+    if (PAG) {
+      const statusIdx = header.indexOf('status');
+      const st = statusIdx === -1 ? '' : String(f[statusIdx] || '').trim();
+      if (PAG.blocked_when_status.includes(st)) {
+        for (const g of PAG.guards) {
+          const gi = header.indexOf(g.column);
+          if (gi === -1) continue;                       // sổ cũ vắng cột ở đuôi — T1 lo việc đó
+          const val = String(f[gi] || '').trim();
+          if (!g.positive_values.includes(val)) continue;
+          warn('T12', at,
+               `status = "${st}" nhưng ${g.column} = "${val}"`,
+               `${g.why}
+` +
+               `        "${val}" không mang nghĩa "test đã chạy xanh" — nó mang nghĩa "scenario này
+` +
+               `        đã được nghiệm thu theo spec HIỆN TẠI". Trên row ${st} thì nghĩa đó SAI.
+` +
+               `        Hạ ${g.column} → ${g.downgrade_to} (và ${g.companion} → ${g.companion_downgrade}),
+` +
+               `        hoặc xử ${st} rồi chạy lại /${g.owner}.`);
+        }
+      }
+    }
   }
 }
 

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
@@ -25,6 +26,23 @@
  *       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,
@@ -110,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 || [])];
@@ -448,7 +486,12 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
       return vtText.slice(a, b < 0 ? undefined : b);
     };
     const summaryZone = slice('"summary": {', '"prds"');
-    const issuesZone  = slice('"issues": {', '"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`,
@@ -487,6 +530,76 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
         }
       }
 
+      // (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 ✅.
@@ -557,7 +670,10 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
     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)) {
+      // `_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ả 🔴.`);
@@ -681,6 +797,317 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
   }
 }
 
+// ── 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;