@jspg-ai/coding-bb 0.0.3-beta.9 → 0.0.5-beta.1

package/cbb/worktrees/_shared/scripts/delete-branches.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * 删除需求分支（共享脚本，真源：cbb/worktrees/_shared/scripts/）
+ *
+ * 供 cbb-worktree-close（Step 4.4 交付完成后自动删本地 + 远程分支）与
+ * cbb-local-mode（Step 5.4 收尾删远程分支）调用。
+ *
+ * 用法：node delete-branches.js <ws_root> <branch> <mode>   # mode: keep / local / local_remote
+ *
+ * 逐仓库执行：本地分支按合并判定选 -d / -D（squash 合并 -d 失败回退 -D）；
+ * local_remote 模式追加 git push <remote> --delete。
+ * 清理阶段失败报告并继续其余仓库，不回滚（ADR 0007）。
+ */
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const wsRoot = process.argv[2];
+const branch = process.argv[3];
+const mode = process.argv[4];
+
+if (!wsRoot || !branch || !mode) {
+  console.error('Usage: node delete-branches.js <ws_root> <branch> <mode>');
+  process.exit(1);
+}
+
+if (mode === 'keep') {
+  console.log('Keep branch, skip delete');
+  console.log('---');
+  console.log('BRANCH_DELETE_RESULT', JSON.stringify({ mode: 'keep', ok: true, deleted: [] }));
+  process.exit(0);
+}
+
+if (mode !== 'local' && mode !== 'local_remote') {
+  console.error('mode must be keep / local / local_remote');
+  process.exit(1);
+}
+
+function run(cmd, cwd, env) {
+  try {
+    return { ok: true, out: execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, ...(env || {}) } }).trim() };
+  } catch (e) {
+    return { ok: false, err: (e.stderr || e.message || String(e)).trim() };
+  }
+}
+
+function detectMain(repoPath) {
+  const remote = run('git remote', repoPath);
+  if (!remote.ok || !remote.out) return 'main';
+  const r = remote.out.split(/\r?\n/)[0];
+  const symbolic = run('git symbolic-ref "refs/remotes/' + r + '/HEAD"', repoPath);
+  if (symbolic.ok && symbolic.out) {
+    return symbolic.out.replace('refs/remotes/' + r + '/', '');
+  }
+  return 'main';
+}
+
+function mergedTo(repoPath, from, to) {
+  // 0=merged, 1=unmerged, 2=to-ref-missing
+  if (!run('git rev-parse --verify --quiet "' + from + '"', repoPath).ok) return 1;
+  if (!run('git rev-parse --verify --quiet "' + to + '"', repoPath).ok) return 2;
+  if (run('git merge-base --is-ancestor "' + from + '" "' + to + '" && echo Y', repoPath).out === 'Y') return 0;
+  // 跨平台：不用 grep（Windows 无 grep），解析 git cherry 输出（+ 前缀 = 未合并提交）
+  const cherry = run('git cherry "' + to + '" "' + from + '"', repoPath);
+  if (!cherry.ok) return 1;
+  if (cherry.out.split(/\r?\n/).filter(Boolean).some(l => l.indexOf('+') === 0)) return 1;
+  return 0;
+}
+
+function mergedToMain(repoPath, branchName, main) {
+  if (mergedTo(repoPath, branchName, main) === 0) return true;
+  if (mergedTo(repoPath, branchName, 'origin/' + main) === 0) return true;
+  // release-* transit
+  const releaseList = run('git for-each-ref --format="%(refname:short)" "refs/heads/release-*" "refs/remotes/origin/release-*"', repoPath);
+  if (releaseList.ok && releaseList.out) {
+    const releases = releaseList.out.split(/\r?\n/).filter(Boolean).sort();
+    for (const rel of releases) {
+      if (mergedTo(repoPath, branchName, rel) === 0) {
+        if (mergedTo(repoPath, rel, main) === 0) return true;
+        if (mergedTo(repoPath, rel, 'origin/' + main) === 0) return true;
+      }
+    }
+  }
+  return false;
+}
+
+function deleteBranch(repoPath, name) {
+  const checkLocal = run('git branch --list "' + branch + '"', repoPath);
+  if (checkLocal.ok && checkLocal.out) {
+    const main = detectMain(repoPath);
+    const merged = main ? mergedToMain(repoPath, branch, main) : false;
+    let flag = merged ? '-d' : '-D';
+    const del = run('git branch ' + flag + ' "' + branch + '"', repoPath);
+    if (del.ok) {
+      console.log('OK ' + name + ' local branch deleted (' + flag + ', ' + (merged ? 'merged' : 'unmerged') + ')');
+    } else {
+      if (flag === '-d') {
+        const fallback = run('git branch -D "' + branch + '"', repoPath);
+        if (fallback.ok) {
+          console.log('OK ' + name + ' local branch deleted (squash merge, fallback -D)');
+        } else {
+          console.error('FAIL ' + name + ' local branch delete failed');
+          return false;
+        }
+      } else {
+        console.error('FAIL ' + name + ' local branch delete failed');
+        return false;
+      }
+    }
+  } else {
+    console.log('Skip ' + name + ': no local branch ' + branch);
+  }
+
+  if (mode === 'local_remote') {
+    const remote = run('git remote', repoPath);
+    if (remote.ok && remote.out) {
+      const r = remote.out.split(/\r?\n/)[0];
+      const pushDel = run('git push "' + r + '" --delete "' + branch + '"', repoPath, { GIT_TERMINAL_PROMPT: '0' });
+      if (pushDel.ok) {
+        console.log('OK ' + name + ' remote branch deleted');
+      } else {
+        console.log('Skip ' + name + ': remote has no ' + branch);
+      }
+    }
+  }
+  return true;
+}
+
+const configPath = path.join(wsRoot, 'CBB-WORKSPACE.json');
+let config = {};
+try { config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch (e) {}
+
+const apps = config.apps || [];
+
+console.log('=== Delete Workspace Branch ===');
+deleteBranch(wsRoot, 'workspace');
+
+console.log('=== Delete App Branches ===');
+for (const app of apps) {
+  const appPath = path.join(wsRoot, '.codespace', app.name);
+  deleteBranch(appPath, app.name);
+}
+
+console.log('---');
+console.log('BRANCH_DELETE_RESULT', JSON.stringify({ mode, ok: true }));
+process.exit(0);

package/cbb/worktrees/_shared/scripts/deprecate-branches.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * 收尾合并门禁 —— 废弃分支出口（ADR 0007）
+ *
+ * 用户在门禁处确认"分支废弃、不再交付"后，把各参与仓库远端的需求分支重命名为
+ * <branch>-deprecated（保留历史、去掉占用中的旧名），**不删除任何提交**。
+ * 本地分支保持原名不动；未推送的仓库（远端无该分支）跳过。
+ *
+ * 用法：
+ *   node deprecate-branches.js <ws_root> <branch> [--apps a,b]
+ *
+ * 退出码：0 全部成功（含 skipped）/ 1 参数错误 / 2 存在失败
+ * 末行：DEPRECATE_RESULT [...]
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+function run(cmd, cwd) {
+  try {
+    return {
+      ok: true,
+      out: execSync(cmd, {
+        cwd,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 120000,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+      }).trim(),
+    };
+  } catch (e) {
+    return { ok: false, err: (e.stderr || e.message || String(e)).trim() };
+  }
+}
+
+function loadApps(wsRoot) {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(wsRoot, 'CBB-WORKSPACE.json'), 'utf-8'));
+    return Array.isArray(config.apps) ? config.apps : [];
+  } catch (e) {
+    return [];
+  }
+}
+
+/** 对单个仓库执行废弃重命名 */
+function deprecateRepo(name, repo, branch) {
+  const newName = branch + '-deprecated';
+  const rec = { name, status: 'skipped', detail: null };
+  if (!fs.existsSync(path.join(repo, '.git'))) {
+    rec.detail = 'no-repo';
+    return rec;
+  }
+  const remote = run('git remote', repo);
+  if (!remote.ok || !remote.out) {
+    rec.detail = 'no-remote';
+    return rec;
+  }
+  const r = remote.out.split(/\r?\n/)[0];
+  // 仅重命名远端确实存在的分支
+  const exists = run('git ls-remote --heads "' + r + '" "refs/heads/' + branch + '"', repo);
+  if (!exists.ok || !exists.out) {
+    rec.detail = 'remote-has-no-branch';
+    return rec;
+  }
+  const pushNew = run('git push "' + r + '" "refs/heads/' + branch + ':refs/heads/' + newName + '"', repo);
+  if (!pushNew.ok) {
+    rec.status = 'failed';
+    rec.detail = 'push-new-failed: ' + (pushNew.err || '').split(/\r?\n/)[0];
+    return rec;
+  }
+  const delOld = run('git push "' + r + '" --delete "' + branch + '"', repo);
+  if (!delOld.ok) {
+    rec.status = 'failed';
+    rec.detail = 'delete-old-failed: ' + (delOld.err || '').split(/\r?\n/)[0];
+    return rec;
+  }
+  rec.status = 'deprecated';
+  rec.detail = 'remote ' + branch + ' → ' + newName;
+  return rec;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const wsRoot = args[0];
+  const branch = args[1];
+
+  if (!wsRoot || !branch || branch.indexOf('--') === 0) {
+    console.error('Usage: node deprecate-branches.js <ws_root> <branch> [--apps a,b]');
+    process.exit(1);
+  }
+
+  const appsIdx = args.indexOf('--apps');
+  const appFilter = appsIdx >= 0
+    ? new Set((args[appsIdx + 1] || '').split(',').map(s => s.trim()).filter(Boolean))
+    : null;
+
+  const repos = [{ name: 'workspace', repo: wsRoot }];
+  for (const app of loadApps(wsRoot)) {
+    if (appFilter && !appFilter.has(app.name)) continue;
+    repos.push({ name: app.name, repo: path.join(wsRoot, '.codespace', app.name) });
+  }
+
+  const results = repos.map(rp => deprecateRepo(rp.name, rp.repo, branch));
+
+  results.forEach(r => {
+    console.log(r.status.toUpperCase() + ' ' + r.name + (r.detail ? ' — ' + r.detail : ''));
+  });
+
+  const ok = results.every(r => r.status !== 'failed');
+  console.log('---');
+  console.log('DEPRECATE_RESULT', JSON.stringify({ branch, new_name: branch + '-deprecated', results }));
+  process.exit(ok ? 0 : 2);
+}
+
+if (require.main === module) main();
+
+module.exports = { run, loadApps, deprecateRepo };

package/cbb/worktrees/_shared/scripts/find-target-worktree.js

@@ -1,96 +1,148 @@
-require('./silence-popup');
-/**
- * openspec-shared 目标需求名识别
- *
- * 唯一真源：cbb/worktrees/_shared/scripts/find-target-worktree.js
- * 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（extend / close / push）。
- *
- * 用法：node find-target-worktree.js <ws_root>
- *
- * 优先级：
- *   1. cwd 在 .worktrees/worktree-xxx/ 内 → 自动从路径反推
- *   2. .worktrees/ 下只有一个 worktree → 自动选用
- *   3. 多个 worktree → 按 mtime 倒序，第一个为推荐
- *
- * 输出：
- *   末行输出需求名（用于 AI agent 解析）
- *   多个时按 [1] xxx ⭐ / [2] yyy 列出
- *
- * 退出码：
- *   0 - 唯一识别（自动或唯一）
- *   1 - 多个 worktree，需用户输入
- *   2 - 无 worktree
- */
-
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-
-const wsRoot = process.argv[2];
-
-if (!wsRoot) {
-  console.error('❌ 用法：node find-target-worktree.js <ws_root>');
-  process.exit(1);
-}
-
-// 优先级 1：cwd 反推
-const cwd = process.cwd();
-const cwdMatch = cwd.match(/\.worktrees[\\\/]worktree-([^\\\/]+)/);
-if (cwdMatch) {
-  const branch = cwdMatch[1];
-  console.log('✅ 从 cwd 反推需求名：' + branch);
-  console.log('---');
-  console.log(branch);
-  process.exit(0);
-}
-
-const worktreesDir = path.join(wsRoot, '.worktrees');
-if (!fs.existsSync(worktreesDir)) {
-  console.error('❌ .worktrees 目录不存在：' + worktreesDir);
-  console.error('   请先执行 cbb-worktree-init 创建 worktree');
-  console.log('---');
-  console.log('NO_WORKTREE');
-  process.exit(2);
-}
-
-// 列出所有 worktree-xxx 目录
-const entries = fs.readdirSync(worktreesDir, { withFileTypes: true })
-  .filter(e => e.isDirectory() && e.name.startsWith('worktree-'))
-  .map(e => ({
-    name: e.name.substring('worktree-'.length),
-    fullName: e.name,
-    path: path.join(worktreesDir, e.name),
-    mtime: fs.statSync(path.join(worktreesDir, e.name)).mtime.getTime(),
-  }));
-
-if (entries.length === 0) {
-  console.error('❌ 未找到任何 worktree');
-  console.error('   请先执行 cbb-worktree-init 创建 worktree');
-  console.log('---');
-  console.log('NO_WORKTREE');
-  process.exit(2);
-}
-
-// 优先级 2：唯一
-if (entries.length === 1) {
-  console.log('✅ 自动选用唯一 worktree：' + entries[0].name);
-  console.log('---');
-  console.log(entries[0].name);
-  process.exit(0);
-}
-
-// 优先级 3：多个 → 按 mtime 倒序
-entries.sort((a, b) => b.mtime - a.mtime);
-
-console.log('⚠️  检测到 ' + entries.length + ' 个 worktree（按最近修改排序）：');
-entries.forEach((e, i) => {
-  if (i === 0) {
-    console.log('  [' + (i + 1) + '] ' + e.name + '  ⭐ (推荐：最近修改)');
-  } else {
-    console.log('  [' + (i + 1) + '] ' + e.name);
-  }
-});
-console.log('请在对话中输入序号(1/2/3)或完整分支名：');
-console.log('---');
-console.log('MULTIPLE_WORKTREEES');
-process.exit(1);
+require('./silence-popup');
+/**
+ * openspec-shared 目标需求名识别
+ *
+ * 唯一真源：cbb/worktrees/_shared/scripts/find-target-worktree.js
+ * 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（close / push）。
+ *
+ * 用法：node find-target-worktree.js <ws_root>
+ *
+ * 优先级（ADR 0002 双布局）：
+ *   1. cwd 在 .worktrees/worktree-xxx/ 内 → 自动从路径反推
+ *   2. 收集候选：worktree 目录（.worktrees/worktree-xxx）
+ *      + 本地布局（根 / .codespace/<app>/ 检出在非主干分支，本地模式进行中）
+ *      同一需求名两种布局共存时合并为一项（标 both）
+ *   3. 唯一候选 → 自动选用；多个 → 按 mtime 倒序列出（本地布局用分支检出时间）
+ *
+ * 输出：
+ *   末行输出需求名（用于 AI agent 解析）
+ *   多个时按 [1] xxx ⭐ / [2] yyy 列出
+ *
+ * 退出码：
+ *   0 - 唯一识别（自动或唯一）
+ *   1 - 多个候选，需用户输入
+ *   2 - 无候选（无 worktree 且无本地布局检出）
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const wsRoot = process.argv[2];
+
+if (!wsRoot) {
+  console.error('❌ 用法：node find-target-worktree.js <ws_root>');
+  process.exit(1);
+}
+
+function run(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch (e) { return null; }
+}
+
+function currentBranch(cwd) {
+  return run('git branch --show-current', cwd) || '';
+}
+
+/** 主干名（探测失败返回 null → 该仓库任何非空检出都视为候选） */
+function detectMain(cwd) {
+  const remotes = run('git remote', cwd);
+  if (remotes) {
+    const r = remotes.split(/\r?\n/)[0];
+    const sym = run('git symbolic-ref "refs/remotes/' + r + '/HEAD"', cwd);
+    if (sym) return sym.replace('refs/remotes/' + r + '/', '');
+  }
+  if (run('git rev-parse --verify --quiet refs/heads/main', cwd)) return 'main';
+  if (run('git rev-parse --verify --quiet refs/heads/master', cwd)) return 'master';
+  return null;
+}
+
+// 优先级 1：cwd 反推
+const cwd = process.cwd();
+const cwdMatch = cwd.match(/\.worktrees[\\\/]worktree-([^\\\/]+)/);
+if (cwdMatch) {
+  const branch = cwdMatch[1];
+  console.log('✅ 从 cwd 反推需求名：' + branch);
+  console.log('---');
+  console.log(branch);
+  process.exit(0);
+}
+
+// 优先级 2a：worktree 目录候选
+const candidates = new Map(); // name → { layouts: Set, mtime }
+
+const worktreesDir = path.join(wsRoot, '.worktrees');
+if (fs.existsSync(worktreesDir)) {
+  const entries = fs.readdirSync(worktreesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && e.name.startsWith('worktree-'));
+  for (const e of entries) {
+    const name = e.name.substring('worktree-'.length);
+    const full = path.join(worktreesDir, e.name);
+    const item = candidates.get(name) || { layouts: new Set(), mtime: 0 };
+    item.layouts.add('worktree');
+    item.mtime = Math.max(item.mtime, fs.statSync(full).mtime.getTime());
+    candidates.set(name, item);
+  }
+}
+
+// 优先级 2b：本地布局候选（根 + .codespace/<app>/ 检出在非主干分支）
+function addLocalCandidate(name, cwdPath) {
+  if (!name) return;
+  const item = candidates.get(name) || { layouts: new Set(), mtime: 0 };
+  item.layouts.add('local');
+  try {
+    item.mtime = Math.max(item.mtime, fs.statSync(path.join(cwdPath, '.git')).mtime.getTime());
+  } catch (_) { /* .git 状态时间不可读则保持 */ }
+  candidates.set(name, item);
+}
+
+const rootMain = detectMain(wsRoot);
+const rootBranch = currentBranch(wsRoot);
+if (rootBranch && (!rootMain || rootBranch !== rootMain)) {
+  addLocalCandidate(rootBranch, wsRoot);
+}
+
+const codeDir = path.join(wsRoot, '.codespace');
+if (fs.existsSync(codeDir)) {
+  for (const app of fs.readdirSync(codeDir).sort()) {
+    const appDir = path.join(codeDir, app);
+    if (!fs.existsSync(path.join(appDir, '.git'))) continue;
+    const appMain = detectMain(appDir);
+    const appBranch = currentBranch(appDir);
+    if (appBranch && (!appMain || appBranch !== appMain)) {
+      addLocalCandidate(appBranch, appDir);
+    }
+  }
+}
+
+if (candidates.size === 0) {
+  console.error('❌ 未找到任何进行中的需求（无 worktree，且无仓库检出在非主干分支）');
+  console.error('   worktree 模式请先执行 cbb-worktree-init；本地模式请先执行 cbb-local-mode');
+  console.log('---');
+  console.log('NO_WORKTREE');
+  process.exit(2);
+}
+
+// 唯一候选 → 自动选用
+if (candidates.size === 1) {
+  const [name] = [...candidates.keys()];
+  const layouts = [...candidates.get(name).layouts].join('+');
+  console.log('✅ 自动选用唯一进行中需求：' + name + '（' + layouts + '）');
+  console.log('---');
+  console.log(name);
+  process.exit(0);
+}
+
+// 多候选 → 按 mtime 倒序列出
+const sorted = [...candidates.entries()].sort((a, b) => b[1].mtime - a[1].mtime);
+console.log('⚠️  检测到 ' + sorted.length + ' 个进行中的需求（按最近活动排序）：');
+sorted.forEach(([name, item], i) => {
+  const layouts = [...item.layouts].join('+');
+  const tag = i === 0 ? '  ⭐ (推荐：最近活动)' : '';
+  console.log('  [' + (i + 1) + '] ' + name + '（' + layouts + '）' + tag);
+});
+console.log('请在对话中输入序号(1/2/3)或完整分支名：');
+console.log('---');
+console.log('MULTIPLE_WORKTREEES');
+process.exit(1);

package/cbb/worktrees/_shared/scripts/find-workspace-root.js

@@ -3,10 +3,10 @@ require('./silence-popup');
  * openspec-shared 工作空间根目录定位
  *
  * 唯一真源：cbb/worktrees/_shared/scripts/find-workspace-root.js
- * 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（init / extend / close / push）。
+ * 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（close / push）。
  *
- * 优先：git worktree list 第一行（主仓库根目录，不受 worktree 内 workspace-config.json 副本干扰）
- * 兜底：当前目录含 workspace-config.json
+ * 优先：git worktree list 第一行（主仓库根目录，不受 worktree 内 CBB-WORKSPACE.json 副本干扰）
+ * 兜底：当前目录含 CBB-WORKSPACE.json
  *
  * 退出码：
  *   0 - 定位成功，输出 WS_ROOT 绝对路径
@@ -44,19 +44,19 @@ if (worktreeList.ok) {
   }
 }
 
-// 兜底：当前目录含 workspace-config.json
+// 兜底：当前目录含 CBB-WORKSPACE.json
 if (!wsRoot) {
   const cwd = process.cwd();
-  if (fs.existsSync(path.join(cwd, 'workspace-config.json'))) {
+  if (fs.existsSync(path.join(cwd, 'CBB-WORKSPACE.json'))) {
     wsRoot = cwd;
   }
 }
 
 // 校验
-if (!wsRoot || !fs.existsSync(path.join(wsRoot, 'workspace-config.json'))) {
+if (!wsRoot || !fs.existsSync(path.join(wsRoot, 'CBB-WORKSPACE.json'))) {
   console.error('❌ 未找到工作空间根目录');
-  console.error('   原因：git worktree list 失败且当前目录无 workspace-config.json');
-  console.error('   请在业务工作空间根目录（由 cbb setup 初始化、包含 workspace-config.json）下执行本技能');
+  console.error('   原因：git worktree list 失败且当前目录无 CBB-WORKSPACE.json');
+  console.error('   请在业务工作空间根目录（由 cbb setup 初始化、包含 CBB-WORKSPACE.json）下执行本技能');
   process.exit(1);
 }
 

package/cbb/worktrees/_shared/scripts/install-git-hook.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * 向指定 git 仓库安装分支感知 pre-commit hook（ADR 0002）。
+ *
+ * 真源：cbb/lib/utils/githook.js 的 PRE_COMMIT_SOURCE（本文件为部署到业务空间的自包含副本，
+ * 改动必须两处同步——本仓库内改真源后同步本文件，勿只改其一）。
+ *
+ * 用法（二选一）：
+ *   CLI：node install-git-hook.js <repoPath...>   —— 对每个仓库安装，输出 HOOK_RESULT
+ *   require：installTo(repoPath) → 'installed' | 'updated' | 'skipped-not-git'
+ *
+ * 供 cbb-worktree-init 的 sync-repos.js 兜底 clone 后调用（cbb setup 已装过，此处幂等补齐）。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const HOOK_MARKER = 'managed-by-cbb';
+const HOOK_FILE = 'pre-commit';
+const BACKUP_SUFFIX = '.cbb-backup';
+
+// 与 cbb/lib/utils/githook.js 的 buildPreCommitSource() 输出完全一致（构建时注入）
+const PRE_COMMIT_SOURCE = "#!/usr/bin/env node\n// managed-by-cbb v1 —— 分支感知提交防线（ADR 0002）\n// main 上：workspace 只放行控制面白名单，应用全拦（merge 提交除外）；非 main 一律放行。\n// 绕过逃生口仅限用户显式 git commit --no-verify。\nconst { execSync } = require('child_process');\nconst fs = require('fs');\nfunction run(cmd) {\n  try { return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim(); }\n  catch (e) { return null; }\n}\nconst branch = run('git branch --show-current') || '';\n// 主干名：优先远端 HEAD 指向；探测失败按本地 main/master 存在性回退\nlet main = null;\nconst remotes = run('git remote');\nif (remotes) {\n  const r = remotes.split(/\\r?\\n/)[0];\n  const sym = run('git symbolic-ref \"refs/remotes/' + r + '/HEAD\"');\n  if (sym) main = sym.replace('refs/remotes/' + r + '/', '');\n}\nif (!main) {\n  if (run('git rev-parse --verify --quiet refs/heads/main')) main = 'main';\n  else if (run('git rev-parse --verify --quiet refs/heads/master')) main = 'master';\n}\n// 非主干（含 detached / 探测失败）→ 放行\nif (!main || branch !== main) process.exit(0);\n\n// merge 进行中（MERGE_HEAD 存在）→ 显式人工合并提交，放行（ADR 0007 合并门禁）\nif (run('git rev-parse --verify --quiet MERGE_HEAD')) process.exit(0);\n\n// 主干上的提交：收集 staged 变更（空提交放行）\nconst staged = run('git diff --cached --name-only') || '';\nconst files = staged.split(/\\r?\\n/).filter(Boolean);\nif (files.length === 0) process.exit(0);\n\n// 仓库类型：workspace 仓库 = 检出含 CBB-WORKSPACE.json（或旧名，改名过渡期识别）\nconst isWorkspace = fs.existsSync('CBB-WORKSPACE.json') || fs.existsSync('workspace-config.json');\n\nfunction deny(bad) {\n  console.error('[cbb-guard] 主干上拦截载荷提交（ADR 0002）：');\n  bad.forEach(f => console.error('  ' + f));\n  console.error('需求载荷须在需求分支上提交：本地模式先 git checkout -b <需求名>；worktree 模式在 .worktrees/ 工作树内提交。');\n  console.error('控制面白名单：CBB-WORKSPACE.json / .gitignore / AGENTS.md / openspec/config.yaml / openspec/schemas/** / .cbb/**');\n  console.error('如确需在主干提交，须由用户显式 git commit --no-verify。');\n  process.exit(1);\n}\n\nif (isWorkspace) {\n  // 旧名仅放行删除条目：更名迁移提交（git mv）会产生旧名删除 + 新名新增两条\n  const EXACT = new Set(['CBB-WORKSPACE.json', 'workspace-config.json', '.gitignore', 'AGENTS.md', 'openspec/config.yaml']);\n  const PREFIXES = ['openspec/schemas/', '.cbb/'];\n  const bad = files.filter(f => !EXACT.has(f) && !PREFIXES.some(p => f.indexOf(p) === 0));\n  if (bad.length) deny(bad);\n} else {\n  deny(files);\n}\nprocess.exit(0);\n";
+
+function isCbbHookContent(content) {
+  return typeof content === 'string' && content.includes(HOOK_MARKER);
+}
+
+function resolveHooksDir(repoPath) {
+  const gitDir = path.join(repoPath, '.git');
+  if (!fs.existsSync(gitDir)) return null;
+  const st = fs.statSync(gitDir);
+  if (!st.isDirectory()) return null; // worktree 检出（.git 为文件）：hook 由主仓库承担
+  return path.join(gitDir, 'hooks');
+}
+
+function installTo(repoPath) {
+  const dir = resolveHooksDir(repoPath);
+  if (!dir) return 'skipped-not-git';
+
+  const hookPath = path.join(dir, HOOK_FILE);
+  fs.mkdirSync(dir, { recursive: true });
+
+  if (fs.existsSync(hookPath)) {
+    const prev = fs.readFileSync(hookPath, 'utf-8');
+    if (isCbbHookContent(prev)) {
+      if (prev !== PRE_COMMIT_SOURCE) fs.writeFileSync(hookPath, PRE_COMMIT_SOURCE);
+      return 'updated';
+    }
+    fs.writeFileSync(hookPath + BACKUP_SUFFIX, prev); // 用户自有 hook：备份后接管
+  }
+  fs.writeFileSync(hookPath, PRE_COMMIT_SOURCE);
+  try { fs.chmodSync(hookPath, 0o755); } catch (_) { /* Windows 无压力 */ }
+  return 'installed';
+}
+
+module.exports = { installTo, isCbbHookContent, PRE_COMMIT_SOURCE };
+
+// CLI 形式：node install-git-hook.js <repoPath...>
+if (require.main === module) {
+  const targets = process.argv.slice(2);
+  if (targets.length === 0) {
+    console.error('Usage: node install-git-hook.js <repoPath...>');
+    process.exit(1);
+  }
+  const results = targets.map(p => ({ path: p, status: installTo(p) }));
+  results.forEach(r => console.log((r.status === 'skipped-not-git' ? '⚠️ ' : '✅ ') + r.path + ' → ' + r.status));
+  console.log('HOOK_RESULT', JSON.stringify(results));
+  process.exit(0);
+}