@educa-corp/sdd-framework 0.9.4 → 0.9.6

package/bin/build.js

@@ -64,9 +64,19 @@ const RUNTIME_READ = {
     'rồi mới tiếp tục phần bên dưới.\n' +
     '\n' +
     'Nó chốt bốn thứ mà mọi trạm QC đều cần: `TICKET-ID` · `active_platform` ·\n' +
-    '`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--include-draft`).\n' +
+    '`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--force`).\n' +
     'Bỏ qua thì artifact QC ghi vào **sai thư mục** và `qc_status` ghi vào **sai sổ trace** —\n' +
     'cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.',
+
+  // Cùng lý do với qc-scope: 5 lệnh qc-* include, inline là nhân 5 bản một quy trình.
+  'steps/qc-stamp.md':
+    '**BẮT BUỘC — đọc `.agent/steps/qc-stamp.md` và thực thi phần áp cho lệnh này**,\n' +
+    'rồi mới tiếp tục phần bên dưới.\n' +
+    '\n' +
+    'Nó có **hai vế**: §1 **ghi** khối `Nguồn & phiên bản` vào artifact lệnh này sinh ra ·\n' +
+    '§2 **so** stamp của artifact lệnh này ĐỌC với version hiện tại của spec.\n' +
+    'Bỏ vế ghi thì trạm sau không có gì để so; bỏ vế so thì stamp thành một con số không ai\n' +
+    'đọc — và một bộ TC lỗi thời sẽ chạy xanh rồi ghi `pass` **hợp lệ theo mọi phép kiểm**.',
 };
 
 /**

package/bin/lint-trace.js

@@ -97,6 +97,25 @@ const TRACE_DIRS = flag('--trace', '.trace').split(',').map(s => s.trim()).filte
 const SPECS_DIR  = flag('--specs', 'specs');
 // Không có default: quét sai chỗ còn tệ hơn không quét. Thiếu cờ → T14 skip + in một dòng.
 const CODE_DIRS  = (flag('--code', '') || '').split(',').map(s => s.trim()).filter(Boolean);
+// Cùng khuôn --code, cùng lý do: gốc artifact QC ({qc_dir}, mặc định `docs`) KHÔNG được đoán.
+// Nó là path QC duy nhất không remap theo spec_source, nên ở umbrella nó ở repo KHÁC với specs.
+// Thiếu cờ → T19 skip CÓ TIẾNG.
+const QC_DIRS    = (flag('--qc', '') || '').split(',').map(s => s.trim()).filter(Boolean);
+// ── G87 — thu hẹp rule TECH-DOC theo PRD, KHÔNG thu hẹp rule SỔ ──────────────
+//
+// validate-traces:66 khai cố ý: "lint luôn chạy toàn bộ. SỔ HỎNG Ở DOMAIN KHÁC VẪN LÀ SỔ HỎNG".
+// Đúng — cho T1–T14: .tsv là dữ liệu KHÔNG regenerate được, hỏng ở đâu cũng là hỏng.
+// T15/T16/T19/T20 canh TECH-DOC, không canh sổ. Lý do kia không nối sang được, mà `exit 1` thì
+// chung một cửa — nên một lệnh CÓ SCOPE (`/validate-traces --prd FEAT-01-1`) bị chặn bởi lỗi ở
+// 29 PRD ngoài scope.
+//
+// VÌ SAO KHÔNG DÙNG `--specs` HẸP LẠI: lintTestidContract() cần `{domain}/{prd-slug}` để tìm bdd/,
+// nên `--specs {specs}/{domain}/{prd-slug}` làm `parts.length < 3` ⇒ `continue` ⇒ BỎ QUA IM LẶNG.
+// Cách lách hiển nhiên nhất cho ra XANH GIẢ — tệ hơn không lách.
+const SCOPE_PRD  = (flag('--scope-prd', '') || '').split(',').map(s => s.trim()).filter(Boolean);
+// `{domain}/{prd-slug}` có nằm trong scope không. Rỗng = không scope = kiểm tất.
+const inScopePrd = (domain, prdSlug) =>
+  !SCOPE_PRD.length || SCOPE_PRD.includes(`${domain}/${prdSlug}`);
 
 // ── Contract dẫn xuất từ schema ───────────────────────────────────────────────
 //
@@ -807,6 +826,390 @@ function lintCodeVsLedger() {
   }
 }
 
+// ── T15/T16 — hợp đồng test-id: bảng §4.5.6 vs .feature ─────────────────────
+//
+// Vì sao là PASS RIÊNG, không đi cùng vòng lặp sổ: hai rule này so tech-doc với .feature,
+// không đụng một ô nào của sổ trace. Neo chúng vào sổ là làm chúng câm ở repo chưa có sổ.
+//
+// PHẠM VI neo vào SỰ TỒN TẠI CỦA HỢP ĐỒNG: doc không có block §4.5 client thì không kiểm gì.
+// Dự án backend-only, hay dự án chưa từng chạy /map-testids, phải IM LẶNG HOÀN TOÀN. Hai rule
+// này nói *"chỗ nào đã hứa thì phải giữ"*, KHÔNG nói *"mọi chỗ đều phải có hợp đồng"* — nếu
+// không thì mọi dự án đang chạy đỏ ngay ngày nâng version, và việc đầu tiên người ta làm là
+// thêm --warn-only vào CI. Mất luôn cả hai rule.
+
+// Ô/dòng còn `{…}` là PLACEHOLDER của template. MỌI tech-doc vừa sinh ra đều mang dòng mẫu
+// `| {uc}-{screen}-{element}-{type} | … | {UC1 · SC1, UC1 · SC3} |`. Không bỏ qua thì doc mới
+// tinh đã đỏ vì "SC1 của UC1 không tồn tại" — báo oan ngay lần chạy đầu tiên.
+const hasPlaceholder = s => /\{[^}\n]*\}/.test(s);
+
+// ── G82 — `{…}` mang HAI nghĩa ở cùng một chỗ ────────────────────────────────
+//
+// Luật cũ: "dòng nào có `{…}` là dòng mẫu của template → bỏ qua". Đúng khi chỉ nhìn template.
+// Trên dữ liệu thật (28 tech-doc · 344 row §4.5.6) thì 19 row — 5,5% — dùng `{…}` làm PATTERN ID
+// CÓ THẬT: `shop-tab-{code}` · `shop-item-card-{itemId}` · `uc{n}-z2-region`. Một dòng đại diện
+// cho sáu nút, hai mươi thẻ.
+//
+// HAI MẶT, mặt thứ hai mới là mặt giết rule:
+//   (1) IM LẶNG — row bị `return` TRƯỚC khi vào `declared` ⇒ T15·T17·T18·T19 đều mù với nó.
+//   (2) BÁO OAN — .Test.md dùng instance cụ thể (`uc1-z2-region`) thì T19 kêu "không có ở
+//       §4.5.6 nào". Nó bắt oan CHÍNH CÁI nó vừa bỏ sót. Và "một rule báo oan trong tuần đầu
+//       là một rule bị tắt" — lúc đó mất luôn cả phần đang chạy đúng.
+//
+// Phân biệt bằng PHÉP ĐẾM, không bằng danh sách tên placeholder (danh sách thì phải bảo trì,
+// và template đổi tên là hỏng): dòng mẫu có `{…}` ở ≥2 Ô; pattern id thật chỉ có ở ô Test-ID.
+const isTemplateSample = cells =>
+  cells.filter(c => hasPlaceholder(c)).length >= 2;
+
+// `uc{n}-z2-region` → /^uc[^-]+-z2-region$/
+// `{…}` khớp MỘT ĐOẠN, không vượt dấu `-`. Dữ liệu thật có cả `{n}` (số), `{code}` (chữ) và
+// `{itemId}` (hỗn hợp) nên `\d+` quá chặt; còn `.+` thì `uc{n}-z2-region` sẽ nuốt cả
+// `ucFOO-BAR-BAZ-z2-region` — lỏng tới mức vô nghĩa.
+function patternToRegex(pat) {
+  const esc = pat.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');   // escape TẤT CẢ, kể cả { }
+  const body = esc.replace(/\\\{[^}]*\\\}/g, '[^-]+');      // rồi mở lại đúng các ô {…}
+  try { return new RegExp(`^${body}$`); } catch { return null; }
+}
+
+// Một id khớp hợp đồng khi: trùng nguyên văn một id đã khai, HOẶC khớp một pattern đã khai.
+const matchesDeclaredIds = (id, ids, patterns) =>
+  ids.has(id) || [...patterns].some(re => re.test(id));
+
+// ── G81 — ô "Serves SC" có ÍT NHẤT 5 dạng ngoài đời ──────────────────────────
+//
+// Đo trên 229 row §4.5.6 thật của 28 tech-doc: regex cũ đọc được 143 = 62%. 82 row dùng dấu NỐI
+// (`UC1-SC1`) thay vì `·`, và regex thứ hai — viết cho `FEAT-02-3-UC1-SC1` — khớp ĐÚNG 0 dòng.
+//
+//   UC1 · SC1                              ✅ dạng duy nhất bản cũ đọc được
+//   UC1-SC1 · UC2-SC1 · UC3-SC1            ❌ dấu nối
+//   UC1-SC8                                ❌ dấu nối
+//   UC3-SC5..SC11                          ❌ range
+//   UC6-SC4, SC5                           ❌ nối tiếp (SC thứ hai mượn UC của SC đầu)
+//   mọi SC của UCn                         ❌ prose — KHÔNG parse được, và đó là chuyện thường
+//
+// TRẢ VỀ { ids, parsed }: `parsed=false` nghĩa là ô có chữ mà không rút được token nào. Gọi bên
+// ngoài PHẢI đếm số đó và in ra — im lặng-vì-không-hiểu khác im lặng-vì-không-có-gì-để-báo, và
+// gộp hai thứ đó là biến "chưa kiểm" thành "đã sạch" (đúng loại lỗi thứ tư mà T13 đặt tên).
+function parseServesCell(cell, ticket) {
+  const ids = [];
+  let lastUC = null;
+  // Quét tuần tự: mỗi lần gặp UC{n} thì nhớ nó, để `, SC5` phía sau mượn được.
+  const tokenRe = /UC(\d+)\s*[·.\-]\s*SC(\d+)(?:\s*\.\.\s*SC(\d+))?|(?:^|[,;·]\s*)SC(\d+)(?:\s*\.\.\s*SC(\d+))?/g;
+  for (const m of cell.matchAll(tokenRe)) {
+    if (m[1]) {                                    // dạng UC{a}-SC{b} (hoặc `·`, `.`)
+      lastUC = m[1];
+      const from = +m[2], to = m[3] ? +m[3] : +m[2];
+      for (let i = from; i <= to; i++) ids.push(`${ticket}-UC${lastUC}-SC${i}`);
+    } else if (m[4] && lastUC) {                   // dạng nối tiếp `, SC5` — mượn UC gần nhất
+      const from = +m[4], to = m[5] ? +m[5] : +m[4];
+      for (let i = from; i <= to; i++) ids.push(`${ticket}-UC${lastUC}-SC${i}`);
+    }
+  }
+  // Dạng đầy đủ có tiền tố ticket (`FEAT-02-3-UC1-SC1`) — giữ từ bản cũ, 0 hit trên dữ liệu thật
+  // nhưng template vẫn cho phép.
+  for (const m of cell.matchAll(/\b([A-Za-z]+-[\d-]*\d-UC\d+-SC\d+)\b/g)) ids.push(m[1]);
+
+  const hasWords = /[A-Za-zÀ-ỹ0-9]/.test(cell);
+  return { ids: [...new Set(ids)], parsed: ids.length > 0 || !hasWords };
+}
+
+// Hợp đồng đã khai, gom cho T17/T18: attr → { ids: Set, byDoc: Map(doc → Set) }.
+// T18 phải so với HỢP NHẤT mọi bảng, không so từng doc: một monorepo có nhiều PRD, và id của
+// PRD khác nằm trong code là chuyện bình thường — so per-doc sẽ báo oan gần hết.
+const declared = new Map();
+// G81 — ô "Serves SC" KHÔNG rút được token nào. Đếm để in ở cuối: "chưa kiểm" không được phép
+// trông giống "đã sạch". Đo thật: 143/229 row đọc được (62%) — 86 row còn lại từng biến mất im lặng.
+const servesUnparsed = [];
+// G86 — doc LEGACY chưa có @trace.testid_attr. Gom để in MỘT dòng CÓ ĐẾM.
+const testidLegacy = [];
+
+function lintTestidContract() {
+  if (!fs.existsSync(SPECS_DIR)) return;
+
+  const docs = walk(SPECS_DIR).filter(f => /-tech-design\.md$/.test(path.basename(f)));
+  if (!docs.length) {
+    infos.push(`Không có tech-doc nào dưới ${rel(SPECS_DIR)} — bỏ qua T15/T16 (hợp đồng test-id).`);
+    return;
+  }
+
+  for (const doc of docs) {
+    const lines = readLines(doc);
+
+    // Block §4.5 theo nền: "### 4.5 … — {platform} ({framework})".
+    // Chỉ nền CLIENT mới có test-id; `system` không có UI nên nằm ngoài phạm vi.
+    const blocks = [];
+    lines.forEach((l, i) => {
+      // G81 — nền có thể GỘP: "### 4.5 … — app+web". Tách thành nhiều nền thay vì một token;
+      // không tách thì bảng gộp chỉ được kiểm theo `bdd/app`, và mọi SC chỉ có ở `web` sẽ lọt.
+      const m = /^###\s+4\.5\b[^—]*—\s*([A-Za-z0-9_+-]+)/.exec(l);
+      if (m) {
+        for (const pf of m[1].split('+').map(x => x.trim()).filter(Boolean)) {
+          if (pf !== 'system') blocks.push({ platform: pf, at: i });
+        }
+      }
+    });
+    if (!blocks.length) continue;
+
+    // ── T16 — có §4.5 client thì header PHẢI khai TÊN THUỘC TÍNH test-id ──
+    const attr = lines.find(l => /^@trace\.testid_attr\s*:/.test(l.trim()));
+    if (!attr) {
+      // ── G86 — DÒNG KHÔNG TỒN TẠI = doc LEGACY, không phải "ai đó xoá" → WARN ──
+      //
+      // Doc sinh TRƯỚC khi field này vào template thì không có dòng nào cả. Đó là trạng thái HỢP LỆ
+      // trong quy trình, y như "placeholder chưa ai điền" ở nhánh dưới — chỉ khác thời điểm.
+      // `testid_contract.$comment` đã HỨA miễn trừ đúng ca này: "dự án chưa từng chạy /map-testids
+      // phải IM LẶNG HOÀN TOÀN … thiếu điều khoản này thì mọi dự án đang chạy đỏ ngay ngày nâng
+      // version, và việc đầu tiên người ta làm là thêm --warn-only vào CI". Nhưng thực thi chỉ miễn
+      // cho doc KHÔNG có §4.5 — mà doc chưa chạy /map-testids thì VẪN có §4.5 (generate-tech-docs
+      // vẽ). Điều khoản không phủ được đúng ca nó mô tả, và dự đoán của nó đã xảy ra từng chữ:
+      // 30 doc đỏ trên một dự án đang chạy, chặn /validate-traces của một PRD không liên quan.
+      //
+      // LẬP LUẬN GIỮ `error` ĐÃ HẾT ĐÚNG. Nó là "QC đoán theo nền ⇒ trượt 100% locator TRONG IM
+      // LẶNG". Vế "im lặng" bị hai consumer vô hiệu hoá từ lâu:
+      //   qc-run-test   "Cảnh báo mềm, KHÔNG im lặng hardcode: ⚠️ Tech-doc thiếu @trace.testid_attr…"
+      //   generate-code "Cảnh báo mềm, KHÔNG im lặng hardcode, rồi mới fallback"
+      // Giữ `error` là dựng cổng thứ hai cho một chuyện đã có người canh — và cổng đó chặn nhầm
+      // người. Cùng lập luận đã dùng cho T14: "nợ tồn ở project đang chạy sẽ đỏ khắp nơi ở lần đầu
+      // và người ta sẽ TẮT CỔNG — mất luôn T1–T13 thật".
+      // Gom lại, in MỘT dòng có đếm ở cuối — 30 dòng ⚠️ riêng lẻ là ồn, và ồn thì người ta ngừng đọc.
+      testidLegacy.push(rel(doc));
+    } else if (/^@trace\.testid_attr\s*:\s*$/.test(attr.trim())) {
+      // ── Dòng CÓ mà giá trị RỖNG = ai đó xoá giá trị → vẫn ERROR ──
+      // Đây là chỗ DUY NHẤT máy phân biệt được "legacy" với "bị xoá": legacy thì DÒNG KHÔNG TỒN TẠI;
+      // bị xoá thì dòng còn đó, giá trị trống. Hạ cả hai xuống warn là mất luôn phép phân biệt.
+      err('T16', rel(doc),
+          '@trace.testid_attr có mặt nhưng RỖNG — giá trị bị xoá',
+          'Khác hẳn doc legacy (ở đó DÒNG không tồn tại). Dòng còn mà giá trị mất nghĩa là ai đó\n' +
+          '        gỡ nó khỏi một hợp đồng ĐÃ CHỐT — mọi locator QC của PRD này đang bám vào đó.\n' +
+          '        Sửa: điền lại, hoặc chạy /map-testids {UC-ID}.');
+    } else if (hasPlaceholder(attr)) {
+      warn('T16', rel(doc),
+           '@trace.testid_attr còn ở dạng placeholder — chưa ai điền',
+           'Tech-doc vừa sinh ra thì đây là trạng thái BÌNH THƯỜNG (nên là WARN, không ERROR).\n' +
+           '        Điền bằng /map-testids {UC-ID} trước khi QC dựng locator.');
+    }
+
+    // Giá trị THẬT của tên thuộc tính. Thiếu hoặc còn placeholder → null, và khi đó không gom
+    // id để so với code: không biết tìm thuộc tính nào trong code thì mọi so sánh đều là đoán.
+    const attrVal = attr && !hasPlaceholder(attr)
+      ? attr.split(':').slice(1).join(':').trim()
+      : null;
+
+    // ── T15 — mọi SC ở cột "Phục vụ SC" phải CÓ THẬT trong .feature ──
+    const parts = path.relative(SPECS_DIR, doc).replace(/\\/g, '/').split('/');
+    if (parts.length < 3) continue;      // không theo {domain}/{prd-slug}/ — bố cục cũ
+    const [domain, prdSlug] = parts;
+    if (!inScopePrd(domain, prdSlug)) continue;   // G87 — ngoài scope PRD thì không soi tech-doc
+    const ticket = path.basename(doc).replace(/-tech-design\.md$/, '');
+
+    for (const b of blocks) {
+      const bddDir = path.join(SPECS_DIR, domain, prdSlug, 'bdd', b.platform);
+      if (!fs.existsSync(bddDir)) continue;
+
+      const known = new Set();
+      for (const f of fs.readdirSync(bddDir).filter(n => n.endsWith('.feature'))) {
+        const t = fs.readFileSync(path.join(bddDir, f), 'utf8');
+        for (const m of t.matchAll(/@trace\.scenario\s*:\s*(\S+)/g)) known.add(m[1]);
+      }
+      if (!known.size) continue;         // chưa có scenario nào → không có gì để đối chiếu
+
+      const end  = lines.findIndex((l, i) => i > b.at && /^###\s/.test(l));
+      const blockEnd = end === -1 ? lines.length : end;
+
+      // Thu HẸP về đúng tiểu mục §4.5.6, không lấy cả block §4.5.
+      //
+      // Block §4.5 chứa §4.5.1 Cây Component, §4.5.2, … — toàn bảng, và chúng KHÔNG phải bảng
+      // test-id. Quét cả block thì: (a) ô "Purpose" / "Màn đứng riêng…" bị parse như ô Serves,
+      // (b) tên component (`Z2BlockController`) khớp regex id nên LỌT VÀO `declared` như một
+      // test-id. Lỗi này có từ trước; nó vô hình vì hai thứ đó chỉ "im lặng không parse được".
+      // Bộ đếm G81 làm nó lộ ra ngay lần chạy đầu trên dữ liệu thật — 146 ô, và không ô nào
+      // thuộc §4.5.6.
+      const subAt = lines.findIndex((l, i) =>
+        i > b.at && i < blockEnd && /^#{3,5}\s*4\.5\.6\b/.test(l));
+      // `continue`, KHÔNG `return`: đây là `for…of` lồng trong `for (const doc of docs)`, nên
+      // `return` thoát CẢ HÀM và bỏ im lặng mọi doc còn lại. Đã gặp: T16 rơi 30 → 9 mà mọi lệnh
+      // kiểm vẫn xanh, vì "ít cảnh báo hơn" không có gì báo là sai.
+      if (subAt === -1) continue;                      // block này không có §4.5.6 → bỏ qua
+      const subEnd = lines.findIndex((l, i) =>
+        i > subAt && i < blockEnd && /^#{1,5}\s/.test(l));
+      const body = lines.slice(subAt, subEnd === -1 ? blockEnd : subEnd);
+
+      // G80 — vị trí cột "Serves SC", tìm theo TÊN ở dòng tiêu đề; -1 = chưa thấy.
+      // Đọc-theo-vị-trí ("ô cuối") chỉ an toàn khi MỌI bảng cùng số cột — mà G81 chứng minh không:
+      // dữ liệu thật có bảng 3 cột lẫn 5 cột. Khi số cột đổi, "ô cuối" mất chỗ neo và không gì
+      // bảo đảm nó là cột Serves. Tìm theo tên trước, rơi về vị trí sau — và NÓI RA khi phải rơi.
+      let servesIdx = -1;
+
+      body.forEach((line, k) => {
+        if (!line.trim().startsWith('|')) return;
+        if (/^\|[\s|:-]+\|$/.test(line.trim())) return; // dòng phân cách markdown |---|---|
+        const cells = line.split('|').map(s => s.trim());
+
+        // Dòng TIÊU ĐỀ — chốt vị trí cột Serves rồi bỏ qua, đừng parse nó như một row.
+        // Nhận cả `Serves SC` (28/28 doc thật) lẫn `Phục vụ SC` (template cũ) — đổi tên là việc
+        // của G80, nhưng doc đã viết thì không đổi theo, nên checker phải nhận cả hai.
+        if (/^test-?id$/i.test((cells[1] || '').replace(/`/g, '').trim())) {
+          servesIdx = cells.findIndex(c => /serves|phục vụ/i.test(c));
+          return;
+        }
+
+        if (isTemplateSample(cells)) return;            // dòng mẫu của template — xem G82
+        const last  = (servesIdx > 0 ? cells[servesIdx] : cells[cells.length - 2]) || '';
+
+        // Gom id đã khai (cột 1) cho T17/T18/T19. Làm ở đây vì đây là chỗ duy nhất đã lọc xong
+        // dòng mẫu và dòng tiêu đề/phân cách.
+        // Ô Test-ID có thể mang NHIỀU id. Dữ liệu thật:
+        //     | `uc1-z2-rank-avatar` / `uc1-z2-rank-name` | Avatar/tên HS | UC1-SC8 |
+        // Lấy mọi token trong backtick; không có backtick nào thì rơi về cả ô (bảng viết trần).
+        // Đọc cả ô như MỘT id thì hai id đó không bao giờ vào `declared`, và T19 BÁO OAN cả hai
+        // khi .Test.md dùng chúng — xác nhận trên bảng thật của z2-tin-hieu-aha.
+        const rawCell = cells[1] || '';
+        const ticked  = [...rawCell.matchAll(/`([^`]+)`/g)].map(m => m[1].trim());
+        const idCells = ticked.length ? ticked : [rawCell.trim()];
+
+        for (const idCell of idCells) {
+          // Phải BẮT ĐẦU bằng chữ/số: chặn dòng phân cách (`---`) và mọi rác không phải id.
+          // `{}` được phép từ G82: `shop-tab-{code}` là pattern id THẬT, không phải placeholder.
+          if (!attrVal || idCell === 'Test-ID') continue;
+          if (!/^[A-Za-z0-9][A-Za-z0-9_.:{}-]*$/.test(idCell)) continue;
+          if (!declared.has(attrVal)) {
+            declared.set(attrVal, { ids: new Set(), patterns: new Set(), byDoc: new Map() });
+          }
+          const d = declared.get(attrVal);
+          if (!d.byDoc.has(doc)) d.byDoc.set(doc, new Set());
+          d.byDoc.get(doc).add(idCell);
+          if (hasPlaceholder(idCell)) {
+            const re = patternToRegex(idCell);
+            if (re) d.patterns.add(re);
+          } else {
+            d.ids.add(idCell);
+          }
+        }
+
+        if (!last) return;
+        // Ô "Phục vụ SC" còn `{…}` → row ĐANG ĐIỀN DỞ (ai đó thay id thật nhưng chưa thay ô này).
+        // Kiểm SC ở đây là báo oan một doc chưa viết xong. Tách khỏi luật dòng-mẫu ở trên vì
+        // G82 cần xử theo TỪNG Ô: ô Test-ID có `{…}` là PATTERN (phải kiểm), ô Serves có `{…}`
+        // là CHƯA ĐIỀN (đừng kiểm). Cùng ký hiệu, hai nghĩa, hai ô.
+        if (hasPlaceholder(last)) return;
+
+        // Năm dạng ô Serves — xem parseServesCell(). KHÔNG parse được token nào thì ĐẾM LẠI
+        // và in ở cuối (G81): im lặng-vì-không-hiểu KHÁC im lặng-vì-không-có-gì-để-báo.
+        const { ids, parsed } = parseServesCell(last, ticket);
+        if (!parsed) { servesUnparsed.push({ doc, line: subAt + k + 1, cell: last }); return; }
+        for (const id of ids) {
+          if (known.has(id)) continue;
+          err('T15', `${rel(doc)}:${subAt + k + 1}`,
+              `§4.5.6 (${b.platform}) trỏ tới ${id} — scenario này KHÔNG có trong .feature`,
+              `Đã tìm ở: ${rel(bddDir)}/\n` +
+              `        Consumer per-UC LỌC theo cột "Serves SC". Trỏ vào SC không tồn tại\n` +
+              `        ⇒ không khớp row nào ⇒ QC tưởng element không có test-id rồi đi dò DOM.\n` +
+              `        Nguyên nhân thường gặp: SC bị gộp/xoá mà bảng không được cập nhật.`);
+        }
+      });
+    }
+  }
+}
+
+// ── T17/T18 — hợp đồng §4.5.6 vs CODE thật ──────────────────────────────────
+//
+// T15/T16 canh bảng với .feature (hai tài liệu). Hai rule này canh bảng với CODE — chiều duy
+// nhất phát hiện được "FE chưa gắn" và "FE gắn ngoài hợp đồng".
+//
+// CẢ HAI LÀ WARN, không ERROR. Id đoán từ thiết kế KHÔNG sống sót 100%: lúc implement, dev có
+// thể gộp hai element thành một component hoặc tách một thành hai. Đây là NỢ CẦN THẤY, không
+// phải cái sai chặn người — cùng nhóm với TECHDOC_DRIFT.
+
+// Dựng regex tìm test-id trong code theo ĐÚNG tên thuộc tính mà tech-doc khai.
+// Không đoán được dạng → trả null, và lệnh sẽ BỎ QUA attr đó thay vì so bừa.
+function testidPattern(attr) {
+  if (/^[A-Za-z][A-Za-z0-9_-]*$/.test(attr)) {
+    // web `data-testid`/`data-test`/`data-qa` · RN `testID` · iOS `accessibilityIdentifier`
+    // Phủ: attr="x" · attr='x' · attr={"x"} · attr={'x'} · attr: "x"
+    return new RegExp(`\\b${attr.replace(/-/g, '\\-')}\\s*[=:]\\s*\\{?\\s*['"\`]([^'"\`]+)['"\`]`, 'g');
+  }
+  if (/Key|Semantics/i.test(attr)) {
+    // Flutter: Key('x') · ValueKey('x') · Semantics(identifier: 'x')
+    return /(?:\bValueKey|\bKey)\s*\(\s*['"]([^'"]+)['"]|identifier\s*:\s*['"]([^'"]+)['"]/g;
+  }
+  return null;
+}
+
+function lintTestidVsCode() {
+  if (!declared.size) return;                 // chưa có hợp đồng nào → ngoài phạm vi
+
+  if (!CODE_DIRS.length) {
+    infos.push(`T17/T18 BỎ QUA — không có --code nên chưa đối chiếu hợp đồng test-id với code. ` +
+               `Ca "FE chưa gắn id đã khai" và "FE gắn id ngoài hợp đồng" đang KHÔNG được kiểm. ` +
+               `Truyền --code {gốc mã nguồn} để bật.`);
+    return;
+  }
+  const roots = CODE_DIRS.filter(d => fs.existsSync(path.resolve(d)));
+  if (!roots.length) return;                  // T14 đã báo gốc code không tồn tại
+
+  const files = [];
+  const walkCode = dir => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) { if (!CODE_SKIP_DIR.has(e.name)) walkCode(path.join(dir, e.name)); }
+      else if (CODE_EXT.includes(path.extname(e.name))) files.push(path.join(dir, e.name));
+    }
+  };
+  for (const r of roots) walkCode(path.resolve(r));
+  if (!files.length) return;
+
+  for (const [attr, d] of declared) {
+    const re = testidPattern(attr);
+    if (!re) {
+      infos.push(`T17/T18 BỎ QUA cho @trace.testid_attr = "${attr}" — không dựng được phép tìm ` +
+                 `xác định cho dạng này. So bừa thì báo oan, nên im lặng và nói ra.`);
+      continue;
+    }
+
+    const inCode = new Map();                 // id → file đầu tiên thấy
+    for (const f of files) {
+      const txt = fs.readFileSync(f, 'utf8');
+      for (const m of txt.matchAll(re)) {
+        const v = m[1] || m[2];
+        if (v && !inCode.has(v)) inCode.set(v, f);
+      }
+    }
+
+    // Code CHƯA có id nào của thuộc tính này → nhiều khả năng UI chưa viết, hoặc --code trỏ
+    // sai gốc. Phán "FE chưa gắn" lúc này là báo oan cả bảng.
+    if (!inCode.size) continue;
+
+    // ── T17 — bảng có, code không có ──
+    for (const [doc, ids] of d.byDoc) {
+      // Pattern id (`shop-tab-{code}`) coi là ĐÃ GẮN khi code có BẤT KỲ instance nào khớp nó.
+      const codeIds = [...inCode.keys()];
+      const missing = [...ids].filter(id => hasPlaceholder(id)
+        ? !((r => r && codeIds.some(c => r.test(c)))(patternToRegex(id)))
+        : !inCode.has(id));
+      if (!missing.length) continue;
+      const SHOW = 5;
+      warn('T17', rel(doc),
+           `${missing.length} test-id đã khai ở §4.5.6 mà KHÔNG tìm thấy trong code: ` +
+           missing.slice(0, SHOW).join(', ') + (missing.length > SHOW ? ` (+${missing.length - SHOW})` : ''),
+           `Thuộc tính đang tìm: ${attr} (theo @trace.testid_attr của doc này).\n` +
+           `        FE chưa gắn, gắn sai giá trị, hoặc element đã đổi lúc implement.\n` +
+           `        QC sẽ trượt locator ở đúng những id này. Sửa: /generate-code, hoặc\n` +
+           `        /map-testids {UC-ID} --from-code nếu element thật đã đổi.`);
+    }
+
+    // ── T18 — code có, bảng không có ──
+    const undeclared = [...inCode.keys()]
+      .filter(id => !matchesDeclaredIds(id, d.ids, d.patterns || new Set()));
+    if (undeclared.length) {
+      const SHOW = 5;
+      warn('T18', rel(path.dirname([...inCode.values()][0])),
+           `${undeclared.length} test-id nằm trong code mà KHÔNG có trong §4.5.6 nào: ` +
+           undeclared.slice(0, SHOW).join(', ') + (undeclared.length > SHOW ? ` (+${undeclared.length - SHOW})` : ''),
+           `Thuộc tính: ${attr}. Ai đó gắn id ngoài hợp đồng — thường là /generate-code chạy khi\n` +
+           `        §4.5.6 rỗng (id TẠM), hoặc sửa tay. Hợp đồng không còn đủ, và QC không biết\n` +
+           `        những id này tồn tại. Sửa: /map-testids {UC-ID} --from-code để đưa vào bảng.`);
+    }
+  }
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 let scanned = { books: 0, seams: 0, history: 0, files: 0 };
@@ -863,6 +1266,198 @@ for (const dir of TRACE_DIRS) {
 // phán khi chưa đọc hết sổ là phán trên dữ liệu thiếu.
 lintCodeVsLedger();
 
+// ── T19 — chân thứ tư: §4.5.6 vs *.Test.md ──────────────────────────────────
+//
+// Hợp đồng test-id có BỐN chân. T15/T16 canh bảng ↔ .feature · T17/T18 canh bảng ↔ code.
+// Chân thứ tư — bảng ↔ *.Test.md — là chân DUY NHẤT mà giá trị id bị CHÉP CỨNG vào một
+// artifact BỀN rồi nằm lại:
+//     generate-code   → bake vào code          → T17/T18 canh
+//     qc-run-test     → dựng locator LÚC CHẠY  → đọc bảng tươi, tự cứu
+//     qc-design-test  → chép vào .Test.md      → chân này
+//
+// VÌ SAO CẦN CẢ LỚP NÀY khi /qc-review và /qc-run-test ĐÃ có guard cho nó (G64):
+// rules/workflow.md — "Canh contract ≠ canh dữ liệu. Cần CẢ HAI". Guard ở trạm 4-5 phủ 100%
+// đường đi thật nhưng do LLM thực thi: nó không chặn được trước khi merge. T19 nông hơn nhưng
+// chạy trong CI. Hai lớp KHÔNG thay nhau — đúng cặp self-check ↔ lint-trace.
+//
+// MỘT CHIỀU. Chiều ngược (§4.5.6 có id mà không TC nào nhắc) KHÔNG kiểm: không phải element nào
+// cũng cần một bước TC, nên kiểm chiều đó là ỒN. Đúng bất đối xứng T17/T18 đã chọn.
+function lintTestidVsTestCases() {
+  if (!declared.size) return;                 // không có §4.5 client → NGOÀI PHẠM VI, im lặng
+
+  if (!QC_DIRS.length) {
+    infos.push(`T19 BỎ QUA — không có --qc nên chưa đối chiếu hợp đồng test-id với test-case. ` +
+               `Ca "TC bám id không còn trong §4.5.6" đang KHÔNG được kiểm ở tầng CI ` +
+               `(/qc-review và /qc-run-test vẫn bắt được, nhưng chỉ khi có người chạy chúng). ` +
+               `Truyền --qc {qc_dir} để bật.`);
+    return;
+  }
+  const roots = QC_DIRS.filter(d => fs.existsSync(path.resolve(d)));
+  if (!roots.length) {
+    infos.push(`T19 BỎ QUA — --qc trỏ tới thư mục không tồn tại: ${QC_DIRS.join(', ')}`);
+    return;
+  }
+
+  const files = [];
+  for (const r of roots) {
+    for (const f of walk(path.resolve(r))) {
+      if (/\.Test\.md$/.test(path.basename(f))) files.push(f);
+    }
+  }
+  if (!files.length) {
+    infos.push(`T19 BỎ QUA — không tìm thấy *.Test.md dưới --qc. ` +
+               `Trỏ nhầm đường mà im lặng thì đó là xanh giả.`);
+    return;
+  }
+
+  // Tập id đã khai, gộp mọi thuộc tính: TC nhắc id nào cũng phải có ở MỘT bảng nào đó.
+  // Gộp mọi thuộc tính: TC nhắc id nào cũng phải có ở MỘT bảng nào đó.
+  // Pattern id đi riêng — instance trong .Test.md (`uc1-z2-region`) phải khớp được
+  // `uc{n}-z2-region` ở bảng, nếu không T19 sẽ BÁO OAN chính id hợp lệ (G82 mặt 2).
+  const allDeclared = new Set();
+  const allPatterns = new Set();
+  for (const [, d] of declared) {
+    for (const id of d.ids) allDeclared.add(id);
+    for (const re of (d.patterns || [])) allPatterns.add(re);
+  }
+  if (!allDeclared.size && !allPatterns.size) return;
+
+  for (const f of files) {
+    const txt = fs.readFileSync(f, 'utf8');
+    // Chỉ nhận id trong backtick — đúng cách qc-design-test ghi ("click `ft001-login-submit-btn`").
+    // Quét chữ trần thì mọi từ gạch ngang trong câu văn đều thành ứng viên ⇒ báo oan.
+    const used = new Set();
+    for (const m of txt.matchAll(/`([a-z0-9][a-z0-9_.:-]*)`/gi)) {
+      const v = m[1];
+      // Chỉ xét token MANG DÁNG test-id (≥2 đoạn ngăn bằng `-`). Loại `--force`, `pass`, `UC1`…
+      if (/^[a-z0-9]+(-[a-z0-9]+){2,}$/i.test(v)) used.add(v);
+    }
+    const unknown = [...used].filter(id => !matchesDeclaredIds(id, allDeclared, allPatterns));
+    if (!unknown.length) continue;
+
+    const SHOW = 5;
+    warn('T19', rel(f),
+         `${unknown.length} test-id trong test-case KHÔNG có ở §4.5.6 nào: ` +
+         unknown.slice(0, SHOW).join(', ') + (unknown.length > SHOW ? ` (+${unknown.length - SHOW})` : ''),
+         'TC bám một id không còn trong hợp đồng ⇒ locator TRƯỢT lúc chạy, và test đỏ\n' +
+         '        "element not found" TRÔNG Y HỆT một bug sản phẩm — nên /qc-report phân loại\n' +
+         '        product-gap rồi in một /report-bug, và một lỗi hợp đồng NỘI BỘ đi ra khỏi\n' +
+         '        đội QC thành phiếu lỗi gửi PO.\n' +
+         '        Thường gặp: /map-testids đổi id mà .Test.md chưa chạy lại.\n' +
+         '        Sửa: /map-testids {UC-ID} (đưa vào hợp đồng) HOẶC /qc-design-test {UC-ID}.');
+  }
+}
+
+// T15/T16 độc lập với sổ trace — xem doc-comment của lintTestidContract().
+lintTestidContract();
+
+// ── G86 — nợ hợp đồng test-id: MỘT dòng có đếm, không 30 dòng rời ────────────
+if (testidLegacy.length) {
+  const SHOW = 3;
+  infos.push(`T16: ${testidLegacy.length} tech-doc chưa có \`@trace.testid_attr\` (doc LEGACY — ` +
+             `sinh trước khi field này vào template). QC sẽ fallback theo nền và TỰ CẢNH BÁO, nên ` +
+             `đây là NỢ CẦN THẤY, KHÔNG chặn. Chốt hợp đồng: /map-testids {UC-ID}. ` +
+             `Ví dụ: ${testidLegacy.slice(0, SHOW).join(' · ')}` +
+             (testidLegacy.length > SHOW ? ` (+${testidLegacy.length - SHOW})` : ''));
+}
+
+
+// ── G81 — ô Serves không đọc được PHẢI được đếm và in ra ─────────────────────
+//
+// Điều khoản cũ — "KHÔNG parse được token nào → BỎ QUA, không đoán" — đúng về KHÔNG ĐOÁN và sai
+// về KHÔNG NÓI. Nó chọn im lặng TUYỆT ĐỐI thay vì im lặng CÓ TIẾNG, nên 86/229 row đi qua mà báo
+// cáo vẫn nói "hợp đồng khớp". Đây là loại lỗi thứ tư mà T13 đặt tên: không phải "có cái sai",
+// mà là "KHÔNG BIẾT bảo vệ có bật hay không".
+if (servesUnparsed.length) {
+  const SHOW = 3;
+  const eg = servesUnparsed.slice(0, SHOW)
+    .map(u => `"${u.cell.slice(0, 48)}"`).join(' · ');
+  infos.push(`T15: ${servesUnparsed.length} ô "Serves SC" không đọc được dạng nào — CHƯA KIỂM ` +
+             `(không phải "sạch", là "không biết"). Ví dụ: ${eg}` +
+             (servesUnparsed.length > SHOW ? ` (+${servesUnparsed.length - SHOW})` : '') +
+             `. Dạng đọc được: "UC1 · SC1" · "UC1-SC1" · "UC3-SC5..SC11" · "UC6-SC4, SC5".`);
+}
+
+// ── T20 — mô tả "lấy X từ Y" phải TÌM ĐƯỢC ở artifact thật ──────────────────
+//
+// G85: `qc_artifact_stamp.fields.bdd_version` khai nguồn là "| **Version** | của header .feature".
+// KHÔNG THỂ ĐÚNG — .feature là Gherkin, header là khối comment `# @trace.*`, không có bảng Markdown.
+// Đo thật: 0/278 file có dạng cũ; 276/278 có `@trace.bdd_version`.
+//
+// Nó đi qua MỌI phép kiểm vì chưa ai ĐI LẤY THỬ. Kiểm chỉ dẫn CÓ MẶT ("khối §Stamp có được include
+// vào 5 lệnh không?" → ✅ 5/5) khác hẳn kiểm chỉ dẫn DÙNG ĐƯỢC. Rule này đóng khoảng đó.
+function lintStampProbes() {
+  const QS = schema.qc_artifact_stamp;
+  if (!QS || !QS.fields) return;
+
+  if (!fs.existsSync(SPECS_DIR)) {
+    infos.push(`T20 BỎ QUA — không có ${rel(SPECS_DIR)} nên chưa kiểm được mô tả nguồn của ` +
+               `qc_artifact_stamp.fields có TÌM ĐƯỢC ở artifact thật không. Truyền --specs để bật.`);
+    return;
+  }
+  const all = walk(SPECS_DIR);
+  // Phân loại artifact theo path/đuôi — đúng bố cục feature-package.
+  const pick = kind => all.filter(f => {
+    const b = path.basename(f), p = f.replace(/\\/g, '/');
+    if (kind === 'feature')      return /\.feature$/.test(b);
+    if (kind === 'tech-design')  return /-tech-design\.md$/.test(b);
+    if (kind === 'design-spec')  return /\/design-spec\//.test(p) && /\.md$/.test(b);
+    if (kind === 'prd') {
+      // PRD = file .md ở GỐC một feature-package: specs/{domain}/{prd-slug}/{TICKET-ID}-{slug}.md,
+      // và folder đó phải có `bdd/` bên cạnh. Lọc lỏng hơn (mọi .md ngoài design-spec/tech-docs)
+      // nuốt cả specs/domain-knowledge/* và BÁO OAN ngay lần chạy đầu — một rule báo oan là một
+      // rule bị tắt.
+      if (!/\.md$/.test(b)) return false;
+      if (/\/(design-spec|tech-docs|bdd|changelog)\//.test(p)) return false;
+      const folder = path.dirname(f);
+      const rel2 = path.relative(SPECS_DIR, folder).replace(/\\/g, '/');
+      if (rel2.split('/').length !== 2) return false;     // đúng {domain}/{prd-slug}
+      return fs.existsSync(path.join(folder, 'bdd'));
+    }
+    return false;
+  });
+
+  for (const [name, f] of Object.entries(QS.fields)) {
+    if (!f || !f.probe || !f.artifact) continue;      // R-rule canh phần khai; đây canh DỮ LIỆU
+    let re;
+    try { re = new RegExp(f.probe); } catch { continue; }
+    const files = pick(f.artifact);
+    if (!files.length) {
+      infos.push(`T20 BỎ QUA cho \`${name}\` — không tìm thấy artifact loại \`${f.artifact}\` ` +
+                 `dưới ${rel(SPECS_DIR)}. Không có mẫu thì không kết luận được.`);
+      continue;
+    }
+    const hit = files.filter(x => { try { return re.test(fs.readFileSync(x, 'utf8')); } catch { return false; } });
+    if (hit.length) continue;                          // tìm được ở ≥1 file → mô tả dùng được
+
+    // Field do MỘT LỆNH KHÁC điền sau → "0/N file có" nghĩa là lệnh đó CHƯA CHẠY, không phải mô tả
+    // sai. T20 không phân biệt được hai ca này từ dữ liệu; `filled_by` là chỗ khai ra sự khác biệt.
+    // Thiếu nó thì rule báo oan trên MỌI dự án chưa chạy lệnh đó — và một rule báo oan là rule bị tắt.
+    if (f.filled_by) {
+      infos.push(`T20 BỎ QUA cho \`${name}\` — 0/${files.length} file \`${f.artifact}\` có, nhưng ` +
+                 `trường này do \`/${f.filled_by}\` điền SAU. "Chưa có" ở đây nghĩa là lệnh đó chưa ` +
+                 `chạy, không phải mô tả nguồn sai.`);
+      continue;
+    }
+
+    warn('T20', `qc_artifact_stamp.fields.${name}`,
+         `mô tả nguồn KHÔNG tìm thấy ở artifact nào (0/${files.length} file \`${f.artifact}\`)`,
+         `probe: ${f.probe}\n` +
+         `        source: "${f.source || '—'}"\n` +
+         `        Một chỉ dẫn "lấy X từ Y" đi qua mọi phép kiểm khi chưa ai ĐI LẤY THỬ: kiểm chỉ dẫn\n` +
+         `        CÓ MẶT khác kiểm nó DÙNG ĐƯỢC. Agent làm theo sẽ không tìm ra, rồi bỏ trống hoặc\n` +
+         `        ĐOÁN — và stamp rỗng trông y hệt "artifact cũ chưa có stamp", nên điều khoản\n` +
+         `        backward_compat sẽ NUỐT LUÔN lỗi này.\n` +
+         `        Kiểm đúng ĐỊNH DẠNG file: .feature là Gherkin (comment # @trace.*), PRD và\n` +
+         `        design-spec là Markdown (bảng | **Version** |).`);
+  }
+}
+
+lintStampProbes();
+lintTestidVsTestCases();
+// T17/T18 SAU nó: cần `declared` mà nó vừa gom.
+lintTestidVsCode();
+
 // ── Report ────────────────────────────────────────────────────────────────────
 
 if (AS_JSON) {
@@ -880,9 +1475,11 @@ console.log('');
 
 if (!foundDirs.length) {
   console.log(`  ℹ️  Không tìm thấy trace dir nào (đã thử: ${TRACE_DIRS.join(', ')}).`);
-  console.log(`      Chưa có sổ trace thì chưa có gì để kiểm — chạy /generate-bdd để khởi tạo.`);
+  console.log(`      Bỏ qua T1–T14 (rule về sổ trace) — chạy /generate-bdd để khởi tạo.`);
   console.log('');
-  process.exit(0);
+  // T15/T16 KHÔNG cần sổ trace: chúng so tech-doc với .feature, và tech-doc có TRƯỚC sổ ở
+  // repo chỉ-spec. Thoát vô điều kiện ở đây là làm hai rule đó câm đúng nơi chúng có việc.
+  if (!errors.length && !warns.length && !infos.length) process.exit(0);
 }
 
 const show = (list, icon) => {