@educa-corp/sdd-framework 0.9.6 → 0.9.8

package/bin/self-check.js

@@ -103,8 +103,26 @@ function allSourceFiles() {
   push(path.join(ROOT, 'templates'), () => true);
   push(path.join(ROOT, 'rules'),    f => f.endsWith('.md'));
   push(path.join(ROOT, 'modules'),  f => f.endsWith('.yaml') || f.endsWith('.md'));
+  // skills/ vào scan set từ Bước S · S0 (2026-09-17). Trước đó R4/R5/R6 mù với toàn bộ
+  // skills/ — và 21 trong 27 file mang stack QC cũ nằm đúng ở đó, nên R5 không canh được
+  // việc một stack đã bỏ quay trở lại. Đo trước khi mở: 11 pattern đang có × 64 file
+  // skills/**/*.md = 0 hit, tức mở scan set không làm đỏ thứ gì đang xanh.
+  push(path.join(ROOT, 'skills'),   f => f.endsWith('.md'));
   return out;
 }
+
+/**
+ * Glob tối giản cho `forbidden_patterns[].scope`. Hỗ trợ `*` (không qua `/`) và `**`
+ * (qua mọi cấp) — đủ cho ba dạng đang dùng và cố ý KHÔNG hơn: một glob engine đầy đủ ở
+ * đây là thứ không ai đọc lại, và scope sai thì rule im lặng chứ không kêu lên.
+ */
+function globMatch(glob, rel) {
+  const re = glob.split('/').map(seg =>
+    seg === '**' ? '.*'
+                 : seg.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')
+  ).join('/').replace(/\/\.\*$/, '(?:/.*)?');
+  return new RegExp(`^${re}$`).test(rel);
+}
 const sources = allSourceFiles().map(p => ({
   rel: path.relative(ROOT, p).replace(/\\/g, '/'),
   text: fs.readFileSync(p, 'utf8'),
@@ -281,16 +299,43 @@ for (const fp of schema.forbidden_patterns) {
   // `except` = file được phép chứa pattern vì nó đang TRÍCH DẪN pattern trong một cảnh
   // báo ("đừng glob X"). Mỗi entry phải kèm lý do trong schema — không phải ignore mù.
   const except = new Set(Object.keys(fp.except || {}));
-  const hits = sources.filter(s => s.text.includes(fp.pattern) && !except.has(s.rel));
+  // `scope` (thêm ở Bước S · S0) = mảng glob giới hạn vùng file rule soi tới. KHÔNG khai
+  // scope = toàn scan set, nên mọi entry có từ trước giữ nguyên hành vi. Vì sao cần: `pytest`
+  // bị cấm trong phạm vi QC nhưng HỢP LỆ ở lane DEV — modules/context-engineering là module
+  // Python thật, dev-gen-test mặc định sinh test Python. Cấm toàn cục là 4 dương tính giả,
+  // và dương tính giả đẻ ra except bừa cho tới khi R5 rỗng ruột mà vẫn xanh.
+  const inScope = s => !fp.scope || fp.scope.some(g => globMatch(g, s.rel));
+  const hits = sources.filter(s => inScope(s) && s.text.includes(fp.pattern) && !except.has(s.rel));
   if (hits.length) {
     err('R5', `Pattern bị cấm quay lại: \`${fp.pattern}\`  (${fp.gap})`,
         `${fp.reason}\n        Thấy ở: ${hits.map(h => h.rel).join(', ')}`);
   }
-  // Cảnh báo nếu một except trở nên vô nghĩa — cảnh báo đã bị xoá thì except cũng nên bỏ
+  // Cảnh báo nếu một except trở nên vô nghĩa — cảnh báo đã bị xoá thì except cũng nên bỏ.
+  // Nằm ngoài `scope` cũng là vô nghĩa: file đó không bao giờ bị soi, giữ except chỉ làm
+  // người đọc tưởng nó đang che một thứ có thật.
   for (const f of except) {
     const src = sources.find(s => s.rel === f);
-    if (!src || !src.text.includes(fp.pattern)) {
-      warn('R5', `\`${fp.pattern}\`: except \`${f}\` không còn chứa pattern — bỏ except này khỏi schema`);
+    if (!src || !src.text.includes(fp.pattern) || !inScope(src)) {
+      warn('R5', `\`${fp.pattern}\`: except \`${f}\` không còn chứa pattern (hoặc ngoài scope) — bỏ except này khỏi schema`);
+    }
+  }
+}
+
+// Một `scope` glob khớp 0 file thì rule **trông như** đang canh một vùng, thực ra canh không
+// khí — đúng kiểu rỗng ruột mà cảnh báo `except` chết ở trên sinh ra để chống, chỉ ở đầu kia.
+// Đã suýt xảy ra thật ở S0: scope trỏ `qa-runner/**` (thư mục S2 sắp XOÁ) và không trỏ
+// `qa-script-designer/**` (thư mục S2 sắp TẠO) → sau S2 đèn xanh vì RỖNG, không vì SẠCH.
+// Chỉ WARN, không ERROR: trỏ vào thư mục chưa tạo là hợp lệ trong lúc đang chuyển stack.
+// Gộp theo glob, không theo entry — 6 entry dùng chung một scope thì cảnh báo một lần.
+{
+  const seen = new Set();
+  for (const fp of schema.forbidden_patterns) {
+    for (const g of (fp.scope || [])) {
+      if (seen.has(g)) continue;
+      seen.add(g);
+      if (!sources.some(s => globMatch(g, s.rel))) {
+        warn('R5', `scope \`${g}\` khớp 0 file — thư mục chưa tồn tại, hoặc đã bị xoá mà glob còn ở lại`);
+      }
     }
   }
 }
@@ -1096,7 +1141,7 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
 // ── 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
+// qc-run-script — 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
@@ -1118,10 +1163,15 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
     }
 
     for (const g of PAG.guards || []) {
-      const rel = `commands/${g.owner}.tmpl`;
+      // `owner` là CHUỖI khi cột có một chủ, MẢNG khi có nhiều (F2 · Đợt 2 · b2: cột
+      // `qc_status` có HAI chủ — /qc-run-script và /qc-run-manualtest). Chuẩn hoá về mảng
+      // thay vì khai hai entry guard cho cùng một cột: hai entry làm `blocked_when_status`
+      // và `downgrade_to` bị chép đôi, và hai nơi nói một chuyện thì một nơi sẽ lệch (R19).
+      for (const owner of (Array.isArray(g.owner) ? g.owner : [g.owner])) {
+      const rel = `commands/${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`);
+        err('R14', `\`positive_assertion_guards\` khai chủ cột \`${g.column}\` là \`${owner}\` — ${rel} không tồn tại`);
         continue;
       }
       const text = fs.readFileSync(abs, 'utf8');
@@ -1143,6 +1193,7 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
             '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')) {
@@ -1187,7 +1238,7 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
 //
 // R3 hỏi "file có nhắc tên field không". Đó là câu SAI cho những field mà trả lời sai
 // gây hại im lặng. Ca thật: schema khai cột `status` có read_by gồm dev-run-test và
-// qc-run-test; R3 xác nhận ✅ vì cả hai file CÓ nhắc `status` — trong đúng câu khai rằng
+// qc-run-script; 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. Đó là G55, và R3
 // xác nhận contract bằng đúng câu văn đang phủ nhận contract.
 //
@@ -1493,7 +1544,7 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
   }
 }
 
-// ── R18 — lệnh ghi artifact phải KHAI, và "có người nhập tay" thì phải `hard` ──
+// ── R18 — lệnh ghi artifact phải KHAI, và cái ĐÈ MẤT KHÔNG DỰNG LẠI ĐƯỢC thì phải `hard` ──
 //
 // Vì sao: `gate.checkpoint_levels` là ALLOWLIST với mặc định `normal` (mức LỎNG NHẤT), và
 // R11 duyệt TỪ SCHEMA RA FILE — nó chỉ kiểm lệnh ĐÃ liệt kê. Lệnh chưa khai thì không vòng
@@ -1501,26 +1552,107 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
 //
 // R18 duyệt CHIỀU NGƯỢC LẠI. Đó là toàn bộ giá trị của nó: một checker duyệt allowlist chỉ
 // thấy được cái ĐÃ KHAI, mà cái CHƯA KHAI mới là chỗ lỗi sống.
+//
+// HAI LUẬT ÉP `hard`, KHÔNG PHẢI MỘT:
+//   (A) `has_human_content: true`                                    — cấp LỆNH
+//   (B) artifact `mode !== 'append'` + `regenerable: false` + `when: 'always'` — cấp ARTIFACT
+//
+// Luật (B) sinh ra vì (A) không phủ được SỔ TÍCH LUỸ: `trace-history.jsonl` KHÔNG ai gõ tay
+// vào — nên (A) trả lời "false", ĐÚNG CHỮ — trong khi chính /validate-traces gọi nó là
+// AUTHORITATIVE, không regenerate được. Đè lên là mất vĩnh viễn.
+//
+// VÌ SAO `mode !== 'append'` CHỨ KHÔNG PHẢI `mode === 'overwrite'`:
+// `merge` KHÔNG an toàn. /amend-prd là merge, và nó tự khai là "thao tác ghi DUY NHẤT trong
+// framework được phép làm output KHÔNG phải superset của bản cũ". Chỉ `append` an toàn vô
+// điều kiện. Gộp `merge` vào diện miễn là mở lại đúng cánh cửa vừa đóng.
+//
+// VÌ SAO (B) THÊM ĐIỀU KIỆN `when === 'always'` (D4):
+// Hành vi ghi thuộc về CHẾ ĐỘ, không thuộc về lệnh. NĂM lệnh tự khai "read-only" và cả năm
+// đều có ghi (/review-context · /review-tech-docs · /validate-traces · /review-code · /debug).
+// Ghi có điều kiện thì người dùng đã phải gõ THÊM một cờ hoặc trả lời Y — bản thân việc đó
+// đã là một cổng. Ép `hard` cho cả lệnh vì một nhánh hiếm là phạt nhầm chế độ đọc:
+// /validate-traces chạy hàng ngày ở chế độ đọc, và dựng cổng chặn lên nó vì nhánh
+// `--reconcile-code` sẽ dạy người ta thêm `--yes` vào script — rồi `--yes` đó nằm lại vĩnh
+// viễn, kể cả cho ngày họ chạy `--reconcile-code`.
+//
+// ĐỔI LẠI, ĐIỀU KIỆN PHẢI KIỂM CHỨNG ĐƯỢC — nếu không thì `when` thành cửa thoát cho mọi
+// lệnh lười khai. `when` là tên cờ ⇒ tmpl PHẢI nhắc đúng cờ đó; `when: 'confirm'` ⇒ tmpl
+// PHẢI có câu hỏi (Y/N). Khai một điều kiện không tồn tại thì luật trông như đã được áp
+// trong khi không ai áp — đúng bài học R17.
 {
   const AW = schema.artifact_writers;
   const CL = (schema.gate || {}).checkpoint_levels;
   if (AW && CL) {
-    const hardSet = new Set((CL.hard || []).map(e => e.cmd));
+    const hardSet = new Set((CL.hard || []).filter(e => e.cmd).map(e => e.cmd));
     const enrolled = AW.enrolled || {};
     const pending = (AW.pending_enrollment || {}).cmds || [];
+    // Từ vựng đọc TỪ SCHEMA, không hard-code — thêm giá trị mới mà quên dạy checker là đúng
+    // kiểu lỗi R18 sinh ra để bắt.
+    const MODES = Object.keys(AW.write_modes || {}).filter(k => k !== '$comment');
+    // Mode được miễn luật (B) — ĐỌC TỪ SCHEMA, không hard-code (xem artifact_writers.safe_modes).
+    const SAFE = new Set(((AW.safe_modes || {}).modes) || ['append']);
+    const ALWAYS = 'always';
+    const CONFIRM = 'confirm';
+    const isFlag = w => /^--[a-z0-9][a-z0-9-]*$/.test(w);
+    const validWhen = w => w === ALWAYS || w === CONFIRM || isFlag(w);
 
     for (const cmd of Object.keys(enrolled)) {
       const e = enrolled[cmd];
       const rel = `commands/${cmd}.tmpl`;
+      const abs = path.join(ROOT, rel);
 
-      if (!fs.existsSync(path.join(ROOT, rel))) {
+      if (!fs.existsSync(abs)) {
         err('R18', `\`artifact_writers.enrolled\` khai \`${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à registry đang phủ nó.');
         continue;
       }
+      const tmpl = fs.readFileSync(abs, 'utf8');
+
       if (!Array.isArray(e.writes) || !e.writes.length) {
         err('R18', `\`artifact_writers.enrolled.${cmd}\` thiếu \`writes\``,
             'Không liệt kê ghi cái gì thì không ai kiểm được "cái đó có người nhập tay không".');
+      } else {
+        e.writes.forEach((w, i) => {
+          const at = `artifact_writers.enrolled.${cmd}.writes[${i}]`;
+          if (typeof w !== 'object' || w === null || Array.isArray(w)) {
+            err('R18', `\`${at}\` phải là object, không phải chuỗi`,
+                'Khuôn cũ (list chuỗi) không chứa được \`mode\`/\`regenerable\`/\`when\`. Một lệnh đụng\n'
+              + '        nhiều artifact khác tính chất thì cờ phẳng ở cấp lệnh luôn nói dối một nửa.');
+            return;
+          }
+          if (!w.path) {
+            err('R18', `\`${at}\` thiếu \`path\``,
+                'Không có tên thì không đối chiếu ngược được với tmpl.');
+          }
+          if (!MODES.includes(w.mode)) {
+            err('R18', `\`${at}\` có \`mode\` không hợp lệ: ${JSON.stringify(w.mode)}`,
+                `Phải là một trong: ${MODES.join(' · ')} — định nghĩa ở \`artifact_writers.write_modes\`.`);
+          }
+          if (typeof w.regenerable !== 'boolean') {
+            err('R18', `\`${at}\` thiếu \`regenerable\` (boolean)`,
+                'Câu hỏi mà \`has_human_content\` KHÔNG hỏi được: "đè mất thì dựng lại được không?".\n'
+              + '        Sổ tích luỹ không ai gõ tay vào, nên \`has_human_content\` trả lời false — đúng\n'
+              + '        chữ, và để lọt đúng thứ mà mất là mất vĩnh viễn.');
+          }
+          if (!validWhen(w.when)) {
+            err('R18', `\`${at}\` thiếu/sai \`when\`: ${JSON.stringify(w.when)}`,
+                'Phải là \`always\`, \`confirm\`, hoặc một tên cờ dạng \`--ten-co\`. Hành vi ghi thuộc\n'
+              + '        về CHẾ ĐỘ, không thuộc về lệnh — năm lệnh đã khai "read-only" trong khi cả năm\n'
+              + '        đều có ghi, chính vì nhãn đặt theo chế độ mặc định rồi không ai sửa.');
+            return;
+          }
+          // Điều kiện phải KIỂM CHỨNG ĐƯỢC, nếu không `when` thành cửa thoát.
+          if (isFlag(w.when) && !tmpl.includes(w.when)) {
+            err('R18', `\`${at}\` khai \`when: "${w.when}"\` nhưng ${rel} KHÔNG nhắc cờ đó`,
+                'Khai một điều kiện không tồn tại thì luật trông như đã được áp trong khi không ai\n'
+              + '        áp — đúng bài học R17. Và nó miễn luôn artifact này khỏi luật (B).');
+          }
+          if (w.when === CONFIRM && !/\(Y\/N\)/.test(tmpl)) {
+            err('R18', `\`${at}\` khai \`when: "confirm"\` nhưng ${rel} không có câu hỏi \`(Y/N)\``,
+                '`confirm` nghĩa là NGƯỜI đã bấm Y — đó là cái thay cho CHECKPOINT. Không tìm thấy\n'
+              + '        câu hỏi nào thì thao tác ghi đang chạy thẳng, mà vẫn được miễn luật (B).');
+          }
+        });
       }
       if (typeof e.has_human_content !== 'boolean') {
         err('R18', `\`artifact_writers.enrolled.${cmd}\` thiếu \`has_human_content\` (boolean)`,
@@ -1533,17 +1665,70 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
             'Bắt buộc CẢ KHI `has_human_content: false`. Ghi đè an toàn mà không ai khai là an\n'
           + '        toàn thì một ngoại lệ CÓ CHỦ Ý trông y hệt một chỗ sót — và sẽ bị copy đi (G79).');
       }
+
+      // ── Luật (B) — cấp ARTIFACT, chỉ cho thao tác ghi VÔ ĐIỀU KIỆN ──
+      const doomed = (Array.isArray(e.writes) ? e.writes : [])
+        .filter(w => w && typeof w === 'object'
+                  && !SAFE.has(w.mode) && w.regenerable === false && w.when === ALWAYS);
+      if (doomed.length && !hardSet.has(cmd)) {
+        const w = doomed[0];
+        err('R18', `\`${cmd}\` ghi \`${w.mode}\` lên artifact KHÔNG dựng lại được ở MỌI lần chạy, nhưng KHÔNG ở \`checkpoint_levels.hard\``,
+            `Artifact: ${w.path}\n`
+          + `        Khai: "${String(w.note || e.why || '').slice(0, 110)}…"\n`
+          + '        Không ai gõ tay vào nó thì `has_human_content` vẫn là false — đúng chữ. Nhưng\n'
+          + `        \`${w.mode}\` lên thứ không dựng lại được là mất VĨNH VIỄN, và \`--yes\` ở mức\n`
+          + '        `normal` làm việc đó TRONG IM LẶNG.\n'
+          + `        Sửa: thêm \`${cmd}\` vào gate.checkpoint_levels.hard · HOẶC \`mode: "append"\` nếu\n`
+          + '        thao tác thật sự chỉ thêm bản ghi mới · HOẶC `when` là cờ/confirm nếu nó CÓ điều kiện.');
+      }
+
+      // ── Luật (A) — cấp LỆNH ──
       if (e.has_human_content === true && !hardSet.has(cmd)) {
-        err('R18', `\`${cmd}\` ghi artifact CÓ phần người nhập tay nhưng KHÔNG ở \`checkpoint_levels.hard\``,
-            `Khai: "${String(e.why || '').slice(0, 110)}…"\n`
-          + `        Ghi đè thứ người nhập tay mà chỉ ở mức \`normal\` thì \`--yes\` xoá nó TRONG IM LẶNG.\n`
-          + `        Sửa: thêm \`${cmd}\` vào gate.checkpoint_levels.hard + viết §luật chạy lại trong lệnh.`);
+        // `has_human_content` là cờ CẤP LỆNH. Khi một lệnh ghi nhiều artifact mà chỉ MỘT trong
+        // số đó có phần người nhập tay, cờ cấp lệnh không nói được điều đó — và luật (A) sẽ ép
+        // `hard` vì một tiền đề SAI. Gặp thật ở /fix-bug (N3): 4 artifact, chỉ `{lessons_path}`
+        // có phần người nhập tay, và nó nằm sau `(Y/N)`.
+        // Nên artifact ĐƯỢC PHÉP tự khai `human_content: true`; khi có khai, luật (A) chỉ xét
+        // đúng những artifact đó. Không khai thì giữ hành vi cũ (xét mọi artifact) — an toàn hơn.
+        // Miễn cho mode AN TOÀN, y như luật (B). Gặp thật ở /qc-run-manualtest (Đợt 2 · b2):
+        // MANUAL_EVIDENCE.md CÓ phần người nhập tay và ghi ở MỌI lần chạy — nhưng `append`,
+        // nên không lần ghi nào làm mất dòng nào. Ép `hard` ở đó là chặn một thao tác không
+        // mất gì, tức đúng loại ma sát vô ích mà `unconditional_hard_budget` sinh ra để chống.
+        const flagged = (e.writes || []).filter(w => w && w.human_content === true);
+        const scope = (flagged.length ? flagged : (e.writes || [])).filter(w => w && !SAFE.has(w.mode));
+        const conditional = scope.every(w => w && w.when && w.when !== ALWAYS);
+        if (!conditional) {
+          err('R18', `\`${cmd}\` ghi artifact CÓ phần người nhập tay nhưng KHÔNG ở \`checkpoint_levels.hard\``,
+              `Khai: "${String(e.why || '').slice(0, 110)}…"\n`
+            + `        Ghi đè thứ người nhập tay mà chỉ ở mức \`normal\` thì \`--yes\` xoá nó TRONG IM LẶNG.\n`
+            + `        Sửa: thêm \`${cmd}\` vào gate.checkpoint_levels.hard + viết §luật chạy lại trong lệnh.`);
+        }
+      }
+    }
+
+    // `non_writers` — lệnh đã rà và kết luận KHÔNG ghi gì. Một lệnh vắng mặt ở cả ba danh sách
+    // trông y hệt một lệnh bị quên; ghi ra đây biến "không có gì" thành kết luận kiểm chứng được.
+    const NW = AW.non_writers || {};
+    for (const c of NW.cmds || []) {
+      if (!fs.existsSync(path.join(ROOT, `commands/${c}.tmpl`))) {
+        err('R18', `\`non_writers\` khai \`${c}\` — commands/${c}.tmpl không tồn tại`,
+            'Khai một lệnh không có thật làm danh sách trông đã phủ rộng hơn thực tế.');
+      }
+      if (enrolled[c]) {
+        err('R18', `\`${c}\` ở CẢ \`non_writers\` LẪN \`enrolled\``,
+            'Mâu thuẫn trực tiếp: vừa khai không ghi gì, vừa liệt kê nó ghi cái gì. Chọn một.');
+      }
+      if (!(NW.why || {})[c]) {
+        err('R18', `\`non_writers\` khai \`${c}\` nhưng thiếu lý do trong \`why\``,
+            '"Không ghi gì" phải là một KẾT LUẬN kiểm chứng được, không phải một khoảng trống —\n'
+          + '        cùng lập luận đã bắt `why` phải khai cả khi `has_human_content: false` (G79).');
       }
     }
 
     // Chiều ngược: lệnh đã ở `hard` VÌ LÝ DO GHI ĐÈ phải có mặt trong registry.
     for (const h of CL.hard || []) {
-      if (!/ghi đè/i.test(String(h.why || ''))) continue;   // `hard` vì lý do khác (vd --resume)
+      if (!h.cmd) continue;                                  // mục $comment
+      if (!/ghi đè/i.test(String(h.why || ''))) continue;     // `hard` vì lý do khác (vd --resume)
       if (!enrolled[h.cmd] && !pending.includes(h.cmd)) {
         err('R18', `\`${h.cmd}\` ở \`checkpoint_levels.hard\` vì ghi đè, nhưng không có trong \`artifact_writers\``,
             'Hai nơi cùng nói về một chuyện mà chỉ một nơi biết — nơi kia sẽ lệch.\n'
@@ -1553,6 +1738,295 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
   }
 }
 
+// ── R19 — bảng mức gate CHÉP TAY trong steps/ và rules/ phải khớp schema ─────
+//
+// Vì sao: cùng một danh sách "lệnh nào chặn, lệnh nào không" tồn tại ở BA nơi, xếp thành
+// một chuỗi "nguồn" mà KHÔNG AI THỰC THI:
+//     rules/workflow.md  — tự nhận "đây chỉ là bản tóm tắt, gate là nguồn"
+//     steps/gate.md      — tự nhận "Nguồn máy đọc: bin/trace-schema.json"
+//     bin/trace-schema.json — nguồn thật
+// Mỗi bản trỏ sang bản sau nói "kia mới là nguồn", và cả hai vẫn CHÉP CỨNG tên lệnh. Một
+// con trỏ tới nguồn KHÔNG ngăn được bản sao lệch — nó chỉ làm người sửa yên tâm rằng có ai
+// đó đang canh.
+//
+// Đã lệch thật (2026-09-16): /review-context và /review-tech-docs chuyển `none` → `hard`,
+// schema + commands/*.tmpl + README đều sửa, build XANH — mà hai bảng kia vẫn liệt chúng ở
+// "Không chặn". R11 canh `commands/*.tmpl` ↔ schema nên người sửa tin là "đã có máy canh
+// mức gate"; phạm vi nó canh hẹp hơn thế. BIẾT CÓ MÁY CANH KHÔNG BẰNG BIẾT MÁY CANH ĐẾN ĐÂU.
+//
+// QUÉT THEO DÒNG, KHÔNG THEO FILE. Mục đích là GIỮ được ví dụ cụ thể (thứ làm bảng dễ đọc)
+// mà vẫn buộc ví dụ phải ĐÚNG. Cấm hẳn việc nêu tên sẽ làm bảng khó hiểu hơn, và rồi người
+// ta chép lại ở chỗ khác — xa hơn, khó canh hơn.
+//
+// KHÔNG quét `skills/`: ở đó "read-only" nói về ARTIFACT ĐANG XEM (vd /review-code không
+// sửa code nó review), không nói về mức CHECKPOINT. Hai nghĩa khác nhau của cùng một chữ.
+{
+  const CL = (schema.gate || {}).checkpoint_levels;
+  if (CL) {
+    const hardSet = new Set((CL.hard || []).filter(e => e.cmd).map(e => e.cmd));
+    const noneSet = new Set((CL.none || []).filter(e => e.cmd).map(e => e.cmd));
+    const realLevel = c => hardSet.has(c) ? 'hard' : (noneSet.has(c) ? 'none' : 'normal');
+
+    // Từ-mức ↔ khoá schema. `normal` là MẶC ĐỊNH (không liệt kê trong schema — xem R11).
+    const ROW = [
+      [/^\|\s*\*\*Không chặn\*\*/i,  'none'],
+      [/^\|\s*\*\*Chặn thường\*\*/i, 'normal'],
+      [/^\|\s*\*\*Chặn CỨNG\*\*/i,   'hard'],
+    ];
+
+    for (const dir of ['steps', 'rules']) {
+      const abs = path.join(ROOT, dir);
+      if (!fs.existsSync(abs)) continue;
+      for (const f of fs.readdirSync(abs).filter(x => x.endsWith('.md'))) {
+        const rel = `${dir}/${f}`;
+        const lines = fs.readFileSync(path.join(abs, f), 'utf8').split(/\r?\n/);
+        lines.forEach((line, i) => {
+          const hit = ROW.find(([re]) => re.test(line));
+          if (!hit) return;                        // không phải hàng bảng mức
+          const declared = hit[1];
+          // Lookbehind chặn báo oan: "sinh/sửa artifact" từng bị cắt ra thành lệnh `/s`.
+          const names = [...line.matchAll(/(?<!\p{L})\/([a-z][a-z0-9-]{2,})(?![\p{L}\d-])/gu)].map(m => m[1]);
+          for (const c of new Set(names)) {
+            if (!fs.existsSync(path.join(ROOT, 'commands', `${c}.tmpl`))) {
+              err('R19', `${rel}:${i + 1} nêu \`/${c}\` — commands/${c}.tmpl không tồn tại`,
+                  'Một ví dụ trỏ vào lệnh không có thật làm cả hàng mất giá trị: người đọc không\n'
+                + '        phân biệt được đâu là tên cũ chưa dọn, đâu là tên đang sai.');
+              continue;
+            }
+            const real = realLevel(c);
+            if (real !== declared) {
+              err('R19', `${rel}:${i + 1} xếp \`/${c}\` vào mức \`${declared}\`, schema nói \`${real}\``,
+                  'Hai file này được nạp vào MỌI phiên chạy. gate.md tự viết: "Hai file cùng được\n'
+                + '        nạp vào mọi lệnh mà nói ngược nhau; agent theo cái nào là TUỲ LÚC".\n'
+                + `        Sửa hàng bảng cho khớp \`gate.checkpoint_levels\`, đừng sửa schema cho khớp bảng.`);
+            }
+          }
+        });
+      }
+    }
+
+    // Chiều ngược: lệnh ở `hard`/`none` không được nằm nhầm hàng ở bất kỳ bảng nào — đã phủ
+    // bởi vòng trên. Nhưng một lệnh `none` mà KHÔNG bảng nào nêu thì người đọc không có ví
+    // dụ nào — đó là mất mát tài liệu, không phải lỗi contract, nên chỉ cảnh báo.
+    const shown = new Set();
+    for (const dir of ['steps', 'rules']) {
+      const abs = path.join(ROOT, dir);
+      if (!fs.existsSync(abs)) continue;
+      for (const f of fs.readdirSync(abs).filter(x => x.endsWith('.md'))) {
+        const txt = fs.readFileSync(path.join(abs, f), 'utf8');
+        for (const line of txt.split(/\r?\n/)) {
+          if (!ROW.some(([re]) => re.test(line))) continue;
+          for (const m of line.matchAll(/(?<!\p{L})\/([a-z][a-z0-9-]{2,})(?![\p{L}\d-])/gu)) shown.add(m[1]);
+        }
+      }
+    }
+    const missing = [...noneSet].filter(c => !shown.has(c));
+    if (missing.length) {
+      warn('R19', `mức \`none\` có lệnh không bảng nào nêu làm ví dụ: ${missing.join(', ')}`,
+           'Không phải lỗi contract — nhưng `none` là mức LỎNG NHẤT và cũng là mức dễ bị copy\n'
+         + '        nhầm nhất. Một ví dụ trong bảng rẻ hơn một lần copy sai.');
+    }
+  }
+}
+
+// ── R20 — mỗi cổng CỨNG phải khai ĐIỀU KIỆN nó nổ, và số cổng vô điều kiện có HẠN MỨC ──
+//
+// Vì sao: `hard` là mức `--yes` KHÔNG bỏ qua được. Khi nó trở nên phiền, người dùng không
+// thêm `--yes` — họ GỠ LỆNH KHỎI `hard`. Và lúc đó mất luôn những cổng đáng giữ. Một cơ chế
+// cổng chặn quá dày không làm hệ thống an toàn hơn rồi chậm hơn; nó làm hệ thống KÉM an toàn
+// hơn, vì nó tiêu huỷ chính cơ chế nó thuộc về. gate.md Bước 3b tồn tại vì đúng rủi ro đó:
+// "cổng luôn in ra một bảng giống hệt nhau … nên Y thành phản xạ và cổng hỏng âm thầm".
+//
+// ĐO 2026-09-16 — 12 lệnh ở `hard`, nhưng chỉ 3 trong đó nổ ở MỌI lần chạy:
+//     7 lệnh khai "chỉ áp khi file đã tồn tại"  → lần chạy đầu đi thẳng
+//     2 lệnh CÓ điều kiện y hệt nhưng KHÔNG khai (generate-prd · generate-architecture)
+//     3 lệnh không có lần chạy vô hại (extend/amend/refine-prd — chỉ chạy trên PRD đã duyệt)
+// Con số gây lo lắng là 12; con số ĐÚNG là 3. R20 làm con số 3 đó đo được và giữ được.
+//
+// BẮT KHAI `null` KÈM LÝ DO: "không có điều kiện" và "quên nghĩ tới điều kiện" trông y hệt
+// nhau — đúng lập luận đã bắt `why` phải khai cả khi `false` (G79).
+//
+// ĐIỀU KIỆN PHẢI CÓ Ở CẢ HAI NƠI: khai trong schema mà tmpl không nói thì agent đọc tmpl sẽ
+// chặn mọi lần — hình dạng G41, hai nguồn nói khác nhau.
+{
+  const CL = (schema.gate || {}).checkpoint_levels;
+  if (CL) {
+    const B = CL.unconditional_hard_budget;
+    // Khuôn câu thu hẹp trong tmpl. Chấp nhận cả `*Mức cứng chỉ áp …*` lẫn
+    // `*Mức cứng **chỉ áp** …*` — hai biến thể đang cùng tồn tại.
+    const NARROW_LINE = /Mức cứng\s*(?:\*\*)?\s*chỉ áp/i;
+    const unconditional = [];
+
+    for (const e of CL.hard || []) {
+      if (!e.cmd) continue;
+      const rel = `commands/${e.cmd}.tmpl`;
+
+      if (!('narrowing' in e)) {
+        err('R20', `\`checkpoint_levels.hard\` mục \`${e.cmd}\` thiếu \`narrowing\``,
+            'Phải khai điều kiện cổng nổ — hoặc `null` nếu KHÔNG có lần chạy vô hại.\n'
+          + '        Bỏ trống thì "cố ý không có điều kiện" trông y hệt "quên nghĩ tới điều kiện",\n'
+          + '        và người sau sẽ copy chỗ sót đi (G79).');
+        continue;
+      }
+
+      if (e.narrowing === null) {
+        unconditional.push(e.cmd);
+        if (!e.narrowing_why) {
+          err('R20', `\`${e.cmd}\` khai \`narrowing: null\` nhưng thiếu \`narrowing_why\``,
+              'Cổng nổ ở MỌI lần chạy là thứ đắt nhất trong cơ chế này. Nói ra vì sao nó ĐÚNG,\n'
+            + '        nếu không người sau sẽ tưởng là chỗ sót rồi thêm điều kiện cho "đỡ phiền".');
+        }
+        continue;
+      }
+
+      if (typeof e.narrowing !== 'string' || !e.narrowing.trim()) {
+        err('R20', `\`${e.cmd}\`.\`narrowing\` phải là chuỗi điều kiện hoặc \`null\``,
+            `Thấy: ${JSON.stringify(e.narrowing)}`);
+        continue;
+      }
+
+      const abs = path.join(ROOT, rel);
+      if (fs.existsSync(abs) && !NARROW_LINE.test(fs.readFileSync(abs, 'utf8'))) {
+        err('R20', `\`${e.cmd}\` khai \`narrowing\` trong schema nhưng ${rel} KHÔNG có câu thu hẹp`,
+            `Khai: "${e.narrowing.slice(0, 95)}…"\n`
+          + '        Agent đọc TMPL, không đọc schema. Thiếu câu đó thì nó chặn MỌI lần chạy —\n'
+          + '        đúng thứ điều kiện này sinh ra để tránh. Thêm một dòng ngay dưới nhãn\n'
+          + '        Checkpoint theo khuôn: *Mức cứng chỉ áp khi …*');
+      }
+    }
+
+    // ── Hạn mức — bánh cóc cho số cổng nổ vô điều kiện ──
+    if (!B || typeof B.max !== 'number') {
+      err('R20', '`checkpoint_levels.unconditional_hard_budget.max` chưa khai',
+          'Với mọi cơ chế mà "thêm một cái nữa" luôn hợp lý từng lần, hạn mức phải nằm TRONG\n'
+        + '        contract để việc vượt nó là một lần sửa NHÌN THẤY trong diff, không phải một\n'
+        + '        hệ quả cộng dồn.');
+    } else if (unconditional.length > B.max) {
+      err('R20', `${unconditional.length} cổng cứng nổ VÔ ĐIỀU KIỆN, vượt hạn mức ${B.max}`,
+          `Đang vượt: ${unconditional.join(', ')}\n`
+        + '        `--yes` KHÔNG bỏ qua được `hard`. Nên khi `hard` quá phiền, người ta không thêm\n'
+        + '        `--yes` — họ GỠ LỆNH KHỎI `hard`, và mất luôn cổng đáng giữ.\n'
+        + '        Sửa: thêm `narrowing` cho một lệnh, HOẶC nâng `max` — nâng là một QUYẾT ĐỊNH,\n'
+        + '        phải kèm lý do trong `why` của khối ngân sách.');
+    } else if (Array.isArray(B.current)) {
+      const a = [...unconditional].sort().join(',');
+      const b = [...B.current].sort().join(',');
+      if (a !== b) {
+        err('R20', '`unconditional_hard_budget.current` lệch với thực tế',
+            `khai:  ${b || '(rỗng)'}\n        thật: ${a || '(rỗng)'}\n`
+          + '        Danh sách chép tay cạnh một con số sẽ lệch — đúng bài học R19. Cập nhật nó.');
+      }
+    }
+
+    if (B && typeof B.max === 'number' && !B.why) {
+      err('R20', '`unconditional_hard_budget` thiếu `why`',
+          'Một con số không nói được vì sao sẽ bị người sau nâng lên cho tiện.');
+    }
+  }
+}
+
+// ── R21 — mọi `checked_by[].cmd` phải trỏ vào một lệnh CÓ THẬT ───────────────
+//
+// Vì sao: nhiều khối contract khai "ai canh điều kiện này" bằng một danh sách `checked_by`.
+// Khi một lệnh bị ĐỔI TÊN hoặc TÁCH ĐÔI, danh sách đó lệch mà KHÔNG máy nào bắt — và hậu quả
+// tệ hơn một tham chiếu treo thường: contract vẫn khai điều kiện đó "đã được canh", trong khi
+// không lệnh nào còn canh nó. Người đọc contract thấy một cái lưới; cái lưới không có ở đó.
+//
+// GẶP THẬT (Đợt 2 · b1 · 2026-09-16): tách /qc-review → /qc-review-testcase + /qc-review-script.
+// `testid_fourth_leg.checked_by` — CHÂN THỨ TƯ của hợp đồng test-id (G64/G76) — trỏ vào tên cũ.
+// Bản kế hoạch của bước đó khai "tách không đụng schema, grep → 0"; grep thật ra 3. Nếu tin bản
+// kế hoạch, chân thứ tư mất người canh và build vẫn XANH.
+//
+// Đây là hình dạng đã gặp ở R17 ("khai một producer không tồn tại thì luật trông như đã được áp,
+// trong khi không ai áp") — R21 là cùng luật đó, áp cho `checked_by` thay vì `declared_by`.
+//
+// QUÉT ĐỆ QUY, không liệt kê tên khối: hôm nay có 2 khối (`testid_fourth_leg`, `qc_artifact_stamp`);
+// khối thứ ba thêm vào mà quên dạy checker là đúng kiểu lỗi rule này sinh ra để bắt.
+{
+  const seen = [];
+  (function walk(node, at) {
+    if (!node || typeof node !== 'object') return;
+    for (const k of Object.keys(node)) {
+      const v = node[k];
+      if (k === 'checked_by' && Array.isArray(v)) seen.push([at + '.' + k, v]);
+      if (v && typeof v === 'object') walk(v, at + '.' + k);
+    }
+  })(schema, '');
+
+  if (!seen.length) {
+    warn('R21', 'không tìm thấy khối `checked_by` nào',
+         'Rule này sinh ra để canh chúng. Không còn khối nào thì hoặc contract đã đổi hình,\n'
+       + '        hoặc rule đang quét sai chỗ — cả hai đều đáng nhìn lại.');
+  }
+
+  for (const [at, list] of seen) {
+    list.forEach((e, i) => {
+      if (!e || !e.cmd) {
+        err('R21', `\`${at}[${i}]\` thiếu \`cmd\``,
+            'Một mục "ai canh" không nói được AI canh thì nó không khai gì cả.');
+        return;
+      }
+      const rel = `commands/${e.cmd}.tmpl`;
+      if (!fs.existsSync(path.join(ROOT, rel))) {
+        err('R21', `\`${at}\` khai \`${e.cmd}\` — ${rel} không tồn tại`,
+            'Lệnh bị đổi tên hoặc TÁCH ĐÔI? Contract vẫn khai điều kiện này "đã được canh", nhưng\n'
+          + '        không lệnh nào còn canh nó — tệ hơn một lỗ hổng ai cũng biết là chưa canh.\n'
+          + '        Sửa: trỏ sang lệnh THỪA HƯỞNG vai đó, đừng chỉ xoá mục.');
+      }
+    });
+  }
+}
+
+// ── R22 — mọi artifact được khai phải có ÍT NHẤT MỘT lệnh TẠO ra nó ──────────
+//
+// Vì sao: `artifact_writers` trả lời "ai ghi gì", nhưng GHI không đồng nghĩa với TẠO. Một lệnh
+// khai `mode: merge` là nói "tôi sửa một phần của file đã có" — nó KHÔNG hứa file đó tồn tại.
+// Nếu MỌI lệnh ghi một artifact đều chỉ `merge`, thì **không lệnh nào sinh ra nó**, và cả chuỗi
+// trạm phía sau đứng chờ một file không bao giờ xuất hiện. Build vẫn xanh suốt.
+//
+// GẶP THẬT, HAI CA (Đợt 2 · b3 · 2026-09-16):
+//   · AUTOMATION_ASSESSMENT.md — /qc-design-script khai ghi CỘT `Script file` của nó (merge),
+//     và /qc-run-manualtest đọc cột `Automatable` từ nó. Không lệnh nào TẠO. Ba lệnh viết ở b2
+//     cùng trỏ vào một file không ai sinh, và không rule nào kêu.
+//   · _seams.tsv — /generate-code tự nói "tạo file + header nếu chưa có", nhưng KHÔNG khai
+//     artifact đó; chỉ /validate-traces khai (merge, "nếu tồn tại"). Sổ này rơi hẳn khỏi registry.
+//
+// `creates: true` LÀ ĐƯỜNG KHAI CHÍNH XÁC, KHÔNG PHẢI ĐƯỜNG TRỐN. Nhiều lệnh vừa tạo-khi-vắng
+// vừa merge-khi-có (file findings của /refine-prd · /review-context · /review-tech-docs). Ép
+// chúng khai `overwrite` là nói dối — chế độ delta của chúng GIỮ `status` của reviewer. Nên
+// mode vẫn `merge`, và `creates: true` nói thêm "và tôi sinh nó ra nếu chưa có".
+{
+  const AW = schema.artifact_writers;
+  if (AW && AW.enrolled) {
+    // Khoá nhận dạng artifact: tên file trong `path`. Cùng tên = cùng artifact, bất kể
+    // placeholder thư mục khác nhau ({qc_artifact_dir} vs {refinement_dir}).
+    const KEY = /([A-Z][A-Z0-9_]{3,}(?:_?<[A-Z]+>)?\.[A-Za-z.]+|[a-z][a-z-]*\.(?:tsv|jsonl|json|yaml|yml))/;
+    const seen = new Map();          // tên file → [{cmd, mode, creates}]
+
+    for (const [cmd, e] of Object.entries(AW.enrolled)) {
+      for (const w of e.writes || []) {
+        if (!w || typeof w !== 'object') continue;
+        const m = KEY.exec(String(w.path || ''));
+        if (!m) continue;            // artifact mô tả bằng lời (vd "Page Object") — không khoá được
+        if (!seen.has(m[1])) seen.set(m[1], []);
+        seen.get(m[1]).push({ cmd, mode: w.mode, creates: w.creates === true });
+      }
+    }
+
+    const CREATING = new Set(['overwrite', 'create', 'append']);
+    for (const [file, writers] of seen) {
+      const creators = writers.filter(w => CREATING.has(w.mode) || w.creates);
+      if (creators.length) continue;
+      err('R22', `\`${file}\` không lệnh nào TẠO — mọi lệnh ghi nó đều \`merge\``,
+          `Đang ghi: ${writers.map(w => w.cmd + ':' + w.mode).join(' · ')}\n`
+        + '        `merge` nói "tôi sửa một phần của file ĐÃ CÓ" — nó không hứa file đó tồn tại. Cả\n'
+        + '        chuỗi trạm sau sẽ đứng chờ một file không bao giờ xuất hiện, và build vẫn xanh.\n'
+        + '        Sửa: khai lệnh TẠO nó (`overwrite`/`create`/`append`), HOẶC thêm `creates: true`\n'
+        + '        vào entry của lệnh vừa-tạo-khi-vắng vừa-merge-khi-có.');
+    }
+  }
+}
+
 // ── report ────────────────────────────────────────────────────────────────────
 const tagCount = schema.tags.length;
 const colCount = schema.tsv_columns.length;
@@ -1576,6 +2050,13 @@ if (!errors.length && !warns.length) {
   // 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`);
+  {
+    const _CL = (schema.gate || {}).checkpoint_levels || {};
+    const _hard = (_CL.hard || []).filter(e => e.cmd);
+    const _u = _hard.filter(e => e.narrowing === null);
+    const _max = ((_CL.unconditional_hard_budget || {}).max);
+    console.log(`     + ${_hard.length} cổng CỨNG, trong đó ${_u.length} nổ VÔ ĐIỀU KIỆN` + (typeof _max === 'number' ? ` (hạn mức ${_max})` : '') + ` — ${_hard.length - _u.length} cổng còn lại chỉ nổ khi đã có thứ để mất`);
+  }
   // ĐẾ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 = '?';