@educa-corp/sdd-framework 0.9.3 → 0.9.5

package/bin/build.js

@@ -56,6 +56,17 @@ const RUNTIME_READ = {
   'steps/report-footer.md':
     '**Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·\n' +
     'Output Artifacts · Next) cho report cuối, kèm khối bên dưới.',
+
+  // Vào đây ở B12: nó được 5 lệnh qc-* include, nên inline là nhân 5 bản của cùng một
+  // quy trình — đúng loại phình mà test "mức slim" tồn tại để canh (nó bắt được thật).
+  'steps/qc-scope.md':
+    '**BẮT BUỘC — đọc `.agent/steps/qc-scope.md` và thực thi TOÀN BỘ quy trình trong đó**,\n' +
+    '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' +
+    '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.',
 };
 
 /**

package/bin/lint-trace.js

@@ -807,6 +807,227 @@ 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);
+
+// 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();
+
+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) => {
+      const m = /^###\s+4\.5\b[^—]*—\s*([A-Za-z0-9_-]+)/.exec(l);
+      if (m && m[1] !== 'system') blocks.push({ platform: m[1], 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) {
+      err('T16', rel(doc),
+          'có block §4.5 (client) nhưng header thiếu @trace.testid_attr',
+          'Đây là TÊN THUỘC TÍNH chứa test-id (data-testid | data-test | ValueKey…).\n' +
+          '        Thiếu nó thì QC đoán theo nền — dự án dùng data-test sẽ TRƯỢT 100% locator,\n' +
+          '        và test đỏ "element not found" trông y hệt một bug sản phẩm.\n' +
+          '        Sửa: 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;
+    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 body = lines.slice(b.at, end === -1 ? lines.length : end);
+
+      body.forEach((line, k) => {
+        if (!line.trim().startsWith('|')) return;
+        if (/^\|[\s|:-]+\|$/.test(line.trim())) return; // dòng phân cách markdown |---|---|
+        if (hasPlaceholder(line)) return;               // dòng mẫu của template
+        const cells = line.split('|').map(s => s.trim());
+        const last  = cells[cells.length - 2] || '';   // cột "Phục vụ SC"
+
+        // Gom id đã khai (cột 1) cho T17/T18. 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.
+        const idCell = (cells[1] || '').replace(/`/g, '').trim();
+        // 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.
+        if (attrVal && /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/.test(idCell) && idCell !== 'Test-ID') {
+          if (!declared.has(attrVal)) declared.set(attrVal, { ids: new Set(), byDoc: new Map() });
+          const d = declared.get(attrVal);
+          d.ids.add(idCell);
+          if (!d.byDoc.has(doc)) d.byDoc.set(doc, new Set());
+          d.byDoc.get(doc).add(idCell);
+        }
+
+        if (!last) return;
+
+        // Hai dạng đã gặp: rút gọn "UC1 · SC1" và đầy đủ "FT-101-UC1-SC1".
+        // KHÔNG parse được token nào → BỎ QUA, không đoán. Biến thể định dạng phải thành
+        // "im lặng", không thành "báo oan" — đó là cách một rule mới mất niềm tin trong tuần đầu.
+        const ids = [
+          ...[...last.matchAll(/\bUC(\d+)\s*[·.]\s*SC(\d+)\b/g)].map(m => `${ticket}-UC${m[1]}-SC${m[2]}`),
+          ...[...last.matchAll(/\b([A-Za-z]+-\d+-UC\d+-SC\d+)\b/g)].map(m => m[1]),
+        ];
+        for (const id of ids) {
+          if (known.has(id)) continue;
+          err('T15', `${rel(doc)}:${b.at + 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 "Phục vụ 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) {
+      const missing = [...ids].filter(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 => !d.ids.has(id));
+    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 +1084,11 @@ 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();
 
+// T15/T16 độc lập với sổ trace — xem doc-comment của lintTestidContract().
+lintTestidContract();
+// T17/T18 SAU nó: cần `declared` mà nó vừa gom.
+lintTestidVsCode();
+
 // ── Report ────────────────────────────────────────────────────────────────────
 
 if (AS_JSON) {
@@ -880,9 +1106,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) => {

package/bin/qc-base-map.json

@@ -47,7 +47,7 @@
     {
       "upstream": "agents/4-qa-tc-designer.md",
       "targets": [],
-      "state": "undecided",
+      "state": "skipped",
       "why": "dinh nghia agent cua upstream; framework dung command + gate _agent_mode thay cho agent file"
     },
     {
@@ -329,58 +329,83 @@
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/functional/api.md"
+      ],
+      "state": "ported",
+      "base_sha": "211c18728baf029a7572f0ffb161e92a933fa8fb"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/flows/auth-sequence.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/auth-sequence.md"
+      ],
+      "state": "ported",
+      "base_sha": "69d60c12fe6d641638132581cce1dc6c955354a6"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/flows/common-flows.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: ban nhap cu, nam gon trong auth-sequence.md + crud-sequence.md (dai va chi tiet hon)."
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/flows/crud-sequence.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/crud-sequence.md"
+      ],
+      "state": "ported",
+      "base_sha": "65bf214d9f9beabe3c40b8697ba7c058adfd8bb5"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/references/common-headers.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/common-headers.md"
+      ],
+      "state": "ported",
+      "base_sha": "74f10a36bec7b40f4d9de2d0928798cb6fad0c2c"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/references/error-codes.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: ban nhap cu, nam gon trong http-status-codes.md (95 dong, day du hon). Phan header cua no nam trong common-headers.md. Lay ca hai la co hai bang tra cung mot thu roi chung lech nhau."
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/references/http-status-codes.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/http-status-codes.md"
+      ],
+      "state": "ported",
+      "base_sha": "a82baa99350f63955245764a6aa57c9dca6d055f"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/templates/auth-chain.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/auth-chain.md"
+      ],
+      "state": "ported",
+      "base_sha": "ef8f9761f1b53d0ccd752f8fe0c13a427fa15f45"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/templates/endpoint.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/endpoint.md"
+      ],
+      "state": "ported",
+      "base_sha": "7b38edd94e5efd37ff561f53cff92adedabaff7f"
     },
     {
       "upstream": "skills/qa-tc-designer/e2e-testcase-designer.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: tuong ung skills/qc/qa-designer/e2e/journey.md. Chua doi chieu noi dung — de danh cho lan ra tang E2E rieng."
     },
     {
       "upstream": "skills/qa-tc-designer/integration-testcase-designer.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: tuong ung 4 skill integration/{api,db,gui,kafka}.md. Chua doi chieu noi dung — de danh."
     },
     {
       "upstream": "skills/qa-tc-designer/manual-excel-testcase.md",
@@ -391,47 +416,70 @@
     {
       "upstream": "skills/qa-tc-designer/nfr-testcase-designer.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: tuong ung skills/qc/qa-designer/non-functional.md. Chua doi chieu noi dung — de danh."
     },
     {
       "upstream": "skills/qa-tc-designer/shared/action-keywords-glossary.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/action-keywords-glossary.md"
+      ],
+      "state": "ported",
+      "base_sha": "df56df91eea42342537ccf67b5946df32d98dbf4"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/duplicate-check-procedure.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/duplicate-check-procedure.md"
+      ],
+      "state": "ported",
+      "base_sha": "c59357a56b289bb9fb7fae8490db37109209cb3a"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/implicit-scenarios.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/implicit-scenarios.md"
+      ],
+      "state": "ported",
+      "base_sha": "6eb801a137ef4dfda97870c1eb36db62f3c782bc"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/precision-rules.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/precision-rules.md"
+      ],
+      "state": "ported",
+      "base_sha": "1c2005b55bd94c3e8fa25dfa12a29c8b23f7c01e"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/read-doc-gap-inputs.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/read-doc-gap-inputs.md"
+      ],
+      "state": "ported",
+      "base_sha": "a7e113b19f35aa47acf91e55cdfb3f630539806c"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/skill-decision-tree.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/skill-decision-tree.md"
+      ],
+      "state": "ported",
+      "base_sha": "57125f0c21512f2abcc55d00420e92c84c95fc8f"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/tc-metadata-format.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/tc-metadata-format.md"
+      ],
+      "state": "ported",
+      "base_sha": "a31d66a7a8dab19cf821c9102a88282b09e16cb9"
     },
     {
       "upstream": "skills/qa-tc-designer/ui-testcase-designer.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: framework tach tang UI thanh 3 skill rieng (functional/gui-screen · gui-feature · integration/gui) theo cay quyet dinh, thay vi mot file 341 dong. Ky thuat EP/BVA/Decision-Table/State-Transition da co trong 3 skill do; khuon TC + do chinh xac da tach ra shared/. Con lai la phan khai agent + orchestrator — framework khong co."
     },
     {
       "upstream": "skills/qa-tc-reviewer/api-test-reviewer.md",
@@ -440,23 +488,35 @@
     },
     {
       "upstream": "skills/qa-tc-reviewer/e2e-test-reviewer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/test-case/e2e.md"
+      ],
+      "state": "ported",
+      "base_sha": "276d0516f95421c726c8c55dc84c3c9244cf70e1"
     },
     {
       "upstream": "skills/qa-tc-reviewer/exploratory-test-reviewer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/test-case/exploratory.md"
+      ],
+      "state": "ported",
+      "base_sha": "4e068bb896739b977a6a5b1f638010d498c46aef"
     },
     {
       "upstream": "skills/qa-tc-reviewer/integration-test-reviewer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/test-case/integration.md"
+      ],
+      "state": "ported",
+      "base_sha": "639b54afb68df83b22168581c5c57b0f91d9cf6a"
     },
     {
       "upstream": "skills/qa-tc-reviewer/nfr-test-reviewer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/test-case/non-functional.md"
+      ],
+      "state": "ported",
+      "base_sha": "5747c7a6bdfaaea1ff3e958688b38b3aeaf9b15a"
     },
     {
       "upstream": "skills/qa-tc-reviewer/script-e2e-reviewer.md",
@@ -485,18 +545,28 @@
     },
     {
       "upstream": "skills/qa-tc-reviewer/shared/read-doc-gap-inputs.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/shared/read-doc-gap-inputs.md"
+      ],
+      "state": "ported",
+      "base_sha": "3caa1562399ef1167ac2dc620add2c6c729e55df"
     },
     {
       "upstream": "skills/qa-tc-reviewer/shared/review-file-template.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/shared/review-file-template.md"
+      ],
+      "state": "ported",
+      "base_sha": "bd596393ecc016cbea106835681a4979c0a9ca0e"
     },
     {
       "upstream": "skills/qa-tc-reviewer/ui-test-reviewer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/test-case/functional.md",
+        "skills/qc/qa-reviewer/shared/review-check-groups.md"
+      ],
+      "state": "ported",
+      "base_sha": "54f81eb6a132d3fb331f18ce0f1a7eb3a9cf19df"
     }
   ],
   "$decisions": {

package/bin/self-check.js

@@ -425,6 +425,30 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
       }
     }
 
+    // ── R8e — rule khai trong `testid_contract` phải được lint-trace PHÁT RA ──
+    //
+    // Cùng khuôn R14(d): khai một rule id trong schema mà checker không phát ra nó thì khối
+    // schema đó chỉ là chữ. Đây là nửa "máy canh" của luật "khai tường minh + để máy canh" —
+    // và hợp đồng test-id là chỗ luật đó bị thiếu lâu nhất (3 lệnh đọc, 2 lệnh ghi, 0 nơi kiểm).
+    {
+      const TC = schema.testid_contract;
+      if (TC && Array.isArray(TC.lint_rules)) {
+        const emits = new Set((lintText.match(/\b(?:err|warn)\('(T\d+)'/g) || [])
+          .map(m => /T\d+/.exec(m)[0]));
+        for (const r of TC.lint_rules) {
+          if (!r.why) {
+            err('R8', `\`testid_contract.lint_rules\` mục \`${r.rule}\` thiếu \`why\``,
+                'Một rule không nói được VÌ SAO sẽ bị người sau coi là tuỳ ý và gỡ đi.');
+          }
+          if (!emits.has(r.rule)) {
+            err('R8', `schema khai \`testid_contract\` rule \`${r.rule}\` mà ${LINT_REL} KHÔNG phát ra`,
+                'Khai rule rồi mà checker không có nó = hợp đồng test-id không được kiểm ở đâu cả,\n'
+              + '        trong khi bảng §4.5.6 có 3 lệnh đọc và 2 lệnh ghi.');
+          }
+        }
+      }
+    }
+
     // ── R8c — `n` phải là 1..N liền mạch, không trùng ──
     //
     // lint-trace dựng header bằng cách SORT theo `n` (thứ tự array KHÔNG phải thứ tự cột —
@@ -1198,6 +1222,12 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
 //     sau đều đoán. Đây đúng loại việc con người không làm đáng tin bằng sự cẩn thận.
 //     → R16(b).
 //
+// (3) Một file NHẬN nội dung port mà KHÔNG đóng dấu nguồn gốc. Bản đồ khai đầy đủ, sha
+//     đúng, self-check xanh — nhưng người mở file không biết đây là bản port, nên lần
+//     đồng bộ sau bản đồ biết BASE mà người sửa file thì không. Ca thật: B12 gộp nội dung
+//     `api-testcase-designer.md` vào `functional/api.md`. (b) và (e) đều mù vì chúng chỉ
+//     so KHI frontmatter có khai. → R16(f).
+//
 // (a) là cái quan trọng nhất về lâu dài: file upstream KHÔNG có entry trong bản đồ =
 // bị bỏ quên trong im lặng. `state: skipped` (có lý do) là câu trả lời hợp lệ; VẮNG MẶT
 // thì không. Cùng khuôn với `checkpoint_levels` và `strict_use_check`: khai tường minh
@@ -1324,6 +1354,30 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
           }
         }
       }
+
+      // ── (f) target `ported` phải KHAI dấu nguồn gốc, không chỉ "khai đúng nếu có khai" ──
+      //
+      // Vì sao cần nhánh riêng: (b) và (e) đều chạy trong `if (m)` / `if (mp)` — chúng so
+      // frontmatter với bản đồ KHI frontmatter có khai. File không khai gì thì cả hai im lặng.
+      // Ca thật (B12): `functional/api.md` nhận nội dung port từ `api-testcase-designer.md`,
+      // vào bản đồ đầy đủ với base_sha đúng, self-check XANH — mà đọc file thì không ai biết
+      // nó là bản port. Mất `upstream_path` + `upstream_sha` ở file đích là mất BASE của merge
+      // ba chiều lần sau: bản đồ biết, còn người sửa file thì không.
+      for (const e of entries.filter(x => x.state === 'ported')) {
+        for (const t of (e.targets || [])) {
+          const tp = path.join(ROOT, t);
+          if (!fs.existsSync(tp)) continue;            // đã báo ở (c)
+          const txt = fs.readFileSync(tp, 'utf8');
+          const lack = ['upstream_path', 'upstream_sha']
+            .filter(f => !new RegExp(`^${f}: .+$`, 'm').test(txt));
+          if (lack.length) {
+            err('R16', `${t} là target \`ported\` nhưng frontmatter THIẾU ${lack.join(' + ')}`,
+                `Bản đồ khai nó port từ \`${e.upstream}\`, còn chính file thì không đóng dấu.
+` +
+                '        Người mở file không biết đây là bản port, và lần đồng bộ sau mất một chiều BASE.');
+          }
+        }
+      }
     }
   }
 }