@educa-corp/sdd-framework 0.8.0 → 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/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.0
+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/validate-traces.md

@@ -256,11 +256,26 @@ Kiểm tra mảng `services` có tồn tại trong `project-context.yaml` không
 Chạy checker xác định trên mọi trace dir đã phân giải ở Step 0:
 
 ```bash
-npx @educa-corp/sdd-framework --lint-trace --trace {all_trace_dirs, ngăn cách bởi dấu phẩy} --specs {paths.specs_dir}
+npx @educa-corp/sdd-framework --lint-trace --trace {all_trace_dirs, ngăn cách bởi dấu phẩy} --specs {paths.specs_dir} --code {code_roots, ngăn cách bởi dấu phẩy}
 ```
 
+**Dựng `code_roots` — bắt buộc truyền, đây là chìa khoá kho của T14:**
+
+| Chế độ | `code_roots` |
+|---|---|
+| **Umbrella** (có `services:`) | tập **duy nhất** mọi giá trị `path` xuất hiện trong `services:` — gồm cả `path` lồng trong `by_prd_slug`. Bỏ trùng (nhiều domain trỏ chung một submodule là chuyện thường). |
+| **Single-service** | `{paths.src_dir}` |
+| Không phân giải được cái nào | **truyền rỗng** — T14 tự bỏ qua và tự in một dòng nói rõ đã bỏ qua. **Đừng đoán** một thư mục nào đó: quét sai chỗ còn tệ hơn không quét. |
+
 *`bin/` sống trong package npm, không được cài vào project — nên `npx` là đường duy nhất. Không có mạng / npx fail → **bỏ qua step này**, in `⚠️ Chưa lint được sổ trace (npx không khả dụng) — kết quả dưới đây chưa được kiểm cấu trúc` vào report, rồi tiếp Step 1. Đừng để nó chặn cả lệnh.*
 
+> **Vì sao `--code` (G60).** Trước nó, checker xác định duy nhất mở file thật của dự án chỉ nhận
+> `--trace` và `--specs` — nó **không thể thấy code**, nên ca *"code đã có tag mà sổ ghi
+> `implemented_by` trống"* không có một mắt xác định nào canh. T14 là chiều ngược đó, ở mức
+> **WARN**: nó **không được** chặn lệnh này, vì 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.
+> Cờ `LEDGER_BEHIND_CODE` ở Step 2b là bản LLM của cùng phép kiểm; `--reconcile-code` là đường ra.
+
 **Exit 0 → tiếp Step 1.**
 
 **Exit 1 → DỪNG NGAY.** Đừng nạp, đừng tính `status`, đừng ghi lại gì:
@@ -334,9 +349,23 @@ Với mỗi row có `service` ∈ (`unrouted`, `unresolved`), tra lại `service
 > `unrouted` → path. Không sửa tay, không sinh lại BDD. Không có bước này thì `unrouted` **đọng lại
 > vĩnh viễn** — đúng bệnh `TBD` mà G1/G28 đã chỉ ra.
 
-### Step 2b — Reverse audit (bắt tag mồ côi)
+### Step 2b — Reverse audit (hai câu hỏi trên cùng một lượt quét)
+
+*Step 2 đi chiều **spec → code** (mỗi row TSV, SC đó implement tới đâu). Step này đi **chiều ngược** — bắt lớp lỗi mà Step 2 cấu trúc không thể thấy.*
 
-*Step 2 đi chiều **spec → code** (mỗi row TSV, SC đó implement tới đâu). Step này đi **chiều ngược** — bắt lớp lỗi mà Step 2 cấu trúc không thể thấy: code trỏ vào một scenario **không còn tồn tại**. Xảy ra khi gen lại BDD làm một SC biến mất (gộp / đổi số / xoá) trong khi code implement nó vẫn nằm đó, vẫn được caller gọi.*
+**Một lượt quét, HAI câu hỏi.** Đừng dừng ở câu đầu:
+
+| | Câu hỏi | Bắt được gì |
+|---|---|---|
+| **A** | *"Tag này trỏ vào SC có tồn tại không?"* | code trỏ vào scenario **đã bị xoá** → `ORPHANED` / `TRACE_ORPHAN` |
+| **B** | *"Sổ có biết SC này đã có code chưa?"* | code đã làm mà **sổ chưa ghi** → `LEDGER_BEHIND_CODE` |
+
+> **Vì sao câu B phải nằm ở đây, và vì sao nó từng thiếu (G60).** Bản trước chỉ có câu A. Câu B dùng
+> **đúng dữ liệu đã nạp trong bộ nhớ** — không phát sinh thêm một lần I/O nào — nên bỏ nó là bỏ
+> không vì lý do gì. Và không có nó thì lớp lỗi *"làm rồi mà không ghi sổ"* **không có một mắt nào
+> canh**: `self-check` R1 hỏi *"ai được phép ghi"* (`implemented_by` có producer ⇒ xanh), còn
+> `lint-trace` trước T14 thì không thấy được code. Đo trên một project thật: **504 scenario** có code
+> mà sổ ghi trống, làm dashboard đếm thiếu **28 điểm** phủ code.
 
 **Quét (gộp vào cùng lượt quét code của Step 5b — không thêm pass mới):** dưới `{code_base_package}` (CLAUDE.md §2) + `{paths.src_dir}`, thu mọi `@trace.implements={UC-ID}-SC{N}`; trong thư mục test thu mọi `@trace.verifies={UC-ID}-SC{N}`.
 
@@ -352,6 +381,24 @@ Với mỗi tag, hỏi: `SC{N}` đó có tồn tại trong `.feature` của đú
 
 Không tìm thấy tag mồ côi nào → bỏ qua im lặng.
 
+#### Câu B — sổ có theo kịp code chưa?
+
+Với mỗi `@trace.implements={UC-ID}-SC{N}` mà `SC{N}` **có** trong `.feature` (tức đã qua câu A):
+
+| Điều kiện | Cờ | Ý nghĩa |
+|---|---|---|
+| Row TSV tồn tại **và** `implemented_by != —` | *(sạch)* | Sổ khớp kho |
+| Row TSV tồn tại **nhưng** `implemented_by == —` | `LEDGER_BEHIND_CODE` 🟠 | **Làm rồi mà không ghi sổ.** Row đang hiện `UNTRACKED`, dashboard đếm thiếu, và `/generate-code` sẽ coi là "chưa làm" rồi sinh lại |
+| Không có row TSV nào | — | Step 2 đã thêm row `UNTRACKED` từ `.feature`; lượt sau sẽ vào hàng trên |
+
+**Ghi lại cho mỗi cờ:** `sc_id` · `platform` (từ tên file sổ) · danh sách file code mang tag · và **`has_verifies`** = có `@trace.verifies` cho đúng SC đó hay không. Field cuối là thứ quyết định `--reconcile-code` điền row đó thành *có test* hay *chưa test* — thu ngay ở đây vì lượt quét này đã đọc cả hai loại tag.
+
+**Nguyên nhân thường gặp, nêu luôn trong report** để người đọc không phải đoán: `/generate-code` dừng ở cổng build nên §Write Trace State chưa chạy; hoặc dev sửa tay cho build pass rồi commit mà không chạy lại lệnh.
+
+**Cờ này 🟠 KHÔNG chặn PR** — xem lý do ở Step 7 (`ledger_behind_code_count`). Đường ra là `--reconcile-code` (Step 5f).
+
+Không tìm thấy row nào lệch → bỏ qua im lặng.
+
 ### Step 3 — Tính `status` theo từng scenario
 
 Áp dụng quy tắc theo thứ tự ưu tiên (first-match-wins):
@@ -562,6 +609,66 @@ Parse `$ARGUMENTS`:
 
 Không đụng `dev_selftest`/`qc_status` (luật G28 không áp: **không có logic nào đổi** — đó chính là tiền đề của realign).
 
+### Step 5f — Reconcile code mode *(chỉ chạy khi có `--reconcile-code`)*
+
+*Đường ra cho cờ `LEDGER_BEHIND_CODE` (Step 2b câu B). Không có nó thì cờ đó **không bao giờ sạch được**: `implemented_by` chỉ `/generate-code` ghi, mà nó thấy row đã có code là skip — nên lối ra duy nhất là ép sinh lại code cho hàng loạt scenario đã làm xong. Đúng vòng lặp đóng mà `--realign` được viết ra để mở, chỉ ở một cột khác.*
+
+`--reconcile-code` (không tham số → mọi row `LEDGER_BEHIND_CODE` **trong scope** của Step 0-A; dùng `--domain`/`--prd`/`--uc` để hẹp lại).
+
+**Điền từ bằng chứng — 5 cột, không hơn:**
+
+| Cột | Lấy từ đâu |
+|---|---|
+| `implemented_by` | tên class/hàm mang `@trace.implements` cho SC đó (nhiều file → nối bằng `,`, đúng khuôn `/generate-code` đang ghi) |
+| `gen_ver` | copy `spec_ver` của **chính row đó** *(không phải version hiện tại của `.feature` — code sinh ra từ bản nào thì `spec_ver` lúc này là bản đó; Step 2 vừa đồng bộ nó)* |
+| `fe_phase` | `integration` nếu file code có wire adapter thật theo §4.5.4 · `ui` nếu chỉ có mock · `—` cho `system`. **Không suy được** → để `—`, đừng đoán |
+| `test_count` · `test_classes` | **CHỈ khi `has_verifies` = true** (Step 2b đã thu). Số test + tên class lấy từ file mang `@trace.verifies`. `has_verifies` = false → **để trống**, tuyệt đối không điền 0-giả hay tên class phỏng đoán |
+
+> ### ⚠️ Luật cứng: KHÔNG set `status`
+>
+> Điền xong 5 cột rồi **để Step 3 tự tính** `status`. Đây không phải chi tiết kỹ thuật — nó là điều
+> quyết định lệnh này hữu ích hay có hại.
+>
+> Có **hai loại bằng chứng, hai người ghi**: `@trace.implements` = *"đã làm"* (do `/generate-code`) ·
+> `@trace.verifies` = *"đã kiểm"* (do `/dev-gen-test`). **Không được suy cái này ra cái kia.**
+>
+> Đo trên một project thật: trong 910 row lệch, **446 có cả hai** ⇒ Step 3 tính ra `OK`; **464 chỉ
+> có cái thứ nhất** ⇒ Step 3 tính ra `GAP`, tức **lộ ra 464 chỗ thiếu test** đang bị chữ `UNTRACKED`
+> che. Nếu lệnh này tự viết `status = OK` thì 464 scenario chưa ai kiểm lên dashboard thành xong hết,
+> và **cổng chặn PR — thứ tồn tại để bắt đúng loại lỗi này — mở cửa cho hàng chưa kiểm.**
+>
+> `/generate-code` đã phát biểu cùng luật này cho chính nó: *"`status` được tính bởi
+> `/validate-traces` — không set ở đây."* Lệnh ghi bù cũng không được là ngoại lệ.
+
+**Ba rào an toàn — bắt buộc, cùng khuôn Step 5e:**
+
+1. **Chỉ chạm row đang `LEDGER_BEHIND_CODE`.** Từ chối mọi row khác. Row `DRIFT`/`ORPHANED`/`GAP`/`OK` đã có `implemented_by` — ghi lên đó là ghi đè việc của `/generate-code`, không phải ghi bù. In:
+   ```
+   ❌ Từ chối reconcile {sc_id}: row này đang {status}, không phải LEDGER_BEHIND_CODE.
+      --reconcile-code chỉ điền vào row TRỐNG mà code đã có tag. Row này có chuyện khác.
+   ```
+2. **Chỉ ghi 5 cột trên.** **Guard sau-ghi:** đọc lại TSV, diff với bản trước; có bất kỳ ô nào **khác** ngoài 5 cột đã định (kể cả `status`, `last_updated` của row không thuộc phạm vi) → **khôi phục file** và dừng.
+3. **In chính xác từng file + từng row đã sửa**, kèm cột nào điền giá trị gì và **bằng chứng nào**:
+   ```
+   📓 Đã ghi bù {n} row:
+      {UC-ID}-{platform}.tsv:{dòng}  {sc_id}
+        implemented_by ← {ClassName.method}      (từ {file}:{dòng})
+        gen_ver        ← {spec_ver}
+        fe_phase       ← {ui | integration | —}
+        test_count     ← {n} · test_classes ← {…}   (từ @trace.verifies ở {file})   [hoặc: bỏ trống — không có @trace.verifies]
+   ```
+   Ghi bù im lặng là ghi bù không kiểm chứng được.
+
+**Không đụng** `dev_selftest`/`qc_status`/`qc_owner`/`qc_blocked_by`: luật G28 không áp vì **không có logic nào đổi** — code đã nằm đó từ trước, ta chỉ ghi lại sự thật vào sổ. Hạ tín hiệu nghiệm thu ở đây là trừng phạt một lượt dọn dẹp.
+
+**Sau khi ghi, chạy tiếp Step 3 → Step 6 → Step 7 như thường** để `status` được tính lại và aggregate phản ánh số mới. In cảnh báo ở report:
+```
+ℓ Coverage sẽ NHẢY sau lượt này — code {cũ}% → {mới}%, test {cũ}% → {mới}%.
+  Đây KHÔNG phải việc mới làm được: là việc đã làm rồi mà sổ chưa ghi. Và {n} row
+  chuyển sang GAP là {n} chỗ thiếu test vừa lộ ra — phần "xấu đi" trên giấy chính
+  là phần trước đó đang bị che.
+```
+
 ### Step 5c — BDD version drift check
 
 *Đối xứng với Step 4 (PRD drift). Trước đây tầng BDD là tầng DUY NHẤT không có cờ drift — dù `/generate-code` vẫn ghi `@trace.bdd_version` vào code và JSON report vẫn lưu nó. Dữ liệu có, chỉ thiếu phép so.*
@@ -692,6 +799,18 @@ fe_integrated    = rows where fe_phase == integrated  # FE đã wire adapter th
 # công việc CHƯA XONG dù status có thể đã là OK (có code + có test trên mock).
 orphaned_count   = rows where status == ORPHANED     # code còn, scenario đã bị xoá khỏi .feature (Step 2b/Rule 0)
 trace_orphan_count = số tag @trace.implements/@trace.verifies trỏ vào SC không tồn tại VÀ không có row TSV (Step 2b)
+ledger_behind_code_count = số row có @trace.implements trong code mà cột implemented_by còn trống
+                   (Step 2b câu B). 🟠 — "làm rồi mà không ghi sổ". Sạch bằng --reconcile-code.
+                   # KHÔNG vào gate.blocking, và đây là quyết định có chủ ý — đừng "sửa":
+                   #   (1) gate.blocking nghĩa hẹp là CODE ĐANG HỎNG. Ở đây code hoàn toàn đúng
+                   #       và đang chạy; chỉ có sổ nói sai về nó. Cùng ranh giới mà R9(e) giữ.
+                   #   (2) Nợ tồn khi mới bật: mọi project đang chạy đều đã có sẵn hàng trăm row
+                   #       loại này (đo thật: 504 scenario / 910 row ở một project) ⇒ cờ chặn mới
+                   #       sẽ đỏ khắp nơi ở lần đầu ⇒ người ta tắt cổng ⇒ mất luôn 4 cờ 🔴 thật.
+                   #   (3) Nhưng nó vẫn PHẢI thấy được: in mỗi lần chạy + counter ở summary, và
+                   #       bản xác định của cùng phép kiểm là lint-trace T14 (cũng WARN).
+                   # Team nào đã dọn sạch nợ tồn thì tự thêm counter này vào gate.blocking kèm
+                   # `why` — self-check R13(e) canh việc đó.
 prd_untracked_edit_count = số file PRD có nội dung đổi kể từ `sha_at_audit` mà `Version` KHÔNG đổi
                    (Step 3.9). 🔴 — có người sửa ngoài đường chính thức, nên MỌI phán đoán version
                    của Step 4/5 trên file đó đang dựa vào một nhãn không còn đúng.
@@ -797,6 +916,7 @@ Schema:
     "fe_integrated": 0,
     "orphaned_count": 0,
     "trace_orphan_count": 0,
+    "ledger_behind_code_count": 0,
     "prd_untracked_edit_count": 0,
     "prd_drift_count": 0,
     "prd_stale_ref_count": 0,
@@ -1007,6 +1127,16 @@ Schema:
         "fix": "sửa sc_id cho đúng SC hiện có, HOẶC xoá code/test nếu không còn cần"
       }
     ],
+    "ledger_behind_code": [
+      {
+        "sc_id": "<SC-ID>",
+        "platform": "web | app | system | webview | …",
+        "files": ["<file code mang @trace.implements cho SC này>"],
+        "has_verifies": false,
+        "would_become": "OK | GAP",
+        "fix": "/validate-traces --reconcile-code   (điền implemented_by/gen_ver/fe_phase từ tag; test_count CHỈ khi có @trace.verifies; KHÔNG set status)"
+      }
+    ],
     "techdoc_drift": [
       {
         "uc_id": "<UC-ID>",
@@ -1242,6 +1372,23 @@ Trace orphan (tag trỏ vào SC không tồn tại, KHÔNG có row .tsv nào):
     (Không lệnh nào khác bắt được cái này — row .tsv đã bị xoá bởi version cũ,
      hoặc tag ghi sai id ngay từ đầu.)
 
+{khối dưới CHỈ in khi ledger_behind_code_count > 0 — else bỏ cả khối}
+🟠 LEDGER_BEHIND_CODE — làm rồi mà sổ chưa ghi ({n} scenario):
+     {UC}-UC1-SC3 (web)  code: {File.method}                   → sẽ thành OK
+     {UC}-UC1-SC4 (web)  code: {File.method}   chưa có test     → sẽ thành GAP
+     … {n} scenario, gom theo PRD: {LESS-06} 76 · {LESS-09} 65 · …
+   Code đã có tag @trace.implements, nhưng cột implemented_by còn trống ⇒ các row này
+   đang hiện UNTRACKED. Dashboard đếm THIẾU, và /generate-code coi là "chưa làm" nên
+   sẽ sinh lại thứ đã có.
+   Nguyên nhân thường gặp: /generate-code dừng ở cổng build nên §Write Trace State
+   chưa chạy (build fail 3 lần → "KHÔNG ghi trace" là đường thoát hợp lệ), rồi dev
+   sửa tay cho build pass và commit mà không chạy lại lệnh.
+   → /validate-traces --reconcile-code            (cả scope hiện tại)
+     /validate-traces --reconcile-code --domain {d}  (dọn từng domain cho dễ soi)
+   ⚠️  {n} trong số này CHƯA có @trace.verifies → chúng sẽ thành GAP, không phải OK.
+       Đó là số ĐÚNG: chỗ thiếu test vừa lộ ra, không phải chỗ mới hỏng.
+   🟠 KHÔNG chặn PR — code đang chạy đúng, chỉ sổ nói sai về nó.
+
 🔴 PRD_UNTRACKED_EDIT — nội dung PRD đổi mà nhãn Version KHÔNG đổi ({n} file):
   specs/payment/create-invoice/PAY01-create-invoice.md   Version 1.3 (không đổi từ lần audit)
     Bằng chứng : git status — sửa CHƯA commit
@@ -1311,6 +1458,10 @@ Routing chưa chốt ({service_unrouted_count} scenario) — 🟠 KHÔNG chặn
       và đóng dấu incorporated + archived/ — không phải làm tay bước nào).
 
 Recommendations:
+  - /validate-traces --reconcile-code  cho LEDGER_BEHIND_CODE 🟠  ← CHẠY CÁI NÀY TRƯỚC
+      ↳ Nó chỉ ghi sổ theo tag đã có trong code, không sinh code. Chạy trước thì
+        UNTRACKED/GAP bên dưới mới là số thật; chạy /generate-code trước sẽ sinh lại
+        thứ đã tồn tại và có thể ghi đè code đang chạy.
   - /generate-code {UC-ID}       cho scenario DRIFT và UNTRACKED
   - /dev-gen-test {UC-ID}        cho GAP (thiếu test)
   - /generate-bdd {prd-file}     cho PRD_DRIFT 🟠 (changelog CÓ nêu UC này)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"
@@ -21,7 +21,8 @@
     "bin/",
     "core/",
     "scripts/",
-    "docs/"
+    "docs/",
+    "!docs/update-framework-daily-logs.md"
   ],
   "keywords": [
     "claude-code",