@educa-corp/sdd-framework 0.7.1 → 0.7.3

package/bin/index.js

@@ -5,6 +5,21 @@ const path = require('path');
 
 const ROOT = path.join(__dirname, '..');
 
+// NGUỒN ASSET ĐỂ CÀI — luôn là `core/`, không bao giờ là dir ở gốc.
+//
+// `core/` là bản dựng sẵn và là thứ DUY NHẤT được ship (package.json → files:
+// bin/ core/ scripts/ docs/). Các dir `modules/`, `hooks/`, `steps/`, `templates/`,
+// `rules/`, `skills/` ở gốc là NGUỒN BUILD — chúng chỉ tồn tại trong dev checkout.
+//
+// Vì sao khai một hằng số cho việc này (hồi quy 0.7.0 / G59): đợt dọn tập publish bỏ
+// `modules/` + `hooks/` khỏi `files`, nhưng BA chỗ trong file này vẫn đọc
+// `path.join(ROOT, 'modules'|'hooks')`. Trong dev checkout chúng vẫn có nên test và
+// `npm run build` đều xanh; trong tarball thì KHÔNG, và `--module` crash cứng bằng
+// ENOENT giữa `--init` — chết TRƯỚC bước `--hooks`, nên một cờ hỏng làm chết cờ kia và
+// project bị cài dở (thiếu .claude/settings.json).
+// Test `bin/ chỉ đọc dir CÓ trong package.json files` canh việc này từ nay.
+const CORE_DIR = path.join(ROOT, 'core');
+
 const pkg      = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
 const VERSION  = pkg.version;
 
@@ -14,6 +29,12 @@ const VERSION  = pkg.version;
 // of this file is evaluated, and `const` does not hoist.
 const MANIFEST_NAME = '.install-manifest.json';
 
+// Asset được YÊU CẦU tường minh (--module, --hooks, module của service) mà bản cài không
+// có. Gom lại thay vì crash giữa `--init`: crash để lại project cài DỞ — đúng ca hồi quy
+// 0.7.0, nơi ENOENT ở bước --module làm bước --hooks không bao giờ chạy. Nhưng cũng KHÔNG
+// im lặng: exit 1 ở cuối, vì người dùng đã xin thứ họ không nhận được.
+const assetErrors = [];
+
 const args = process.argv.slice(2);
 const isMigrateSpecs = args.includes('--migrate-specs');
 const isMigrateBddPf = args.includes('--migrate-bdd-platform');
@@ -301,11 +322,20 @@ if (isInit) {
       console.log(`⚠️  Unknown module: "${moduleName}"`);
       console.log(`   Available: ${AVAILABLE_MODULES.join(', ')}`);
     } else {
-      const srcModuleDir  = path.join(ROOT, 'modules', moduleName);
+      const srcModuleDir  = path.join(CORE_DIR, 'modules', moduleName);
       const destModuleDir = path.join(agentDir, 'modules', moduleName);
-      fs.mkdirSync(destModuleDir, { recursive: true });
-      copyDirRecursive(srcModuleDir, destModuleDir);
-      console.log(`✅ Module "${moduleName}" installed to: .agent/modules/${moduleName}`);
+      // Guard TRƯỚC khi copy. Bản cũ gọi thẳng copyDirRecursive và ENOENT làm chết cả
+      // `--init` giữa đường — bước `--hooks` ngay dưới không bao giờ chạy, project bị cài
+      // dở. Một cờ hỏng không được phép làm chết cờ khác.
+      if (!fs.existsSync(srcModuleDir)) {
+        console.log(`❌ Module "${moduleName}" không có trong bản cài: ${path.relative(ROOT, srcModuleDir)}`);
+        console.log(`   Bản cài thiếu/hỏng — cài lại, hoặc xoá cache npx rồi chạy lại.`);
+        assetErrors.push(`module ${moduleName}`);
+      } else {
+        fs.mkdirSync(destModuleDir, { recursive: true });
+        copyDirRecursive(srcModuleDir, destModuleDir);
+        console.log(`✅ Module "${moduleName}" installed to: .agent/modules/${moduleName}`);
+      }
     }
   }
 
@@ -440,12 +470,18 @@ if (isInit) {
         if (!AVAILABLE_MODULES.includes(svc.module)) {
           console.log(`  ⚠️  Unknown module "${svc.module}" — skipped`);
         } else {
-          const srcMod  = path.join(ROOT, 'modules', svc.module);
+          const srcMod  = path.join(CORE_DIR, 'modules', svc.module);
           const destMod = path.join(svcAgentDir, 'modules', svc.module);
           if (fs.existsSync(srcMod)) {
             fs.mkdirSync(destMod, { recursive: true });
             copyDirRecursive(srcMod, destMod);
             console.log(`  ✅ ${svc.name}/.agent/modules/${svc.module}/`);
+          } else {
+            // Bản cũ bỏ qua ÂM THẦM ở đây: người dùng khai module cho service, không nhận
+            // được gì, và không dòng nào báo. Cùng nguồn lỗi với ca --module ở trên nhưng
+            // hỏng theo hướng im lặng — tệ hơn.
+            console.log(`  ❌ ${svc.name}: module "${svc.module}" không có trong bản cài`);
+            assetErrors.push(`${svc.name}/module ${svc.module}`);
           }
         }
       }
@@ -577,6 +613,12 @@ if (isInit) {
   console.log('To upgrade later:  /update-framework   (trong Claude Code)');
   console.log('                   (or: npx @educa-corp/sdd-framework@latest --init)');
   console.log('');
+  if (assetErrors.length) {
+    console.log('');
+    console.log(`❌ ${assetErrors.length} asset được yêu cầu nhưng bản cài không có: ${assetErrors.join(' · ')}`);
+    console.log('   Phần còn lại của --init đã hoàn tất — nhưng exit 1 vì bạn đã xin thứ không nhận được.');
+    process.exit(1);
+  }
   process.exit(0);
 }
 
@@ -963,7 +1005,7 @@ function installDataGuardHook() {
 
   // 1. Copy hook script
   fs.mkdirSync(hooksDir, { recursive: true });
-  const srcHook  = path.join(ROOT, 'hooks', 'data-guard.js');
+  const srcHook  = path.join(CORE_DIR, 'hooks', 'data-guard.js');
   const destHook = path.join(hooksDir, 'data-guard.js');
   fs.copyFileSync(srcHook, destHook);
   console.log(`  ✅ Hook copied to: .claude/hooks/data-guard.js`);

package/bin/lint-trace.js

@@ -155,6 +155,63 @@ function readLines(file) {
   return fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n').split('\n');
 }
 
+// ── T13 — hai điều kiện bảo vệ sổ có KIỂM ĐƯỢC không ─────────────────────────
+//
+// T10 (luật merge) và T11 (bị gitignore) đều hỏi `git`. Trước T13, khi không hỏi được
+// thì cả hai `catch { return; }` — IM LẶNG. Và im lặng ở đây tệ hơn nó nghe: gate-trace
+// G0 lọc warns theo rule id, không thấy gì thì in ra
+//     "✅ G0 sổ được bảo vệ — nằm trong git · git biết cách gộp (2/2 điều kiện)"
+// tức KHẲNG ĐỊNH sổ được bảo vệ trên bằng chứng chưa bao giờ được thu. Cùng hình dạng
+// G55 (`pass` không có quyền khẳng định).
+//
+// Ca thường gặp nhất KHÔNG phải hiếm: image CI tối giản. `node:20-alpine` và
+// `node:20-slim` đều KHÔNG có git — tức chính môi trường mà cổng này tồn tại để chạy.
+//
+// Ba trạng thái, phân biệt có chủ ý:
+//   ok           → hỏi được, T10/T11 chạy bình thường
+//   no-binary    → không có `git` ⇒ KHÔNG BIẾT sổ có được bảo vệ hay không
+//   not-a-repo   → có git nhưng sổ không nằm trong repo nào ⇒ nó KHÔNG được commit
+// Hai trạng thái sau đều phát T13. Gate nâng T13 thành chặn (schema →
+// gate.config_preconditions.promote_lint_rules) — pre-push NHẮC, CI CHẶN, y như T10/T11.
+// Thụt lề cho dòng hint nhiều dòng — trùng khuôn của err()/warn().
+const NL = String.fromCharCode(10) + "        ";
+let _gitState = null;
+function gitState(sampleFile) {
+  if (_gitState) return _gitState;
+  const cp = require('child_process');
+  const q = (args, opts) => cp.spawnSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'ignore', 'ignore'], ...opts });
+  const v = q(['--version']);
+  if (v.error || v.status !== 0) return (_gitState = 'no-binary');
+  const dir = sampleFile ? path.dirname(sampleFile) : '.';
+  const r = q(['rev-parse', '--git-dir'], { cwd: fs.existsSync(dir) ? dir : '.' });
+  if (r.error || r.status !== 0) return (_gitState = 'not-a-repo');
+  return (_gitState = 'ok');
+}
+
+function lintGitEvaluable(sampleFile) {
+  const st = gitState(sampleFile);
+  if (st === 'ok') return true;
+  const where = rel(sampleFile || TRACE_DIRS[0]);
+  if (st === 'no-binary') {
+    warn('T13', where,
+         'KHÔNG kiểm được điều kiện bảo vệ sổ — môi trường này không có binary `git`',
+         ['T10 (luật merge) và T11 (bị gitignore) đều phải hỏi git. Không hỏi được thì hai điều',
+          'kiện đó KHÔNG được đánh giá — và "không biết" KHÔNG PHẢI "sạch".',
+          'Ca thường gặp nhất: image CI tối giản. node:*-alpine và node:*-slim đều KHÔNG có git.',
+          'Sửa:  image: node:20        (bản Debian — có git sẵn)',
+          '  hoặc apk add --no-cache git   /   apt-get install -y git'].join(NL));
+    return false;
+  }
+  warn('T13', where,
+       'sổ trace KHÔNG nằm trong một repo git nào — nó không được version control',
+       ['Sổ trace phải commit: nó không regenerate được, và trace-history.jsonl là dữ liệu',
+        'tích luỹ — mất là mất vĩnh viễn.',
+        'Nếu đây là bản copy tạm để kiểm thì bỏ qua được. Trong CI thì KHÔNG: nghĩa là repo',
+        'chưa được clone đúng, hoặc sổ nằm trong submodule chưa clone',
+        '(GitLab: GIT_SUBMODULE_STRATEGY=recursive · GitHub: submodules: recursive).'].join(NL));
+  return false;
+}
+
 // ── T7 — marker conflict git ──────────────────────────────────────────────────
 //
 // Chạy TRƯỚC mọi rule khác và trên MỌI file: một marker lọt vào TSV làm T1/T2 báo
@@ -587,8 +644,12 @@ for (const dir of TRACE_DIRS) {
     }
   }
 
-  if (sampleForAttr) lintMergeAttr(sampleForAttr);
-  lintGitTracked(abs);
+  // T13 TRƯỚC T10/T11: nếu không hỏi được git thì hai rule kia không có gì để phán, và
+  // im lặng ở đó làm gate G0 khẳng định "sổ được bảo vệ" trên bằng chứng không tồn tại.
+  if (lintGitEvaluable(sampleForAttr || abs)) {
+    if (sampleForAttr) lintMergeAttr(sampleForAttr);
+    lintGitTracked(abs);
+  }
 }
 
 // ── Report ────────────────────────────────────────────────────────────────────
@@ -596,7 +657,7 @@ for (const dir of TRACE_DIRS) {
 if (AS_JSON) {
   console.log(JSON.stringify({
     ok: errors.length === 0,
-    scanned, trace_dirs: foundDirs, errors, warns, infos,
+    scanned, trace_dirs: foundDirs, git_state: _gitState, errors, warns, infos,
   }, null, 2));
   process.exit(errors.length && !WARN_ONLY ? 1 : 0);
 }

package/bin/self-check.js

@@ -695,13 +695,16 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
 {
   const inv = (schema.gate || {}).audit_invalidating_tags;
   if (inv) {
-    const rel = inv.ci_template;
-    if (!rel) {
-      err('R10', '`gate.audit_invalidating_tags` thiếu `ci_template` — không biết canh file nào');
-    } else {
+    // MỖI template CI phải grep đủ 7 tag — không chỉ bản GitHub. Một bản dịch (GitLab…)
+    // không được canh mà tụt lại sau schema thì grep không khớp gì ⇒ job LUÔN XANH.
+    const rels = inv.ci_templates || (inv.ci_template ? [inv.ci_template] : []);
+    if (!rels.length) {
+      err('R10', '`gate.audit_invalidating_tags` thiếu `ci_templates` — không biết canh file nào');
+    }
+    for (const rel of rels) {
       const abs = path.join(ROOT, rel);
       if (!fs.existsSync(abs)) {
-        err('R10', `\`audit_invalidating_tags.ci_template\` trỏ tới ${rel} — file không tồn tại`,
+        err('R10', `\`audit_invalidating_tags.ci_templates\` trỏ tới ${rel} — file không tồn tại`,
             'Template đổi tên/bị xoá? Không có nó thì lỗ "sửa code mà không audit lại" hở lại.');
       } else {
         const yml = fs.readFileSync(abs, 'utf8');

package/bin/trace-schema.json

@@ -1259,6 +1259,10 @@
         "Cùng cách phân vai G39 đã chọn cho pre-push vs CI."
       ],
       "promote_lint_rules": [
+        {
+          "rule": "T13",
+          "why": "KHÔNG KIỂM ĐƯỢC hai điều kiện kia — thiếu binary `git`, hoặc sổ không nằm trong repo git nào. Đây là loại THỨ TƯ, khác cả ba loại còn lại: không phải 'đang có cái sai' (🔴), không phải 'nợ' (🟠), cũng không phải 'bảo vệ đang tắt' (T10/T11) — mà là 'KHÔNG BIẾT bảo vệ có bật hay không'. Trước T13, ca này làm G0 in ra `sổ được bảo vệ — 2/2 điều kiện`: một lời KHẲNG ĐỊNH trên bằng chứng chưa bao giờ được thu, tệ hơn im lặng (cùng hình dạng G55). Ca thường gặp nhất là CI dùng image tối giản — node:*-alpine và node:*-slim đều KHÔNG có git — tức chính môi trường mà cổng này tồn tại để chạy."
+        },
         {
           "rule": "T11",
           "why": "sổ trace đang bị gitignore — nó KHÔNG được lưu vào git, mất là mất toàn bộ (G29)"
@@ -1369,7 +1373,17 @@
         "self-check R10 canh templates/ci/trace-gate.yml có nhắc đủ 7 tag này. Tag đổi tên mà",
         "file CI không biết ⇒ grep không khớp gì ⇒ job LUÔN XANH ⇒ cổng mù im lặng."
       ],
-      "ci_template": "templates/ci/trace-gate.yml",
+      "$ci_templates_comment": [
+    "MỖI file CI phải grep đủ 7 tag. Trước v0.7.2 chỉ có bản GitHub Actions được canh —",
+    "nên khi một team dịch sang GitLab, bản dịch KHÔNG được rule nào canh, và nếu nó tụt",
+    "lại sau schema thì grep không khớp gì ⇒ job LUÔN XANH ⇒ cổng mù trong im lặng. Đúng",
+    "lỗi R10 tồn tại để chặn, chỉ ở một file khác loại. Thêm template CI mới thì THÊM VÀO",
+    "danh sách này ngay — R10 canh từng file."
+   ],
+   "ci_templates": [
+    "templates/ci/trace-gate.yml",
+    "templates/ci/trace-gate.gitlab-ci.yml"
+   ],
       "tags": [
         {
           "tag": "@trace.implements",

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.7.1
+0.7.3

package/core/templates/ci/trace-gate.gitlab-ci.yml

@@ -0,0 +1,169 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# SDD Framework — Trace Gate (GitLab CI)
+#
+# COPY nội dung này vào `.gitlab-ci.yml` ở gốc repo. Nó KHÔNG tự chạy từ
+# `.agent/templates/` — mọi thứ trong `.agent/` là bản sinh ra, bị ghi đè mỗi lần
+# `/update-framework`.
+#
+# ⚠️ Repo chưa có `.gitlab-ci.yml`? Thêm file này = mọi push/MR từ nay sẽ kích hoạt
+#    pipeline. Đó là mục đích — nhưng hãy biết trước.
+#
+# GIỚI HẠN — đọc trước khi tin:
+#   Job này chứng minh "report khớp SỔ, và sổ không có cờ 🔴".
+#   Nó KHÔNG chứng minh "sổ khớp CODE" — việc đó cần quét tag trong source, đọc
+#   .feature, so version, tức cần `/validate-traces` (một lệnh LLM, không chạy được
+#   trong CI thường). Nên nó bắt ca phổ biến "quên chạy lại /validate-traces",
+#   nhưng KHÔNG bắt ca "sửa code mà không đụng sổ".
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# BỐN BẪY KHI DỊCH TỪ GITHUB ACTIONS — file này đã vá cả bốn.
+#
+# Bản GitHub (`trace-gate.yml`) dựa vào ba thứ `ubuntu-latest` cho sẵn mà GitLab
+# KHÔNG có. Hai bẫy đầu ỒN (job đỏ, thấy ngay). Hai bẫy sau IM LẶNG — job XANH
+# trên một phép kiểm chưa bao giờ chạy, tức đúng thứ cổng này tồn tại để chống.
+#
+#   1. ỒN     thiếu `tags:`        → job stuck "no active runners that can run this job",
+#                                    dù runner Online. Group/shared runner thường có
+#                                    `run_untagged = false`, nên job KHÔNG tag sẽ không
+#                                    bao giờ được nhận. Điền đúng tag của runner bạn.
+#   2. ỒN     thiếu Node           → `npx: not found`. GitHub có bước
+#                                    `actions/setup-node@v4`; GitLab không có tương
+#                                    đương, và bước đó là chỗ cấp `npx`.
+#   3. IM LẶNG thiếu `GIT_DEPTH: 0` → GitLab clone SHALLOW (mặc định 20). `git diff
+#                                    BASE...HEAD` không có merge-base ⇒ ra RỖNG ⇒ job
+#                                    `require-fresh-audit` in "MR không chạm tag nào"
+#                                    và PASS, trong khi bạn vừa đổi tag. XANH GIẢ.
+#   4. IM LẶNG image không có git   → `node:20-alpine` và `node:20-slim` đều KHÔNG có
+#                                    git. Mà lint-trace cần git cho T10 (luật merge) và
+#                                    T11 (bị gitignore) — hai điều kiện `gate-trace` G0
+#                                    NÂNG thành chặn. Không hỏi được git thì (trước T13)
+#                                    G0 in "✅ sổ được bảo vệ — 2/2 điều kiện": một lời
+#                                    KHẲNG ĐỊNH trên bằng chứng chưa bao giờ được thu.
+#                                    Từ v0.7.2 lint phát **T13** và gate FAIL đúng ca đó
+#                                    — nhưng cách sửa vẫn là dùng image CÓ git.
+#
+# `before_script` dưới đây in `node -v` và `git --version` để bẫy 2 và 4 lộ ra ở
+# dòng log đầu tiên, thay vì lộ ra dưới dạng một dấu xanh sai.
+# ─────────────────────────────────────────────────────────────────────────────
+
+stages:
+  - trace
+
+variables:
+  # ── BẪY 3 ── BẮT BUỘC. Không có dòng này thì `require-fresh-audit` XANH GIẢ.
+  GIT_DEPTH: 0
+
+  # PIN VERSION, đừng `@latest`. Cổng này quyết định PR nào được merge — một bản
+  # release framework đổi hành vi cổng giữa sprint là thứ bạn muốn tự chọn thời điểm.
+  SDD_VERSION: "0.7.2"
+
+  # Sổ/spec nằm trong submodule (umbrella + spec_source)? Bỏ comment dòng dưới.
+  # Không có nó, lint thấy 0 sổ → gate FAIL ở G2 ("chưa audit ≠ sạch"). Ồn, không im.
+  # GIT_SUBMODULE_STRATEGY: recursive
+
+.sdd:
+  # ── BẪY 2 + 4 ── `node:20` là bản Debian: có SẴN cả node lẫn git.
+  # KHÔNG dùng `node:20-alpine` / `node:20-slim` — chúng thiếu git (xem bẫy 4).
+  # Buộc phải dùng alpine? Thêm: `- apk add --no-cache git`
+  image: node:20
+
+  # ── BẪY 1 ── ĐỔI thành đúng tag của runner bạn. Kiểm ở Settings → CI/CD → Runners.
+  # Runner Online mà job vẫn stuck ⇒ hoặc lệch tag, hoặc runner không bật
+  # "Run untagged jobs", hoặc runner chỉ nhận protected ref (MR pipeline chạy trên
+  # `refs/merge-requests/N/head` — KHÔNG phải protected ref, kể cả khi đích là main).
+  tags:
+    - CHANGE_ME
+
+  before_script:
+    # Hai dòng này tồn tại để bẫy 2 và 4 lộ ra NGAY, chứ không lộ ra dưới dạng dấu xanh sai.
+    - node -v
+    - git --version
+
+# ── 1+2. Cấu trúc sổ + cổng chặn cờ 🔴 ───────────────────────────────────────
+# Sổ trace 24 cột do LLM ghi tay: một dấu tab thiếu dồn mọi ô sang trái, ô `status`
+# nhận một ngày tháng, và không cờ nào bật. lint bắt việc đó (T1/T2/T3), bắt marker
+# conflict git lọt vào sổ (T7), sổ thiếu luật merge (T10), sổ bị gitignore (T11),
+# row vừa DRIFT vừa mang `pass` (T12), và ca không hỏi được git (T13).
+#
+# `--gate-trace` tự chạy lại lint ở tầng G1, nên bước lint riêng ở trên là để có log
+# dễ đọc khi đỏ. Muốn gọn thì bỏ nó và chỉ giữ `--gate-trace`.
+trace-gate:
+  extends: .sdd
+  stage: trace
+  script:
+    - npx -y @educa-corp/sdd-framework@${SDD_VERSION} --lint-trace
+    - npx -y @educa-corp/sdd-framework@${SDD_VERSION} --gate-trace
+  artifacts:
+    when: always
+    paths:
+      - .trace/trace-report.json
+    expire_in: 1 week
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+# ── 3. Ép audit phải TƯƠI khi thứ report đang KHẲNG ĐỊNH bị đổi ──────────────
+# ĐO BẰNG TAG, KHÔNG BẰNG `src/**`: framework có luật boundary-only tagging, nên
+# "MR có sửa src/ không?" chặn oan cả MR chỉ thêm một field vào DTO — một file không
+# mang lời khẳng định trace nào. Cái gì báo oan thì bị tắt, rồi mất luôn phần cần chặn.
+# Câu hỏi đúng: "MR có chạm dòng nào mang tag mà report đang khẳng định không?"
+#   sửa log trong Controller  → cho qua
+#   thêm field vào DTO        → cho qua
+#   thêm method + @implements → CHẶN
+#   lấp một @trace.stub       → CHẶN
+#
+# 7 tag dưới đây khai ở `bin/trace-schema.json` → `gate.audit_invalidating_tags`;
+# `self-check` R10 canh danh sách này khớp schema. Tag đổi tên mà file CI không biết
+# ⇒ grep không khớp gì ⇒ job LUÔN XANH ⇒ cổng mù trong im lặng.
+#
+# GIỚI HẠN ĐÃ BIẾT: đổi tên class (AuthService → AuthenticationService) không chạm
+# dòng tag ⇒ job này bỏ lọt, dù cột `implemented_by` giờ trỏ vào tên không còn. Chấp
+# nhận có chủ ý: ca đó ít gặp và KHÔNG im lặng (lần `/validate-traces` sau báo ngay),
+# còn báo oan thì xảy ra mỗi ngày và hậu quả là CỔNG BỊ TẮT.
+require-fresh-audit:
+  extends: .sdd
+  stage: trace
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - |
+      # ── BẪY 3, phần thứ hai ── GitHub có `github.base_ref` sẵn trong checkout.
+      # GitLab phải FETCH branch đích TRƯỚC — nếu không thì "$BASE" không tồn tại,
+      # `git diff` ra rỗng, và job PASS sai. Refspec tường minh để chắc chắn
+      # `refs/remotes/origin/<branch>` được cập nhật.
+      BR="$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+      git fetch --no-tags origin "+refs/heads/${BR}:refs/remotes/origin/${BR}"
+      BASE="origin/${BR}"
+
+      # Fail-fast: chứng minh merge-base tồn tại. Không có nó, mọi kết luận bên dưới
+      # dựa trên một diff rỗng — và "rỗng" ở đây nghĩa là "không biết", không phải "sạch".
+      if ! git merge-base "$BASE" HEAD >/dev/null 2>&1; then
+        echo "🔴 Không tìm được merge-base giữa $BASE và HEAD."
+        echo "   Gần như chắc chắn là clone SHALLOW — kiểm biến GIT_DEPTH: 0 ở đầu file."
+        echo "   Không có merge-base thì git diff ra rỗng và job này sẽ PASS SAI."
+        exit 1
+      fi
+
+      TAGS='@trace\.(implements|verifies|seam_port|seam_pending|stub|stub_owner|stub_for)'
+      touched=$(git diff -U0 "$BASE"...HEAD | grep -E "^[+-].*${TAGS}" | head -5 || true)
+      audit=$(git diff --name-only "$BASE"...HEAD | grep -E 'trace-report\.json$' | head -1 || true)
+
+      if [ -n "$touched" ] && [ -z "$audit" ]; then
+        echo "🔴 MR đổi tag trace nhưng không kèm trace-report.json được sinh lại."
+        echo ""
+        echo "Những dòng này đã đổi:"
+        echo "$touched" | sed 's/^/    /'
+        echo ""
+        echo "Trace gate chỉ chứng minh 'report khớp SỔ'. Tag vừa đổi mà chưa audit lại"
+        echo "thì mọi cờ 🔴 trong report nói về trạng thái TRƯỚC khi bạn sửa."
+        echo ""
+        echo "Chạy trong Claude Code:  /validate-traces"
+        echo "Rồi commit:              .trace/trace-report.json + *.tsv"
+        exit 1
+      fi
+
+      if [ -n "$touched" ]; then
+        echo "✅ Tag trace có đổi, và audit đã được sinh lại cùng MR."
+      else
+        echo "✅ MR không chạm tag nào mà report đang khẳng định — audit vẫn còn đúng."
+      fi

package/docs/03-guides/architect.md

@@ -98,7 +98,7 @@ sprint thứ ba không ai làm.** Framework có hai lệnh CLI trả exit code
 
 | Lệnh | Chặn gì | Đặt ở đâu |
 |---|---|---|
-| `--lint-trace` | **Cấu trúc sổ** (12 rule): header lệch · row sai số ô · enum sai · `sc_id` trùng · marker conflict git · `.jsonl` hỏng. Cộng **T12 — nhất quán GIỮA các ô**: row vừa `status ∈ {DRIFT, ORPHANED}` vừa mang `dev_selftest`/`qc_status = pass`. Cộng hai điều kiện **cấu hình** ở mức ⚠️: thiếu luật merge · sổ bị gitignore | pre-push **và** CI |
+| `--lint-trace` | **Cấu trúc sổ** (13 rule): header lệch · row sai số ô · enum sai · `sc_id` trùng · marker conflict git · `.jsonl` hỏng. Cộng **T12 — nhất quán GIỮA các ô**: row vừa `status ∈ {DRIFT, ORPHANED}` vừa mang `dev_selftest`/`qc_status = pass`. Cộng hai điều kiện **cấu hình** ở mức ⚠️: thiếu luật merge · sổ bị gitignore | pre-push **và** CI |
 | `--gate-trace` | **Cấu hình** (nâng hai ⚠️ trên thành chặn) + **cờ 🔴**: `ORPHANED` · `TRACE_ORPHAN` · `SEAM_UNWIRED` · `STUB_UNRESOLVED` | CI (cần report tươi) |
 
 ```bash
@@ -106,12 +106,13 @@ npx @educa-corp/sdd-framework --lint-trace     # exit 1 nếu sổ hỏng
 npx @educa-corp/sdd-framework --gate-trace     # exit 1 nếu có cờ 🔴
 ```
 
-Mẫu sẵn dùng: `.agent/templates/ci/trace-gate.yml` (GitHub Actions) · `.agent/templates/hooks/pre-push`.
+Mẫu sẵn dùng: `.agent/templates/ci/trace-gate.yml` (GitHub Actions) · `.agent/templates/ci/trace-gate.gitlab-ci.yml` (GitLab CI) · `.agent/templates/hooks/pre-push`.
 **Copy ra khỏi `.agent/`** trước khi dùng — mọi thứ trong đó bị ghi đè mỗi lần `/update-framework`.
 
 ### Bốn tầng của `--gate-trace`, và vì sao thứ tự đó
 
 0. **Sổ được bảo vệ?** — sổ có **nằm trong git**? git có **biết cách gộp** sổ? Kiểm cấu trúc của một quyển sổ sắp mất thì vô nghĩa. Hai điều kiện này `lint-trace` đã phát hiện dưới dạng ⚠️; gate **nâng** chúng thành lỗi chặn — *pre-push nhắc, CI chặn*.
+   **Và một điều kiện thứ ba: có kiểm được không?** (`T13`) — thiếu binary `git`, hoặc sổ ngoài mọi repo. Trước v0.7.2, ca này làm G0 in `✅ sổ được bảo vệ — 2/2 điều kiện` trên bằng chứng chưa bao giờ thu, vì G0 lọc warns theo rule id và không thấy gì thì kết luận *"sạch"* thay vì *"không biết"*. Ca thường gặp nhất là **image CI tối giản** — `node:*-alpine` và `node:*-slim` đều không có git, tức chính môi trường mà cổng này tồn tại để chạy.
 1. **Sổ đúng hình dạng?** (gọi `--lint-trace`) — phán trạng thái trên sổ lệch cột là phán trên dữ liệu rác.
 2. **Report còn tươi VÀ phủ toàn bộ?** — đối chiếu `trace-report.json` với chính sổ TSV nó khai
    là đang mô tả. Không có tầng này thì cổng là **sân khấu**: chạy `/validate-traces` một lần,

package/docs/04-reference/trace-schema.md

@@ -193,6 +193,8 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 >
 > ⓘ = **không phải lỗi.** Hai cờ `*_STALE_REF` tồn tại vì version PRD/tech-doc là **MỘT số cho cả tài liệu nhiều UC** — thêm một UC làm mọi UC cũ lệch số dù không đổi một chữ. Không lọc thì cả loạt UC ăn cờ đỏ oan, và làm theo hướng dẫn cũng không tắt được (`/generate-code` skip row đang `OK`). Sạch bằng `--realign-*`: chỉ sửa dòng `@trace.*`, **không đụng logic**, và **từ chối chạy** nếu UC đó đang thật sự `DRIFT`/`ORPHANED`.
 >
+> **Không kiểm được ≠ sạch.** `lint-trace` **T13** phát khi không hỏi được `git` (image CI thiếu git, hoặc sổ ngoài repo) — và `gate-trace` G0 **fail**, thay vì khẳng định `sổ được bảo vệ — 2/2 điều kiện` trên bằng chứng chưa bao giờ thu. Cùng nguyên tắc `spec_edit_detection.degraded`: *không bịa cờ, và không im lặng*.
+
 > **Mọi cờ đều PHẢI có counter `{flag}_count`** trong Step 7 + `summary` của `trace-report.json` — `bin/self-check.js` R7 ép, không có ngoại lệ. Thiếu counter = cờ vô hình với dashboard.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"