@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/bin/index.js

@@ -2,7 +2,6 @@
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
 
 const ROOT = path.join(__dirname, '..');
 
@@ -19,6 +18,8 @@ const args = process.argv.slice(2);
 const isMigrateSpecs = args.includes('--migrate-specs');
 const isMigrateBddPf = args.includes('--migrate-bdd-platform');
 const isRenamePrd    = args.includes('--rename-prd-files');
+const isLintTrace    = args.includes('--lint-trace');
+const isGateTrace    = args.includes('--gate-trace');
 const isInit     = args.includes('--init');
 const isProject  = args.includes('--project');
 const installHooks = args.includes('--hooks');
@@ -80,12 +81,13 @@ if (showHelp) {
   console.log('');
   console.log('Install modes:');
   console.log('  --init                    Install framework to .agent/ + create shortcuts in .claude/commands/');
-  console.log('                            Recommended for new projects. Run upgrade.sh to upgrade later.');
+  console.log('                            Recommended for new projects. Later: /update-framework in Claude Code.');
   console.log('  --init --umbrella         Umbrella repo setup: installs framework at umbrella level only.');
   console.log('                            Generates project-context.yaml with services routing.');
   console.log('                            Does NOT install into service submodule directories.');
-  console.log('  --project                 Install full commands to ./.claude/commands/ (project-scoped, legacy)');
-  console.log('  (no flag)                 Install full commands to ~/.claude/commands/ (global, legacy)');
+  console.log('');
+  console.log('  (--project và chế độ không-cờ đã được GỠ ở v0.5.1 — chúng cài lệnh mà không cài');
+  console.log('   .agent/, nên lệnh chạy thiếu guardrail và pipeline QC không hoạt động. Dùng --init.)');
   console.log('');
   console.log('Maintenance:');
   console.log('  --migrate-specs           Migrate an existing project from the legacy artifact-type-first');
@@ -99,6 +101,23 @@ if (showHelp) {
   console.log('                            else step vocabulary; inserts @trace.platform when missing. Reports');
   console.log('                            filename COLLISION and LOST SPEC instead of guessing.');
   console.log('                            DRY-RUN by default; add --apply to execute. Uses git mv when possible.');
+  console.log('  --lint-trace             Kiểm SỔ TRACE THẬT (.trace/**) đối chiếu bin/trace-schema.json:');
+  console.log('                            header 24 cột · số ô mỗi row · giá trị enum · sc_id trùng · tên file');
+  console.log('                            {UC-ID}-{platform}.tsv · ô ngày · marker conflict git · trace-history.jsonl.');
+  console.log('                            Read-only, KHÔNG sửa gì. Exit 1 nếu có lỗi → cắm được vào CI/pre-push.');
+  console.log('                            Options: --trace DIR[,DIR] (mặc định .trace) · --specs DIR (mặc định specs)');
+  console.log('                                     --warn-only (luôn exit 0) · --json');
+  console.log('                            Vì sao: self-check canh CONTRACT (file lệnh); cái này canh DỮ LIỆU.');
+  console.log('                            Sổ trace do LLM ghi tay, 24 cột — một tab lệch là không ai thấy (G38).');
+  console.log('');
+  console.log('  --gate-trace             CỔNG CHẶN PR — exit 1 khi trace có cờ 🔴 (ORPHANED · TRACE_ORPHAN ·');
+  console.log('                            SEAM_UNWIRED · STUB_UNRESOLVED). Đây là lớp lỗi mà build xanh +');
+  console.log('                            test từng-UC xanh KHÔNG phát hiện được. Read-only.');
+  console.log('                            Ba tầng: sổ đúng hình dạng (gọi --lint-trace) → report còn TƯƠI');
+  console.log('                            (đối chiếu với sổ TSV) → không có cờ 🔴.');
+  console.log('                            Options: --trace DIR[,DIR] · --report PATH · --skip-lint');
+  console.log('                                     --no-reconcile · --warn-only · --json');
+  console.log('');
   console.log('  --rename-prd-files        Rename feature-package PRD files from the old fixed name prd.md to the');
   console.log('                            {TICKET-ID}-{prd-slug}.md convention (e.g. SEG01-segment-scoring-service.md).');
   console.log('                            For projects already on the feature-package layout. DRY-RUN by default;');
@@ -125,7 +144,8 @@ if (showHelp) {
   console.log('  npx @educa-corp/sdd-framework --init --umbrella \\');
   console.log('    --spec-source free-trial-specs \\');
   console.log('    --services mass-product-web:nextjs   # umbrella with one FE service');
-  console.log('  npx @educa-corp/sdd-framework --project --hooks              # legacy project install');
+  console.log('  npx @educa-corp/sdd-framework --lint-trace                   # kiểm sổ trace (CI / pre-push)');
+  console.log('  npx @educa-corp/sdd-framework --lint-trace --warn-only       # xem nợ tồn, chưa chặn');
   process.exit(0);
 }
 
@@ -149,16 +169,80 @@ if (isRenamePrd) {
   return; // rename-prd-files.js calls process.exit itself
 }
 
-// ── Step 1: Build .tmpl → .md ─────────────────────────────────────────────
+// ── --lint-trace: kiểm sổ trace thật của người dùng (G38) ──────────────────
+// Read-only, đi trước bước build vì nó làm việc trên .trace/ của project, không phải
+// package. Cùng khuôn với các flag maintenance ở trên.
+if (isLintTrace) {
+  require(path.join(__dirname, 'lint-trace.js'));
+  return; // lint-trace.js calls process.exit itself
+}
+
+// ── --gate-trace: cổng chặn PR — exit 1 khi có cờ 🔴 (G39) ─────────────────
+// Cũng read-only. Tự gọi lint-trace ở tầng G1, nên một lệnh là đủ cho CI.
+if (isGateTrace) {
+  require(path.join(__dirname, 'gate-trace.js'));
+  return; // gate-trace.js calls process.exit itself
+}
+
+// ── Step 1: Build .tmpl → .md — CHỈ khi cần ───────────────────────────────
+//
+// Tarball publish đã chứa `core/` dựng sẵn (npm pack: 138 entry). Build lại ở máy
+// người dùng không đem lại gì và mang rủi ro thật (GAPS-v3 G43): nó ghi vào THƯ MỤC
+// PACKAGE — tức npx cache, hoặc node_modules của bản cài global. Thư mục đó có thể
+// read-only (CI doanh nghiệp, `sudo npm i -g` rồi chạy bằng user thường), và hai
+// `--init` chạy đồng thời ở hai project dùng chung cache sẽ đua nhau trên cùng core/.
+//
+// Nên: build CHỈ khi core/ vắng mặt hoặc lệch version — tức chỉ trong dev checkout.
 const buildScript = path.join(__dirname, 'build.js');
-if (fs.existsSync(buildScript)) {
+const coreVersionFile = path.join(ROOT, 'core', 'FRAMEWORK_VERSION');
+
+let corePrebuilt = false;
+try {
+  corePrebuilt = fs.readFileSync(coreVersionFile, 'utf8').trim() === VERSION;
+} catch { /* không có file = chưa build */ }
+
+// `hasSources` LÀ phép phân biệt dev-checkout vs bản cài từ npm — đặt tên MỘT LẦN.
+//
+// Vì sao gọi tên nó (GAPS-v4 G59): trước đó cùng một `existsSync(commands/*.tmpl)` được viết
+// ở hai chỗ với hai ý khác nhau, và `package.json → files` thì SHIP `commands/` — nên phép thử
+// LUÔN đúng và consumer nhìn thấy một lời nhắc mà chú thích của chính nó nói là
+// "consumer không cần biết bước này tồn tại". Đã kiểm bằng cách pack rồi chạy tarball thật.
+// Giờ `files` chỉ còn bin/ core/ scripts/ docs/, nên `hasSources` phân biệt đúng.
+const hasSources = fs.existsSync(path.join(ROOT, 'commands', 'generate-code.tmpl'));
+
+if (!corePrebuilt && hasSources && fs.existsSync(buildScript)) {
+  // DEV CHECKOUT, core/ vắng hoặc lệch version → dựng lại từ nguồn.
   try {
     require(buildScript);
   } catch (err) {
     console.error('Build step failed:', err.message);
     process.exit(1);
   }
+} else if (!corePrebuilt) {
+  // BẢN CÀI TỪ NPM mà core/ vắng hoặc lệch version — KHÔNG có nguồn để dựng lại.
+  //
+  // Trước G59, nhánh này rơi vào `require(buildScript)` và build.js chết với một ENOENT trên
+  // `commands/` — thông báo không nói được vấn đề thật. Cố build ở đây còn tệ hơn: G43 đã nêu
+  // rõ là nó ghi vào THƯ MỤC PACKAGE (npx cache / node_modules global), có thể read-only, và
+  // hai `--init` song song sẽ đua nhau. Nên: dừng với một câu nói đúng việc cần làm.
+  console.error('');
+  console.error(`❌ Bản cài này thiếu core/ dựng sẵn cho v${VERSION}.`);
+  console.error('   Package đã tải về bị thiếu/hỏng — KHÔNG thể dựng lại vì tarball không mang');
+  console.error('   commands/*.tmpl (có chủ ý: nguồn chỉ có trong dev checkout).');
+  console.error('');
+  console.error('   Xử:  npx clear-npx-cache   (hoặc xoá thủ công cache npx) rồi chạy lại');
+  console.error(`        npm i -g @educa-corp/sdd-framework@${VERSION}   nếu dùng bản global`);
+  process.exit(1);
+} else if (hasSources) {
+  // corePrebuilt && hasSources → DEV CHECKOUT, core/ đã khớp version.
+  // Cần lời nhắc này vì trước G43 thì `--init` LUÔN build, nên "sửa .tmpl rồi --init" từng có
+  // tác dụng. Giờ không — và một thay đổi lặng lẽ như thế sẽ tốn của ai đó nửa tiếng.
+  console.log('');
+  console.log(`ℹ️  core/ đã build sẵn (v${VERSION}) — bỏ qua bước build.`);
+  console.log('   Vừa sửa commands/*.tmpl · steps/ · templates/ ? Chạy `npm run build` trước.');
 }
+// corePrebuilt && !hasSources → bản cài từ npm, mọi thứ đúng chỗ. IM LẶNG — đây là đường của
+// consumer, và họ không cần biết bước build tồn tại.
 
 // ── --init mode: install to .agent/ + create .claude/commands/ shortcuts ─────
 if (isInit) {
@@ -205,27 +289,10 @@ if (isInit) {
   console.log('');
   console.log('Creating .claude/commands/ shortcuts ...');
   console.log('');
-  fs.mkdirSync(claudeCommandsDir, { recursive: true });
-
-  const agentCommandsDir = path.join(agentDir, 'commands');
-  const commandFiles = fs.readdirSync(agentCommandsDir).filter(f => f.endsWith('.md'));
-  const failedShortcuts = [];
-
-  for (const cmdFile of commandFiles) {
-    const cmdName = cmdFile.replace('.md', '');
-    const shortcut =
-      `# /${cmdName}\n` +
-      `\n` +
-      `Read the full command definition from \`.agent/commands/${cmdFile}\`` +
-      ` and execute it with arguments: $ARGUMENTS\n`;
-    try {
-      fs.writeFileSync(path.join(claudeCommandsDir, cmdFile), shortcut, 'utf8');
-      console.log(`  ✅ /${cmdName}`);
-    } catch {
-      console.log(`  ❌ /${cmdName}  (failed to write shortcut)`);
-      failedShortcuts.push(cmdName);
-    }
-  }
+  const sc = writeShortcuts(agentDir, claudeCommandsDir, { verbose: true });
+  const commandFiles = sc.commandFiles;
+  const failedShortcuts = sc.failed;
+  reportShortcuts(sc, '.claude/commands/');
 
   // 3. Install module (optional --module flag)
   if (moduleName) {
@@ -383,17 +450,11 @@ if (isInit) {
         }
       }
 
-      // Create .claude/commands/ shortcuts
-      fs.mkdirSync(svcClaudeCmds, { recursive: true });
-      const svcCmdFiles = fs.readdirSync(path.join(svcAgentDir, 'commands')).filter(f => f.endsWith('.md'));
-      for (const cmdFile of svcCmdFiles) {
-        const cmdName = cmdFile.replace('.md', '');
-        const shortcut =
-          `# /${cmdName}\n\nRead the full command definition from \`.agent/commands/${cmdFile}\`` +
-          ` and execute it with arguments: $ARGUMENTS\n`;
-        fs.writeFileSync(path.join(svcClaudeCmds, cmdFile), shortcut, 'utf8');
-      }
-      console.log(`  ✅ ${svc.name}/.claude/commands/ (${svcCmdFiles.length} shortcuts)`);
+      // Create .claude/commands/ shortcuts (cùng hàm với đường single-service — G44:
+      // trước đó hai chỗ này copy-paste nhau và chỉ một chỗ được sửa khi có thay đổi)
+      const svcSc = writeShortcuts(svcAgentDir, svcClaudeCmds, { verbose: false });
+      console.log(`  ✅ ${svc.name}/.claude/commands/ (${svcSc.commandFiles.length} shortcuts)`);
+      reportShortcuts(svcSc, `${svc.name}/.claude/commands/`);
 
       // Generate project-context.yaml (only if not already present)
       const ctxPath = path.join(svcAgentDir, 'project-context.yaml');
@@ -510,99 +571,59 @@ if (isInit) {
     console.log('  2. Commit .agent/ to git so your whole team has the framework');
   }
   console.log('');
-  console.log('To upgrade later:  bash scripts/upgrade.sh');
+  // G47 mục 1: dòng này từng in `bash scripts/upgrade.sh` sau MỌI lần cài — nhưng
+  // `scripts/` không bao giờ được cài vào project (coreMappings không có nó), nên
+  // consumer nhận "No such file or directory" ngay câu chỉ dẫn ĐẦU TIÊN họ đọc.
+  console.log('To upgrade later:  /update-framework   (trong Claude Code)');
   console.log('                   (or: npx @educa-corp/sdd-framework@latest --init)');
   console.log('');
   process.exit(0);
 }
 
-// ── Banner (legacy --project / global modes) ──────────────────────────────
-const targetDir = isProject
-  ? path.join(process.cwd(), '.claude', 'commands')
-  : path.join(os.homedir(), '.claude', 'commands');
-
-const scope = isProject ? 'project' : 'global';
-
+// ── Không phải --init ⇒ không cài gì, chỉ hướng dẫn (GAPS-v3 G50) ─────────
+//
+// Trước đây chỗ này là hai chế độ 'legacy': `--project` và nhánh KHÔNG-CỜ (global).
+// Cả hai chỉ copy commands/*.md vào .claude/commands/ và KHÔNG cài .agent/ — trong khi
+// chính các file lệnh đó tham chiếu .agent/ ở 612 chỗ, và bước ĐẦU TIÊN của mọi lệnh là
+// 'Đọc .agent/project-context.yaml'. Kết quả không phải hỏng hẳn mà THOÁI HOÁ ÂM THẦM:
+//   • 6 lệnh QC chết (nạp skill lúc chạy từ .agent/skills/qc/)
+//   • mọi lệnh còn lại VẪN CHẠY nhưng không nạp được .agent/rules/ — tức mất data-guard
+//     và mất luật CHECKPOINT/scope. Không ai được báo.
+//   • /setup-ai-first Step 6b bảo copy từ .agent/templates/ — không có ở đó
+// Và installer thì in '✅ Installed 32/32 commands'. Đúng lớp lỗi cả loạt GAP này chống:
+// tín hiệu xanh trên thứ đã hết đúng.
+//
+// --init phủ MỌI ca thật (single-service · monorepo · umbrella). Legacy không giải quyết
+// vấn đề nào mà --init không giải quyết — nó chỉ là di sản.
 console.log('');
 console.log('╔══════════════════════════════════════════╗');
 console.log('║     SDD Framework — CLI Installer        ║');
 console.log(`║     v${VERSION}                          ║`);
 console.log('╚══════════════════════════════════════════╝');
 console.log('');
-console.log(`Scope  : ${scope}`);
-console.log(`Target : ${targetDir}`);
-if (moduleName)    console.log(`Module : ${moduleName}`);
-if (installHooks)  console.log('Hooks  : enabled');
-console.log('');
-
-// ── Step 2: Install commands ──────────────────────────────────────────────
-fs.mkdirSync(targetDir, { recursive: true });
-
-const commandsDir = path.join(ROOT, 'commands');
-const commands    = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
-const failed      = [];
-
-for (const cmd of commands) {
-  try {
-    fs.copyFileSync(path.join(commandsDir, cmd), path.join(targetDir, cmd));
-    console.log(`  ✅ ${cmd.replace('.md', '')}`);
-  } catch {
-    console.log(`  ❌ ${cmd.replace('.md', '')} (failed)`);
-    failed.push(cmd);
-  }
+if (isProject) {
+  console.log('ℹ️  `--project` đã được gỡ (v0.5.1).');
+} else {
+  console.log('ℹ️  Chạy không kèm cờ nào thì không có gì để cài.');
 }
-
 console.log('');
-
-if (failed.length > 0) {
-  console.log(`⚠️  Installed ${commands.length - failed.length}/${commands.length} commands. Failed: ${failed.join(', ')}`);
-  process.exit(1);
-}
-
-console.log(`✅ Installed ${commands.length}/${commands.length} commands to:`);
-console.log(`   ${targetDir}`);
-
-// ── Step 3: Install module (optional) ─────────────────────────────────────
-if (moduleName) {
-  console.log('');
-  if (!AVAILABLE_MODULES.includes(moduleName)) {
-    console.log(`⚠️  Unknown module: "${moduleName}"`);
-    console.log(`   Available: ${AVAILABLE_MODULES.join(', ')}`);
-    process.exit(1);
-  }
-
-  const srcModuleDir  = path.join(ROOT, 'modules', moduleName);
-  const destModuleDir = path.join(process.cwd(), '.agent', 'modules', moduleName);
-
-  fs.mkdirSync(destModuleDir, { recursive: true });
-  copyDirRecursive(srcModuleDir, destModuleDir);
-
-  console.log(`✅ Module "${moduleName}" installed to:`);
-  console.log(`   ${destModuleDir}`);
-}
-
-// ── Step 4: Install data-guard hook (optional, --hooks flag) ──────────────
-if (installHooks) {
-  console.log('');
-  installDataGuardHook();
-}
-
-// ── Summary ───────────────────────────────────────────────────────────────
+console.log('   Chế độ cũ chỉ copy file lệnh vào .claude/commands/ mà KHÔNG cài .agent/.');
+console.log('   Nhưng các lệnh tham chiếu .agent/ ở 612 chỗ — bước đầu tiên của mọi lệnh là');
+console.log('   đọc .agent/project-context.yaml. Nên bản cài đó chạy MÀ KHÔNG có data-guard,');
+console.log('   không có luật CHECKPOINT/scope, và cả pipeline QC không hoạt động — im lặng.');
 console.log('');
-console.log('Next steps:');
-console.log('  1. Open your project in Claude Code');
-console.log('  2. Type /setup-ai-first to initialize the workflow');
-console.log('  3. Type / to browse all available commands');
-if (!moduleName) {
-  console.log('');
-  console.log(`Tip: re-run with --module <name> to install a stack profile.`);
-  console.log(`     Available: ${AVAILABLE_MODULES.join(', ')}`);
-}
-if (!installHooks) {
-  console.log('');
-  console.log('Tip: re-run with --hooks to install data-guard hook (sensitive file protection).');
-}
+console.log('   Dùng:');
+console.log('     npx @educa-corp/sdd-framework --init                        # single-service');
+console.log('     npx @educa-corp/sdd-framework --init --module java-spring --hooks');
+console.log('     npx @educa-corp/sdd-framework --init --services be:java-spring,web:react');
+console.log('');
+console.log('   Đã lỡ cài kiểu cũ? Cứ chạy --init: nó phát hiện file lệnh cũ trong');
+console.log('   .claude/commands/, backup rồi báo ra — không đè im lặng.');
+console.log('');
+console.log('   Xem đủ tuỳ chọn:  npx @educa-corp/sdd-framework --help');
 console.log('');
+process.exit(0);
+
 
 // ── Helpers ───────────────────────────────────────────────────────────────
 
@@ -642,10 +663,15 @@ function readManifest(agentDir) {
 }
 
 /**
- * Copy core/ → .agent/, backing up any file the project edited since the last install.
- * @returns {{ edited: string[], backupDir: string|null, firstRun: boolean }}
- *   edited   — repo-relative paths (posix) that were overwritten AND had local edits
- *   firstRun — no manifest existed, so edits could not be detected this time
+ * Copy core/ → .agent/, backing up any file the project edited since the last install,
+ * AND removing files the framework no longer ships (GAPS-v3 G44).
+ *
+ * @returns {{ edited: string[], removed: string[], keptEdited: string[],
+ *             backupDir: string|null, firstRun: boolean }}
+ *   edited     — file bị ghi đè VÀ có sửa đổi cục bộ (đã backup)
+ *   removed    — file framework đã bỏ, còn nguyên bản ⇒ đã xoá
+ *   keptEdited — file framework đã bỏ NHƯNG người dùng đã sửa ⇒ GIỮ LẠI + backup
+ *   firstRun   — chưa có manifest nên lần này không phát hiện được sửa đổi
  */
 function installCore(coreDir, agentDir, version) {
   const manifest = readManifest(agentDir);
@@ -655,6 +681,12 @@ function installCore(coreDir, agentDir, version) {
   const edited = [];
   const written = {};
 
+  const backup = (abs, rel) => {
+    const bak = path.join(backupDir, rel);
+    fs.mkdirSync(path.dirname(bak), { recursive: true });
+    fs.copyFileSync(abs, bak);
+  };
+
   const walk = (src, dst) => {
     fs.mkdirSync(dst, { recursive: true });
     for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -666,9 +698,7 @@ function installCore(coreDir, agentDir, version) {
       // Locally edited == exists, we have a record of what we last wrote, and the
       // file no longer matches that record. Framework-only changes never match here.
       if (manifest && fs.existsSync(d) && manifest.files[rel] && sha1(d) !== manifest.files[rel]) {
-        const bak = path.join(backupDir, rel);
-        fs.mkdirSync(path.dirname(bak), { recursive: true });
-        fs.copyFileSync(d, bak);
+        backup(d, rel);
         edited.push(rel);
       }
       fs.copyFileSync(s, d);
@@ -677,33 +707,253 @@ function installCore(coreDir, agentDir, version) {
   };
   walk(coreDir, agentDir);
 
+  // ── Prune: gỡ file framework KHÔNG CÒN ship (G44) ──────────────────────────
+  //
+  // Trước G44, installCore chỉ copy — không có nhánh xoá nào. Nên một lệnh bị bỏ ở
+  // version mới nằm lại trong .agent/commands/ và .claude/commands/ của mọi project
+  // VĨNH VIỄN: vẫn hiện trong menu `/`, vẫn chạy được, vẫn mang logic của version cũ
+  // — kể cả khi framework đã bỏ nó VÌ NÓ SAI. Và `/update-framework` Step 5 thì hứa
+  // báo cáo "Removed", một trạng thái installer không thể tạo ra.
+  //
+  // Đây là hành vi XOÁ FILE TRONG PROJECT NGƯỜI DÙNG, nên chỉ xoá khi CẢ BA đúng:
+  //   1. có trong manifest cũ      ⇒ do framework đặt vào, không phải người dùng tạo
+  //   2. không có trong core/ mới  ⇒ framework đã bỏ
+  //   3. hash khớp manifest        ⇒ nguyên bản, xoá không mất gì của ai
+  // Đúng (1)+(2) mà sai (3) ⇒ người dùng đã sửa ⇒ GIỮ LẠI + backup + báo. Thà để lại
+  // một file lạc còn hơn xoá thứ ai đó đã bỏ công viết.
+  const removed = [];
+  const keptEdited = [];
+  if (manifest) {
+    for (const rel of Object.keys(manifest.files)) {
+      if (written[rel]) continue;                       // vẫn còn ship
+      const abs = path.join(agentDir, rel);
+      if (!fs.existsSync(abs)) continue;                // đã biến mất từ trước
+      if (sha1(abs) === manifest.files[rel]) {
+        fs.unlinkSync(abs);
+        removed.push(rel);
+      } else {
+        backup(abs, rel);
+        keptEdited.push(rel);
+      }
+    }
+    // Dọn thư mục rỗng còn lại sau khi prune (vd cả một module bị bỏ). Chỉ xoá dir
+    // RỖNG — không recursive, nên không thể chạm vào file nào của người dùng.
+    for (const rel of removed) {
+      let dir = path.dirname(path.join(agentDir, rel));
+      while (dir !== agentDir && dir.startsWith(agentDir)) {
+        try {
+          if (fs.readdirSync(dir).length) break;
+          fs.rmdirSync(dir);
+        } catch { break; }
+        dir = path.dirname(dir);
+      }
+    }
+  }
+
+  // GIỮ phần `shortcuts` của manifest cũ. installCore chạy TRƯỚC writeShortcuts, nên
+  // ghi một object mới chỉ có `files` sẽ xoá sạch lịch sử shortcut — và writeShortcuts
+  // sau đó thấy `prev = {}`, mất cả prune LẪN phát hiện trùng tên. Bug này đã xảy ra
+  // thật khi làm G44: .agent/commands/debug.md được gỡ nhưng shortcut của nó thì không.
   fs.writeFileSync(
     path.join(agentDir, MANIFEST_NAME),
-    JSON.stringify({ version, generated_at: new Date().toISOString(), files: written }, null, 2),
+    JSON.stringify({
+      version,
+      generated_at: new Date().toISOString(),
+      files: written,
+      shortcuts: (manifest && manifest.shortcuts) || {},
+    }, null, 2),
     'utf8'
   );
 
-  return { edited, backupDir: edited.length ? backupDir : null, firstRun };
+  return {
+    edited, removed, keptEdited,
+    backupDir: (edited.length || keptEdited.length) ? backupDir : null,
+    firstRun,
+  };
 }
 
 function reportOverwritten(result, agentLabel) {
   if (result.firstRun) {
     console.log('');
     console.log(`  ℹ️  ${agentLabel}${MANIFEST_NAME} created. Từ lần nâng cấp SAU, mọi file bạn`);
-    console.log(`     sửa trong ${agentLabel} mà bị ghi đè sẽ được backup + liệt kê.`);
+    console.log(`     sửa trong ${agentLabel} mà bị ghi đè sẽ được backup + liệt kê,`);
+    console.log(`     và file framework đã bỏ sẽ được gỡ khỏi ${agentLabel}.`);
     return;
   }
-  if (!result.edited.length) return;
 
-  const rel = path.relative(process.cwd(), result.backupDir).replace(/\\/g, '/');
-  console.log('');
-  console.log(`  ⚠️  ${result.edited.length} file trong ${agentLabel} đã bị bạn sửa và VỪA BỊ GHI ĐÈ:`);
-  for (const f of result.edited.slice(0, 12)) console.log(`        ${agentLabel}${f}`);
-  if (result.edited.length > 12) console.log(`        … và ${result.edited.length - 12} file nữa`);
-  console.log(`      Bản cũ đã lưu ở: ${rel}/`);
-  console.log(`      ${agentLabel} là bản mirror SINH RA — sửa trực tiếp ở đó không bền.`);
-  console.log(`      Muốn giữ thay đổi: chuyển nó vào repo framework rồi phát hành,`);
-  console.log(`      hoặc áp lại thủ công sau khi xem diff. Xoá thư mục backup khi xong.`);
+  const bak = result.backupDir
+    ? path.relative(process.cwd(), result.backupDir).replace(/\\/g, '/')
+    : null;
+  const list = (arr, n = 12) => {
+    for (const f of arr.slice(0, n)) console.log(`        ${agentLabel}${f}`);
+    if (arr.length > n) console.log(`        … và ${arr.length - n} file nữa`);
+  };
+
+  if (result.edited.length) {
+    console.log('');
+    console.log(`  ⚠️  ${result.edited.length} file trong ${agentLabel} đã bị bạn sửa và VỪA BỊ GHI ĐÈ:`);
+    list(result.edited);
+    console.log(`      Bản cũ đã lưu ở: ${bak}/`);
+    console.log(`      ${agentLabel} là bản mirror SINH RA — sửa trực tiếp ở đó không bền.`);
+    console.log(`      Muốn giữ thay đổi: chuyển nó vào repo framework rồi phát hành,`);
+    console.log(`      hoặc áp lại thủ công sau khi xem diff. Xoá thư mục backup khi xong.`);
+  }
+
+  // G44 — nói ra thứ đã bị GỠ. Trong một diff nâng cấp lớn, file biến mất là thứ dễ
+  // trôi nhất; và nếu không báo thì người dùng chỉ phát hiện khi gõ một slash command
+  // giờ đã không còn.
+  if (result.removed.length) {
+    console.log('');
+    console.log(`  🗑️  ${result.removed.length} file framework đã bị BỎ ở version này — đã gỡ khỏi ${agentLabel}:`);
+    list(result.removed, 8);
+    console.log(`      Chúng còn nguyên bản (không ai sửa) nên gỡ đi không mất gì.`);
+    console.log(`      Lệnh nào biến mất khỏi menu / là vì vậy.`);
+  }
+
+  if (result.keptEdited.length) {
+    console.log('');
+    console.log(`  ⚠️  ${result.keptEdited.length} file framework đã bị bỏ NHƯNG bạn đã sửa — GIỮ LẠI:`);
+    list(result.keptEdited, 8);
+    console.log(`      Đã backup ở: ${bak}/`);
+    console.log(`      Framework không dùng chúng nữa. Xoá tay khi bạn chắc không cần,`);
+    console.log(`      hoặc chuyển thay đổi đó vào repo framework nếu nó còn giá trị.`);
+  }
+}
+
+// ── Shortcut .claude/commands/ — có manifest, có prune, có cảnh báo trùng tên ──
+//
+// Vì sao cần (GAPS-v3 G44): bản cũ ghi 32 file vào .claude/commands/ VÔ ĐIỀU KIỆN,
+// không backup, không cảnh báo, và không bao giờ gỡ shortcut của lệnh đã bị bỏ.
+// Hai hệ quả:
+//   • Tên lệnh rất chung — /debug, /sync, /learn, /code-review — và trùng cả với
+//     skill/plugin sẵn có của Claude Code. Project đã có /sync riêng thì MẤT nó,
+//     im lặng, ngay lần cài đầu. Bảo vệ G24 chỉ áp cho .agent/, không tới đây.
+//   • Lệnh bị bỏ ở version mới vẫn hiện trong menu `/` mãi mãi, và khi ai đó gõ nó
+//     thì file .agent/commands/ đích đã không còn.
+//
+// Shortcut được ghi vào manifest ở khoá `shortcuts` (path tương đối gốc project),
+// tách khỏi `files` (tương đối .agent/). Manifest cũ chỉ có `files` → vẫn đọc được.
+function shortcutBody(cmdFile) {
+  const cmdName = cmdFile.replace(/\.md$/, '');
+  return `# /${cmdName}\n\nRead the full command definition from \`.agent/commands/${cmdFile}\``
+       + ` and execute it with arguments: $ARGUMENTS\n`;
+}
+
+function writeShortcuts(agentDir, claudeCommandsDir, { verbose }) {
+  const manifest = readManifest(agentDir) || {};
+  const prev = manifest.shortcuts || {};
+  const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+
+  fs.mkdirSync(claudeCommandsDir, { recursive: true });
+  const commandFiles = fs.readdirSync(path.join(agentDir, 'commands')).filter(f => f.endsWith('.md'));
+
+  const written = {};
+  const failed = [];
+  const collided = [];
+  const removed = [];
+  const keptEdited = [];
+  const legacyFound = [];   // file lệnh ĐẦY ĐỦ từ bản cài legacy — KHÁC lệnh của project
+  const sha1s = (str) => require('crypto').createHash('sha1').update(str).digest('hex');
+
+  for (const cmdFile of commandFiles) {
+    const abs  = path.join(claudeCommandsDir, cmdFile);
+    const body = shortcutBody(cmdFile);
+    const key  = cmdFile;
+
+    // Đã tồn tại, KHÔNG do lần cài trước của framework tạo, và nội dung khác ⇒ backup
+    // rồi báo — đừng lặng lẽ đè. Nhưng PHÂN BIỆT HAI CA, vì thông điệp phải khác nhau:
+    //
+    //   (a) BẢN CÀI FRAMEWORK CŨ (legacy). Legacy mode copy file lệnh ĐẦY ĐỦ (60–110 KB)
+    //       vào .claude/commands/ với đúng 32 tên đó. G50 gỡ legacy nên mọi project đã cài
+    //       kiểu cũ SẼ đi qua đường này. Gọi nó là "slash command của bạn" là SAI: người
+    //       dùng sẽ tưởng vừa mất 32 lệnh tự viết, đi mở backup tìm, rồi phát hiện đó chỉ
+    //       là bản framework cũ.
+    //   (b) slash command THẬT của project — tên lệnh framework rất chung (/debug /sync
+    //       /learn) nên trùng là chuyện có thật.
+    //
+    // Nhận diện: shortcut ~150 B · bản legacy 60–110 KB · lệnh project thường < 5 KB.
+    // Chênh ~500 lần, không cần đoán. Ngưỡng 20 KB nằm giữa 5 và 60 nên rất an toàn;
+    // `## Gate` là dấu hiệu thứ hai (mọi file lệnh built đều có, shortcut thì không).
+    if (fs.existsSync(abs) && !prev[key]) {
+      const cur = fs.readFileSync(abs, 'utf8');
+      if (cur !== body) {
+        const bak = path.join(agentDir, `.overwritten-${stamp}-shortcuts`, cmdFile);
+        try {
+          fs.mkdirSync(path.dirname(bak), { recursive: true });
+          fs.copyFileSync(abs, bak);
+          (cur.length > 20 * 1024 || cur.includes('## Gate') ? legacyFound : collided).push(cmdFile);
+        } catch { /* backup fail thì vẫn báo ở dưới */ }
+      }
+    }
+
+    try {
+      fs.writeFileSync(abs, body, 'utf8');
+      written[key] = sha1s(body);
+      if (verbose) console.log(`  ✅ /${cmdFile.replace(/\.md$/, '')}`);
+    } catch {
+      if (verbose) console.log(`  ❌ /${cmdFile.replace(/\.md$/, '')}  (failed to write shortcut)`);
+      failed.push(cmdFile.replace(/\.md$/, ''));
+    }
+  }
+
+  // Prune — cùng ba điều kiện như installCore: có trong manifest cũ, không còn ship,
+  // và còn nguyên bản. Người dùng sửa shortcut thì giữ lại.
+  for (const key of Object.keys(prev)) {
+    if (written[key]) continue;
+    const abs = path.join(claudeCommandsDir, key);
+    if (!fs.existsSync(abs)) continue;
+    if (sha1s(fs.readFileSync(abs, 'utf8')) === prev[key]) {
+      try { fs.unlinkSync(abs); removed.push(key); } catch { /* bỏ qua */ }
+    } else {
+      keptEdited.push(key);
+    }
+  }
+
+  // Ghi lại manifest (installCore đã ghi `files` trước đó — nối thêm `shortcuts`)
+  try {
+    const mPath = path.join(agentDir, MANIFEST_NAME);
+    const m = readManifest(agentDir) || { files: {} };
+    m.shortcuts = written;
+    fs.writeFileSync(mPath, JSON.stringify(m, null, 2), 'utf8');
+  } catch { /* manifest không ghi được thì lần sau coi như firstRun — không chặn cài */ }
+
+  return { commandFiles, failed, collided, legacyFound, removed, keptEdited };
+}
+
+function reportShortcuts(sc, label) {
+  // Bản cài legacy cũ — KHÔNG phải slash command của người dùng. Nói đúng tên nó, vì
+  // G50 gỡ legacy nên mọi project đã cài kiểu cũ sẽ đi qua đây, và gọi sai tên làm họ
+  // tưởng vừa mất 32 lệnh tự viết rồi đi mở backup tìm một thứ không tồn tại.
+  if ((sc.legacyFound || []).length) {
+    console.log('');
+    console.log(`  🔄 ${sc.legacyFound.length} file trong ${label} là BẢN CÀI FRAMEWORK CŨ (legacy)`);
+    console.log(`      — đã thay bằng shortcut. Đây KHÔNG phải slash command bạn tự viết.`);
+    console.log(`      Bản cũ vẫn được backup ở .agent/.overwritten-*-shortcuts/, nhưng bạn gần như`);
+    console.log(`      chắc chắn không cần nó — xoá thư mục đó khi thấy \`/\` vẫn hoạt động bình thường.`);
+    console.log(`      (Chế độ cài legacy đã được gỡ ở v0.5.1: nó cài lệnh mà không cài .agent/,`);
+    console.log(`       nên lệnh chạy thiếu guardrail và pipeline QC không hoạt động.)`);
+  }
+  if (sc.collided.length) {
+    console.log('');
+    console.log(`  ⚠️  ${sc.collided.length} slash command CÓ SẴN của project vừa bị shortcut framework ghi đè:`);
+    for (const f of sc.collided.slice(0, 10)) console.log(`        ${label}${f}`);
+    if (sc.collided.length > 10) console.log(`        … và ${sc.collided.length - 10} file nữa`);
+    console.log(`      Bản cũ đã lưu trong .agent/.overwritten-*-shortcuts/`);
+    console.log(`      Tên lệnh của framework rất chung (/debug /sync /learn) nên dễ trùng.`);
+    console.log(`      Muốn giữ lệnh của bạn: đổi tên nó rồi khôi phục từ backup.`);
+  }
+  if (sc.removed.length) {
+    console.log('');
+    console.log(`  🗑️  ${sc.removed.length} shortcut của lệnh đã bị bỏ — đã gỡ khỏi ${label}`);
+    for (const f of sc.removed.slice(0, 8)) console.log(`        /${f.replace(/\.md$/, '')}`);
+    if (sc.removed.length > 8) console.log(`        … và ${sc.removed.length - 8} nữa`);
+  }
+  if (sc.keptEdited.length) {
+    console.log('');
+    console.log(`  ⚠️  ${sc.keptEdited.length} shortcut của lệnh đã bị bỏ NHƯNG bạn đã sửa — giữ lại:`);
+    for (const f of sc.keptEdited.slice(0, 8)) console.log(`        ${label}${f}`);
+    console.log(`      Lệnh đích trong .agent/commands/ đã không còn — shortcut này sẽ lỗi khi gọi.`);
+  }
 }
 
 function installDataGuardHook() {
@@ -719,34 +969,83 @@ function installDataGuardHook() {
   console.log(`  ✅ Hook copied to: .claude/hooks/data-guard.js`);
 
   // 2. Update .claude/settings.json
+  //
+  // settings.json HỎNG thì DỪNG, đừng ghi đè. Bản cũ `catch {}` rồi đi tiếp với
+  // `settings = {}`, và bước writeFileSync bên dưới ghi đè TOÀN BỘ file bằng đúng
+  // một entry hook — tức một dấu phẩy thừa trong settings.json làm mất sạch cấu hình
+  // Claude Code của project, im lặng.
   let settings = {};
   if (fs.existsSync(settingsPath)) {
-    try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
+    const raw = fs.readFileSync(settingsPath, 'utf8');
+    try {
+      settings = JSON.parse(raw);
+    } catch (err) {
+      console.log('');
+      console.log(`  ❌ .claude/settings.json không phải JSON hợp lệ: ${err.message}`);
+      console.log('     KHÔNG đăng ký hook — ghi vào đây bây giờ sẽ xoá sạch cấu hình hiện có.');
+      console.log('     Sửa file rồi chạy lại với --hooks.');
+      console.log('');
+      console.log('  ℹ️  Script hook đã được copy; chỉ còn thiếu bước đăng ký. Mẫu:');
+      console.log('     .agent/hooks/settings.json');
+      return;
+    }
+    if (settings === null || typeof settings !== 'object' || Array.isArray(settings)) {
+      console.log('');
+      console.log('  ❌ .claude/settings.json không phải một JSON object — KHÔNG đăng ký hook.');
+      console.log('');
+      return;
+    }
   }
 
   // Merge: add PreToolUse hook if not already present
   if (!settings.hooks) settings.hooks = {};
   if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
 
+  // `Grep` BẮT BUỘC có mặt: Grep với output_mode:"content" ĐỌC ĐƯỢC nội dung file,
+  // nên thiếu nó thì việc chặn Read chỉ là cửa trước, cửa sau mở toang (GAPS-v3 G42a).
   const hookEntry = {
-    matcher: 'Read|Write|Edit|Bash',
+    matcher: 'Read|Write|Edit|Grep|NotebookEdit|Bash',
     hooks: [{ type: 'command', command: 'node .claude/hooks/data-guard.js' }],
   };
 
-  const alreadyRegistered = settings.hooks.PreToolUse.some(
+  // Tìm entry đã có (nếu có) — KHÔNG chỉ để bỏ qua, mà để NÂNG CẤP matcher.
+  //
+  // Bản cũ chỉ hỏi "có đăng ký chưa?" rồi bỏ qua nếu có. Nghĩa là mọi project đã cài
+  // hook TRƯỚC bản sửa G42 sẽ giữ matcher cũ `Read|Write|Edit|Bash` — thiếu `Grep` —
+  // VĨNH VIỄN, và không lần `--hooks` nào sau đó chữa được. Lỗ bảo mật sống sót qua
+  // đúng cái lệnh đáng ra phải bịt nó.
+  const existing = settings.hooks.PreToolUse.find(
     h => h.hooks && h.hooks.some(hh => hh.command && hh.command.includes('data-guard.js'))
   );
 
-  if (!alreadyRegistered) {
+  const REQUIRED_TOOLS = hookEntry.matcher.split('|');
+
+  if (!existing) {
     settings.hooks.PreToolUse.push(hookEntry);
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
-    console.log(`  ✅ Hook registered in: .claude/settings.json`);
+    console.log('  ✅ Hook registered in: .claude/settings.json');
   } else {
-    console.log(`  ℹ️  Hook already registered in .claude/settings.json`);
+    const have = String(existing.matcher || '').split('|').map(s => s.trim());
+    const missing = REQUIRED_TOOLS.filter(t => !have.includes(t));
+    if (missing.length) {
+      existing.matcher = hookEntry.matcher;
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+      console.log(`  ✅ Hook matcher nâng cấp: thêm ${missing.join(', ')}`);
+      if (missing.includes('Grep')) {
+        console.log('     (thiếu Grep = lỗ đọc file: Grep với output_mode:"content" trả về nội dung)');
+      }
+    } else {
+      console.log('  ℹ️  Hook already registered in .claude/settings.json');
+    }
   }
 
   console.log('');
-  console.log('  🔒 Data guard active — AI will be blocked from reading:');
-  console.log('     .env*, *.key, *.pem, *secret*, *password*, *credential*');
-  console.log('     application-prod.*, appsettings.Production.json, ...');
+  console.log('  🔒 Data guard đang canh các tool: Read · Write · Edit · Grep · NotebookEdit · Bash');
+  console.log('     Chặn: .env*  ·  *.key/.pem/.p12/.jks  ·  application-prod.*  ·  .ssh/ .aws/ secrets/');
+  console.log('           file cấu hình/dữ liệu có tên chứa secret|credential|password|token|api-key');
+  console.log('');
+  console.log('     KHÔNG chặn (có chủ ý — đây là công việc của framework):');
+  console.log('       • specs/ .trace/ docs/ .agent/ feedback/  — vùng làm việc, không chứa secret thật');
+  console.log('       • file mã nguồn (.java/.ts/.dart/.kt…)     — PasswordResetController.java là code');
+  console.log('     Guard không canh được đường đưa dữ liệu ra ngoài (WebFetch…) — nó là file guard.');
 }