@educa-corp/sdd-framework 0.8.1 → 0.9.0

package/bin/lint-trace.js

@@ -27,6 +27,28 @@
  *   T8  trace-history*.jsonl: mỗi dòng một JSON object đủ key bắt buộc        → ERROR
  *   T9  mỗi sổ TSV có .feature đúng platform tồn tại (sổ mồ côi)             → WARN
  *   T10 sổ có luật merge (merge=union + text eol=lf) — hỏi `git check-attr`   → WARN
+ *   T14 code mang @trace.implements={SC} mà sổ ghi implemented_by trống       → WARN
+ *
+ * T14 là chiều NGƯỢC của mọi rule khác: T1–T13 chỉ mở SỔ. T14 mở KHO (code) rồi đối chiếu
+ * với sổ — chiều duy nhất bắt được ca "làm rồi mà không ghi sổ".
+ *
+ * Vì sao nó phải tồn tại (G60, 2026-08-26 — xem docs/update-framework-daily-logs.md):
+ * `implemented_by` có ĐÚNG MỘT producer (`/generate-code` §Write Trace State), và producer
+ * đó là bước CUỐI của lệnh dài nhất, nằm SAU cổng build — mà cổng build có đường thoát hợp
+ * lệ *"fail 3 lần → DỪNG, KHÔNG ghi trace"*. Nên "code có, sổ trống" là trạng thái tài liệu
+ * CÔNG NHẬN là tới được, và KHÔNG bước nào sau đó dọn nó.
+ *
+ * Ba lưới đều xanh, và đều đúng theo định nghĩa của chính nó: self-check R1 hỏi *"ai được
+ * phép ghi"* (có producer ⇒ xanh); file này trước T14 không có chìa khoá kho (chỉ nhận
+ * --trace/--specs, không đọc project-context.yaml); `/validate-traces` Step 2b CÓ vào kho và
+ * CÓ đọc đúng tag cần, nhưng chỉ hỏi một trong hai câu (*"tag trỏ vào SC có tồn tại không"*
+ * → TRACE_ORPHAN) rồi dừng. Đo thật trên một project: 910/1946 row `UNTRACKED` là ghi oan
+ * (47%) — lệch 28 điểm phủ code trên dashboard.
+ *
+ * WARN, KHÔNG phải ERROR — có chủ ý. `/validate-traces` Step 1.0 DỪNG cả lệnh khi lint exit
+ * 1. Biến nợ tồn thành error là ngày đầu bật lên cả team mất lệnh audit, rồi ai cũng gõ
+ * `--warn-only` mãi và mất luôn T1–T13 thật. Cùng lập luận đã dùng để giữ
+ * PRD_UNTRACKED_EDIT ngoài `gate.blocking`.
  *
  * T4 + T7 + T10 là cụm G40 (luật merge git): `merge=union` đổi *mất-row-im-lặng* thành
  * *trùng-row-bắt-được*, nên union KHÔNG được bật mà thiếu T4. T10 canh chính luật đó — đặt
@@ -36,8 +58,12 @@
  * bin/trace-schema.json. Thêm cột/vocabulary mới vào schema mà quên dạy file này →
  * self-check.js R8 fail build.
  *
- * Chạy: node bin/lint-trace.js [--trace DIR[,DIR]] [--specs DIR] [--warn-only] [--json]
+ * Chạy: node bin/lint-trace.js [--trace DIR[,DIR]] [--specs DIR] [--code DIR[,DIR]]
+ *                              [--warn-only] [--json]
  *       exit 1 nếu có ERROR (0 với --warn-only)
+ *
+ * --code là gốc mã nguồn để T14 quét. KHÔNG truyền → T14 bị bỏ qua, và file này IN RA MỘT
+ * DÒNG nói rõ là đã bỏ qua. Im lặng rồi báo "sạch" đúng là cách 910 row kia lọt qua.
  */
 
 const fs = require('fs');
@@ -69,6 +95,8 @@ const WARN_ONLY = argv.includes('--warn-only');
 const AS_JSON   = argv.includes('--json');
 const TRACE_DIRS = flag('--trace', '.trace').split(',').map(s => s.trim()).filter(Boolean);
 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);
 
 // ── Contract dẫn xuất từ schema ───────────────────────────────────────────────
 //
@@ -148,6 +176,11 @@ const infos  = [];
 const err  = (rule, where, msg, hint) => errors.push({ rule, where, msg, hint });
 const warn = (rule, where, msg, hint) => warns.push({ rule, where, msg, hint });
 
+// Sổ đã đọc, gom cho T14. Khoá là sc_id THUẦN (không kèm platform) vì tag trong code không
+// mang platform, và file này KHÔNG được đoán bố cục repo để suy ra. Mỗi entry giữ mọi nơi
+// sc_id đó xuất hiện, nên báo cáo nêu đúng từng sổ thay vì tuyên bố một platform không chắc.
+const ledger = new Map();   // sc_id → [{ at, filled }]
+
 // ── Đi cây thư mục ────────────────────────────────────────────────────────────
 
 function walk(dir, out = []) {
@@ -357,6 +390,11 @@ function lintBook(file) {
         } else {
           seen.set(id, n);
         }
+        // Gom cho T14 — chạy sau khi mọi dir đã quét xong.
+        const implIdx = header.indexOf('implemented_by');
+        const impl = implIdx === -1 ? '' : String(f[implIdx] || '').trim();
+        if (!ledger.has(id)) ledger.set(id, []);
+        ledger.get(id).push({ at, filled: !!impl && !isUnknown(impl) });
       }
     }
 
@@ -612,6 +650,119 @@ function lintOrphanBook(file, meta, traceRoot) {
   }
 }
 
+// ── T14 — kho (code) vs sổ: làm rồi mà không ghi sổ ──────────────────────────
+//
+// Chiều ngược của T1–T13. Xem doc-comment đầu file để biết vì sao lưới cũ không bắt được.
+
+const CODE_EXT = ['.java', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.dart', '.kt',
+                  '.kts', '.py', '.vue', '.swift', '.go', '.cs', '.php', '.rb'];
+const CODE_SKIP_DIR = new Set(['node_modules', '.git', 'build', 'dist', '.next', 'target',
+                               'out', '.dart_tool', 'coverage', '.gradle', '.idea', 'Pods',
+                               'vendor', '__pycache__', '.venv', '.agent', 'bin', 'obj']);
+
+/**
+ * Bung dạng viết tắt của tag: `FT-01-UC1-SC2,SC7,OTHER-UC3-SC1` → các cặp {uc, unit}.
+ * `SC7` trần thừa hưởng UC của token đầy đủ gần nhất bên trái — đúng quy ước
+ * /generate-code dùng khi một file phủ nhiều scenario của cùng một UC.
+ */
+function expandImplements(value) {
+  const out = [];
+  let lastUc = null;
+  for (let piece of String(value).split(/[,\s]+/)) {
+    piece = piece.trim().replace(/^\(+|\)+$/g, '');
+    if (!piece || piece.includes('@') || piece.includes('=')) continue;
+    let m = /^(.*?-UC\d+)-((?:SC|BR|AC)\d+)$/.exec(piece);
+    if (m) { lastUc = m[1]; out.push({ uc: m[1], unit: m[2] }); continue; }
+    m = /^((?:SC|BR|AC)\d+)$/.exec(piece);
+    if (m && lastUc) { out.push({ uc: lastUc, unit: m[1] }); continue; }
+    m = /^(.*?-UC\d+)$/.exec(piece);
+    if (m) { lastUc = m[1]; }
+  }
+  return out;
+}
+
+function lintCodeVsLedger() {
+  if (!CODE_DIRS.length) {
+    infos.push(`T14 BỎ QUA — không có --code nên chưa đối chiếu code với sổ. ` +
+               `Ca "code đã có tag mà sổ ghi implemented_by trống" đang KHÔNG được kiểm. ` +
+               `Truyền --code {gốc mã nguồn, ngăn bởi dấu phẩy} để bật.`);
+    return;
+  }
+  const roots = CODE_DIRS.filter(d => fs.existsSync(path.resolve(d)));
+  const gone = CODE_DIRS.filter(d => !fs.existsSync(path.resolve(d)));
+  if (gone.length) {
+    infos.push(`T14 — ${gone.length} gốc code không tồn tại, đã bỏ qua: ${gone.join(', ')}`);
+  }
+  if (!roots.length) {
+    infos.push(`T14 BỎ QUA — không gốc code nào trong --code tồn tại.`);
+    return;
+  }
+
+  // sc_id → Set(file) mà code khai là implement nó
+  const tagged = new Map();
+  let filesScanned = 0;
+
+  const walkCode = dir => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) {
+        if (CODE_SKIP_DIR.has(e.name)) continue;
+        walkCode(path.join(dir, e.name));
+        continue;
+      }
+      if (!CODE_EXT.includes(path.extname(e.name))) continue;
+      const p = path.join(dir, e.name);
+      let txt;
+      try { txt = fs.readFileSync(p, 'utf8'); } catch { continue; }
+      if (!txt.includes('@trace.implements')) continue;
+      filesScanned++;
+      // Một dòng comment có thể mang NHIỀU tag ngăn bởi `·` — cắt trước tag kế tiếp,
+      // không thì giá trị nuốt cả dòng và sinh sc_id rác.
+      for (const m of txt.matchAll(/@trace\.implements\s*[=:]?\s*([^\n\r*]*)/g)) {
+        let v = m[1];
+        const cut = v.indexOf('@trace.');
+        if (cut >= 0) v = v.slice(0, cut);
+        for (const { uc, unit } of expandImplements(v)) {
+          if (!unit.startsWith('SC')) continue;      // BR/AC là tag hợp lệ, không phải scenario
+          const id = `${uc}-${unit}`;
+          if (!tagged.has(id)) tagged.set(id, new Set());
+          tagged.get(id).add(rel(p));
+        }
+      }
+    }
+  };
+  for (const d of roots) walkCode(path.resolve(d));
+
+  // Đối chiếu: code khai có, mà MỌI nơi trong sổ đều ghi trống.
+  const behind = [];
+  for (const [id, files] of tagged) {
+    const rows = ledger.get(id);
+    if (!rows) continue;                       // không có row nào → TRACE_ORPHAN, việc của Step 2b
+    if (rows.some(r => r.filled)) continue;    // ít nhất một nơi đã ghi → không phán
+    behind.push({ id, files: [...files], rows: rows.map(r => r.at) });
+  }
+
+  infos.push(`T14 — đã quét ${filesScanned} file code mang @trace.implements ` +
+             `trong ${roots.length} gốc (${roots.join(', ')}).`);
+  if (!behind.length) return;
+
+  behind.sort((a, b) => a.id.localeCompare(b.id));
+  const SHOW = 15;
+  for (const b of behind.slice(0, SHOW)) {
+    warn('T14', b.rows.join(' · '),
+         `code khai implement "${b.id}" nhưng sổ ghi implemented_by trống`,
+         `Code: ${b.files.slice(0, 3).join(', ')}${b.files.length > 3 ? ` (+${b.files.length - 3})` : ''}\n` +
+         `        Hàng đã vào kho mà sổ chưa ghi ⇒ dòng này hiện UNTRACKED, dashboard đếm thiếu\n` +
+         `        và /generate-code sẽ coi là "chưa làm" rồi sinh lại.\n` +
+         `        Nguyên nhân thường gặp: /generate-code dừng ở cổng build nên §Write Trace State\n` +
+         `        chưa chạy. Sửa: /validate-traces --reconcile-code (điền từ tag, KHÔNG set status).`);
+  }
+  if (behind.length > SHOW) {
+    warn('T14', `(+${behind.length - SHOW} scenario nữa)`,
+         `tổng ${behind.length} scenario có code mà sổ chưa ghi — chỉ hiện ${SHOW} đầu`,
+         `Xem đủ danh sách: thêm --json. Dọn cả loạt: /validate-traces --reconcile-code`);
+  }
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 let scanned = { books: 0, seams: 0, history: 0, files: 0 };
@@ -664,6 +815,10 @@ for (const dir of TRACE_DIRS) {
   }
 }
 
+// T14 SAU vòng lặp mọi trace dir: ở chế độ umbrella một sc_id có thể nằm ở nhiều dir, nên
+// phán khi chưa đọc hết sổ là phán trên dữ liệu thiếu.
+lintCodeVsLedger();
+
 // ── Report ────────────────────────────────────────────────────────────────────
 
 if (AS_JSON) {

package/bin/self-check.js

@@ -61,7 +61,6 @@
 
 const fs = require('fs');
 const path = require('path');
-const crypto = require('crypto');   // R16(b) — băm file snapshot để đối chiếu base_sha
 
 const ROOT = path.join(__dirname, '..');
 const WARN_ONLY = process.argv.includes('--warn-only');
@@ -1183,151 +1182,6 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
   }
 }
 
-// ── R16 — snapshot upstream và framework không được trôi khỏi nhau trong im lặng ─
-//
-// Hai sự cố thật đã xảy ra trong lúc port bộ QC, và KHÔNG tầng nào bắt được:
-//
-// (1) 35 file skill QC bị xoá khỏi skills/. self-check ✅ · build ✅ 41/41 · .agent vẫn
-//     chạy được (mirror KHÔNG prune nên bản cũ còn nằm đó) — nhưng core/ thì rỗng, và
-//     bin/index.js prune sẽ CHỦ ĐỘNG xoá chúng ở project người dùng khi nâng cấp (đúng
-//     luật: có trong manifest + không còn ship + hash khớp). Ba tầng che nhau; hỏng chỉ
-//     lộ ở phía người dùng. → R16(d).
-//
-// (2) Một `upstream_sha` được GÕ BỪA vào frontmatter thay vì tính. Tự phát hiện, nhưng
-//     nếu lọt thì nó là BASE sai cho mọi lần merge ba chiều về sau — tức mọi lần đồng bộ
-//     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).
-//
-// (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
-// từng cái, rồi để máy canh — thay vì tin rằng ai đó sẽ nhớ.
-//
-// R16 tự bỏ qua nếu chưa có bin/qc-base-map.json (repo chưa port bộ QC) — không ép
-// mọi consumer phải có bản đồ này.
-{
-  const MAP_PATH  = path.join(ROOT, 'bin/qc-base-map.json');
-  const SNAP_DIR  = path.join(ROOT, 'upstream/qc-base');
-  const hasMap    = fs.existsSync(MAP_PATH);
-  const hasSnap   = fs.existsSync(SNAP_DIR);
-
-  // ── (d) lệnh qc-* trỏ vào skill nào thì skill đó phải tồn tại ────────────────
-  // Chạy ĐỘC LẬP với bản đồ: đây là lớp lỗi (1) ở trên, và nó không cần snapshot.
-  const SKILLS_QC = path.join(ROOT, 'skills/qc');
-  if (fs.existsSync(SKILLS_QC)) {
-    const cmdDir = path.join(ROOT, 'commands');
-    for (const f of fs.readdirSync(cmdDir).filter(n => /^qc-.*\.tmpl$/.test(n))) {
-      const txt = fs.readFileSync(path.join(cmdDir, f), 'utf8');
-      // `{paths.qc_skills_dir}/<đường dẫn>` — lấy phần sau dấu / đầu tiên
-      const refs = new Set();
-      for (const m of txt.matchAll(/\{paths\.qc_skills_dir\}\/([A-Za-z0-9._\/-]+)/g)) {
-        refs.add(m[1].replace(/[.,)`]+$/, ''));
-      }
-      for (const ref of refs) {
-        const abs = path.join(SKILLS_QC, ref);
-        if (!fs.existsSync(abs)) {
-          err('R16', `${f} trỏ vào \`{paths.qc_skills_dir}/${ref}\` — KHÔNG TỒN TẠI trong skills/qc/`,
-              'Lệnh vẫn chạy, vẫn ghi file, nhưng phân tích rỗng logic và KHÔNG cờ nào bật. ' +
-              'Khôi phục skill, hoặc sửa lệnh nếu đã cố ý bỏ.');
-        }
-      }
-    }
-  }
-
-  if (hasMap && hasSnap) {
-    let map;
-    try { map = JSON.parse(fs.readFileSync(MAP_PATH, 'utf8')); }
-    catch (e) { err('R16', `bin/qc-base-map.json không parse được: ${e.message}`); map = null; }
-
-    if (map) {
-      const entries = map.map || [];
-      const byUp = new Map(entries.map(e => [e.upstream, e]));
-
-      // liệt kê file snapshot thật
-      const walk = (dir, base = '') => {
-        let out = [];
-        for (const n of fs.readdirSync(dir)) {
-          const p = path.join(dir, n), rel = base ? `${base}/${n}` : n;
-          out = out.concat(fs.statSync(p).isDirectory() ? walk(p, rel) : [rel]);
-        }
-        return out;
-      };
-      const snap = walk(SNAP_DIR).sort();
-
-      // ── (a) mọi file snapshot phải có entry ───────────────────────────────────
-      const missing = snap.filter(r => !byUp.has(r));
-      if (missing.length) {
-        err('R16', `${missing.length} file trong upstream/qc-base/ KHÔNG có entry trong bin/qc-base-map.json`,
-            `Bị bỏ quên trong im lặng. Thêm entry với state \`skipped\` + \`why\` nếu cố ý không lấy.\n` +
-            `        ${missing.slice(0, 5).join('\n        ')}${missing.length > 5 ? `\n        … và ${missing.length - 5} file nữa` : ''}`);
-      }
-      const orphan = entries.filter(e => !snap.includes(e.upstream));
-      if (orphan.length) {
-        err('R16', `${orphan.length} entry trỏ vào file KHÔNG còn trong snapshot: ${orphan.map(e => e.upstream).join(', ')}`,
-            'Snapshot đã đổi mà bản đồ chưa theo — chạy lại bước dựng bản đồ.');
-      }
-
-      // ── (b) entry `ported` phải có base_sha, và base_sha phải KHỚP file thật ──
-      const sha1 = b => crypto.createHash('sha1').update(b).digest('hex');
-      for (const e of entries.filter(x => x.state === 'ported')) {
-        if (!e.base_sha) {
-          err('R16', `entry \`${e.upstream}\` là \`ported\` nhưng THIẾU base_sha`,
-              'Không có base thì merge ba chiều lần sau mất một chiều — mọi đồng bộ thành đoán.');
-          continue;
-        }
-        const abs = path.join(SNAP_DIR, e.upstream);
-        if (!fs.existsSync(abs)) continue;             // đã báo ở orphan
-        const real = sha1(fs.readFileSync(abs));
-        if (real !== e.base_sha) {
-          err('R16', `base_sha của \`${e.upstream}\` KHÔNG khớp file snapshot`,
-              `khai=${e.base_sha.slice(0, 12)}… thật=${real.slice(0, 12)}… — sha bịa, hoặc snapshot đã bị sửa tay sau khi port.`);
-        }
-        // frontmatter của file đích phải khai đúng cùng một sha VÀ cùng một upstream_path
-        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 m = /^upstream_sha: (.+)$/m.exec(txt);
-          if (m && m[1].trim() !== e.base_sha) {
-            err('R16', `${t} khai upstream_sha khác base_sha trong bản đồ`,
-                `file=${m[1].trim().slice(0, 12)}… map=${e.base_sha.slice(0, 12)}… — hai chỗ nói về cùng một sự thật mà lệch nhau.`);
-          }
-          // ── (e) upstream_path trong frontmatter phải trỏ vào file snapshot CÓ THẬT ──
-          //
-          // Vì sao cần nhánh riêng: (b) so sha, và sha vẫn khớp khi đường dẫn bị sửa sai —
-          // nên (b) mù với ca này. Ca thật (B9): một script đổi tên `DOC_GAPS.md → DOC_GAP.md`
-          // chạy quét cả frontmatter, sửa luôn `upstream_path` thành tên KHÔNG tồn tại ở
-          // upstream. self-check vẫn xanh; chỉ lộ ra khi kiểm tay. Mất `upstream_path` là mất
-          // nửa BASE của merge ba chiều — biết "sha nào" mà không biết "của file nào".
-          const mp = /^upstream_path: (.+)$/m.exec(txt);
-          if (mp) {
-            const declared = mp[1].trim();
-            if (declared !== e.upstream) {
-              err('R16', `${t} khai upstream_path "${declared}" ≠ bản đồ "${e.upstream}"`,
-                  'Hai chỗ cùng khai một sự thật mà lệch nhau — sửa cho khớp.');
-            }
-            if (!fs.existsSync(path.join(SNAP_DIR, declared))) {
-              err('R16', `${t} khai upstream_path "${declared}" — KHÔNG TỒN TẠI trong snapshot`,
-                  'Đường dẫn bị sửa sai (vd một lần đổi tên hàng loạt quét cả frontmatter), ' +
-                  'hoặc upstream đã đổi tên. sha có thể vẫn khớp nên nhánh (b) không bắt được.');
-            }
-          }
-        }
-      }
-
-      // ── (c) mọi target của entry `ported` phải tồn tại ────────────────────────
-      for (const e of entries.filter(x => x.state === 'ported')) {
-        for (const t of (e.targets || [])) {
-          if (!fs.existsSync(path.join(ROOT, t))) {
-            err('R16', `entry \`${e.upstream}\` là \`ported\` nhưng target \`${t}\` không tồn tại`,
-                'Bản đồ lỗi thời sau khi đổi tên/xoá file đích.');
-          }
-        }
-      }
-    }
-  }
-}
-
 // ── report ────────────────────────────────────────────────────────────────────
 const tagCount = schema.tags.length;
 const colCount = schema.tsv_columns.length;

package/bin/trace-schema.json

@@ -695,7 +695,8 @@
       "n": 4,
       "name": "gen_ver",
       "written_by": [
-        "generate-code"
+        "generate-code",
+        "validate-traces"
       ],
       "read_by": [
         "validate-traces",
@@ -706,7 +707,8 @@
       "n": 5,
       "name": "implemented_by",
       "written_by": [
-        "generate-code"
+        "generate-code",
+        "validate-traces"
       ],
       "read_by": [
         "validate-traces",
@@ -910,7 +912,8 @@
       "name": "fe_phase",
       "written_by": [
         "generate-code",
-        "generate-bdd"
+        "generate-bdd",
+        "validate-traces"
       ],
       "read_by": [
         "validate-traces"
@@ -1211,6 +1214,7 @@
         "DESIGNSPEC_DRIFT",
         "DESIGNSPEC_STALE_VS_BDD",
         "TRACE_ORPHAN",
+        "LEDGER_BEHIND_CODE",
         "SEAM_UNWIRED",
         "STUB_UNRESOLVED",
         "SEAM_PENDING",

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.8.1
+0.9.0

package/core/commands/generate-code.md

@@ -736,6 +736,7 @@ Dựng mock từ `mock_source` đã phân giải ở Phase Detection — **shape
 - [ ] **Add-only cho file EXTEND:** đọc lại file trên disk; mọi member + `@trace.implements` cũ (gồm UC khác) còn nguyên; Guard sau-ghi đã chạy, không mất member nào
 - [ ] **Seam/Stub ledger:** không tạo giả lập khi hàng thật đã tồn tại (đã nối/lấp thẳng); mọi seam mới có `@trace.seam_pending` + dòng `kind=seam PENDING`; mọi method trắng có `@trace.stub`/`@trace.stub_owner`/`@trace.stub_for` + dòng `kind=stub PENDING` trong `_seams.tsv`; nếu UC này là chủ nợ (seam) → đã set `READY` + in cảnh báo
 - [ ] **Fill-before-create:** trước khi tạo method mới đã quét sổ + `@trace.stub` — có stub khớp thì **lấp tại chỗ** (giữ chữ ký, gỡ `@trace.stub*` → `@trace.implements`, sổ `RESOLVED`); KHÔNG còn method song song cùng trách nhiệm
+- [ ] **Ghi sổ xong và đã KIỂM LẠI:** §Write Trace State đã chạy, và Guard sau-ghi cho sổ xác nhận mọi `sc_id` vừa implement có `gen_ver` + `implemented_by` ≠ `—`. Footer có dòng `📓 Sổ trace: đã ghi {n}/{m}`. *(Bước này ở cuối lệnh nên dễ rơi nhất — rơi là dashboard đếm thiếu vĩnh viễn, xem G60.)*
 
 ## Build Verify
 ```bash
@@ -749,8 +750,20 @@ Dựng mock từ `mock_source` đã phân giải ở Phase Detection — **shape
 >   ❌ Build FAIL sau 3 lần thử — không ghi trace, không commit.
 >      Lỗi cuối: {tóm tắt}
 >      File đã sinh giữ nguyên trên working tree để bạn sửa tay hoặc chạy /debug.
+>
+>      ⚠️  Code đã có tag @trace.implements nhưng SỔ CHƯA GHI. Nếu bạn sửa tay cho build
+>          pass rồi commit mà KHÔNG chạy lại lệnh này, sổ sẽ đứng ở "chưa có code" vĩnh
+>          viễn — không lệnh nào tự dọn. Hai đường ra:
+>            · chạy lại /generate-code {UC-ID} --force  (ghi sổ đúng đường chính thức), hoặc
+>            · /validate-traces --reconcile-code        (điền sổ từ tag, KHÔNG set status)
 >   ```
 >   Đặt Status badge = ❌ ở report cuối và dừng (bỏ qua Write Trace / Refresh Panel / Commit).
+>
+> **Vì sao đường thoát này phải chỉ cửa ra (G60):** trạng thái nó để lại — *code có tag, sổ
+> trống* — là trạng thái **duy nhất** trong framework mà không bước nào sau đó sửa. Đo trên một
+> project thật: 504 scenario ở đúng trạng thái này, làm dashboard đếm thiếu 28 điểm phủ code.
+> Một ngõ cụt được tài liệu hoá mà không chỉ cửa ra thì người dùng sẽ tự chọn cửa sai (bôi xanh
+> sổ bằng tay, kể cả những scenario chưa có test).
 
 ## Write Trace State
 
@@ -794,6 +807,35 @@ Bất kể trường hợp nào, in khối này ở report cuối để dev khô
       số cũ mới là số sai. (Tỷ lệ phủ code/test không đổi — test_count giữ nguyên.)
 ```
 
+### Guard sau-ghi cho SỔ *(bắt buộc — không có nó thì bước này bỏ qua được trong im lặng)*
+
+*Lệnh này **đã** có Guard sau-ghi cho **file code** (§File Scan: đọc lại, đối chiếu, mất member thì
+khôi phục). Sổ thì chưa có — mà sổ mới là thứ dashboard và cổng PR đọc.*
+
+Ngay sau khi ghi TSV, **đọc lại file trên disk** và kiểm đúng một điều: **mọi `sc_id` vừa implement
+trong lần chạy này đều có `gen_ver` ≠ `—` VÀ `implemented_by` ≠ `—`.**
+
+| Kết quả | Hành động |
+|---|---|
+| Đủ hết | tiếp Refresh Panel / Commit. In dòng tổng ở footer (dưới). |
+| **Thiếu bất kỳ row nào** | **DỪNG. Đặt Status badge = ❌.** KHÔNG commit, KHÔNG báo "xong". In: `❌ Ghi sổ THẤT BẠI — {n}/{m} scenario chưa có gen_ver/implemented_by: {danh sách sc_id}. Code đã sinh nhưng sổ chưa ghi; chạy lại /generate-code {UC-ID} --force, hoặc /validate-traces --reconcile-code.` |
+| Không tìm thấy file TSV | **DỪNG** cùng cách — sổ phải tồn tại từ `/generate-bdd`; không có nghĩa là chạy sai UC/platform, đừng tạo sổ mới ở đây. |
+
+**In ở footer report, mọi lần chạy, kể cả khi đủ:**
+```
+📓 Sổ trace: đã ghi {n}/{m} scenario vào {UC-ID}-{platform}.tsv
+```
+
+> **Vì sao một dòng đếm lại quan trọng (G60):** ghi sổ là **động tác cuối** của lệnh dài nhất trong
+> bộ, nằm **sau** cổng build. Khi nó bị rơi, mọi thứ khác vẫn xanh: code có, build pass, commit
+> xong, report báo ✅ — và **không có dòng nào trong transcript nói rằng sổ chưa được ghi**. Ba tuần
+> sau dashboard hiện thiếu, không ai truy được lượt chạy nào. Đo trên một project thật: **504
+> scenario** ở đúng trạng thái đó, và người phát hiện là một dev thấy dashboard nói "chưa có code"
+> trong khi tự mình mở code ra thì tag đủ cả.
+>
+> Đây cũng là lý do guard này **phải chặn** (khác T14 ở `lint-trace`, cố ý chỉ WARN): ở đây không có
+> nợ tồn nào để sợ — ta đang nói về **đúng lượt chạy vừa rồi**, và nó vừa thất bại thật.
+
 ## Refresh Panel Mirror
 # Làm mới panel mirror của Living Docs *(local)*
 

package/core/commands/propose-scenario.md

@@ -1,7 +1,7 @@
 # /propose-scenario — Đề xuất một BDD Scenario mới (cho Tester & QC)
 
 Dành cho **tester và QC** phát hiện edge case chưa được BDD hiện tại phủ (vd một gap missing-coverage
-`DOC_GAP` từ `/qc-analyze`). Draft một Gherkin scenario vào **khu proposal** để
+`DOC_GAPS` từ `/qc-analyze`). Draft một Gherkin scenario vào **khu proposal** để
 PO/Dev review và promote.
 
 **KHÔNG sửa file `.feature` canonical.** BDD do PO/Dev sở hữu — lệnh này chỉ ghi