@jspg-ai/coding-bb 0.0.3-beta.32 → 0.0.3-beta.34

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

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * 收尾 / 交付合并门禁 —— 直合并通道 + 合并判定（ADR 0007 / 0008）
+ *
+ * 把需求分支合并进目标分支并推送远端：
+ *   - 供 cbb-worktree-close / cbb-local-mode 的收尾门禁调用（默认目标 = 主干）
+ *   - 供 cbb-worktree-push Step 7 的"直接合并"出口调用（--target 可指定测试分支）
+ * 默认交付走 MR（人工在浏览器合入）；本脚本是用户在门禁处**显式确认**后的
+ * "由 agent 直接完成合并"通道。
+ *
+ * 用法：
+ *   node merge-branches.js <ws_root> <branch> [--apps a,b] [--target <分支>] [--allow-checkout] [--dry-run]
+ *   node merge-branches.js <ws_root> <branch> [--apps a,b] [--target <分支>] --check   # 仅判定，不合并
+ *
+ * 目标分支：
+ *   缺省 / --target 等于该仓库探测主干 → 主干快路径（本地主干检出上 merge --no-ff → push）
+ *   --target 指定非主干分支            → 临时 worktree（基于 origin/<target>，不动用户检出）
+ *
+ * 模式：
+ *   --check      逐仓库判定是否已合并到目标（主干含 release-* 中转 / squash / cherry-pick 兜底，
+ *                算法与 cbb-worktree-close 的 safety-check.js 同源）；不修改任何状态
+ *   默认         两阶段（ADR 0007）：
+ *                  1. 预检：逐仓库校验（目标可解析 / 检出干净 / 分支存在）
+ *                     任一不过 → 退出 2，不执行任何合并
+ *                  2. 执行：merge --no-ff → push；执行中失败 → 停止并报告已完成清单（不回滚；重跑幂等）
+ *   --dry-run    只做预检，不执行
+ *
+ * 退出码：0 全部成功（含 skipped / merged）/ 1 参数错误 / 2 预检或执行失败（含 need-mr / unmerged）
+ * 末行：MERGE_RESULT [...] 或 MERGE_CHECK_RESULT [...]
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+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 detectMain(repoPath) {
+  const remote = run('git remote', repoPath);
+  if (!remote.ok || !remote.out) return '';
+  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 '';
+}
+
+// ── 合并判定（与 cbb-worktree-close/scripts/safety-check.js 同源） ──
+// 0=merged, 1=unmerged, 2=to-ref-missing
+function mergedTo(repoPath, from, to) {
+  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 'main';
+  if (mergedTo(repoPath, branchName, 'origin/' + main) === 0) return 'origin/' + main;
+  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 'main-via-' + rel;
+        if (mergedTo(repoPath, rel, 'origin/' + main) === 0) return 'origin/' + main + '-via-' + rel;
+      }
+    }
+  }
+  return null;
+}
+
+/** 目标为具体分支时的已合并判定（含 origin 镜像，不做 release 中转） */
+function mergedToTarget(repoPath, branchName, target) {
+  if (mergedTo(repoPath, branchName, target) === 0) return target;
+  if (mergedTo(repoPath, branchName, 'origin/' + target) === 0) return 'origin/' + target;
+  return null;
+}
+
+function classifyPushError(stderr) {
+  const s = (stderr || '').toLowerCase();
+  if (s.includes('protected branch') || s.includes('deny updating')) return 'branch-protected';
+  if (s.includes('non-fast-forward') || s.includes('fetch first') || s.includes('rejected')) return 'non-fast-forward';
+  if (s.includes('permission denied (publickey)')) return 'ssh-auth-failed';
+  if (s.includes('authentication failed')) return 'https-auth-failed';
+  if (s.includes('could not resolve host') || s.includes('connection refused') || s.includes('hung up')) return 'network-unreachable';
+  return 'unknown';
+}
+
+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 [];
+  }
+}
+
+/** 参与仓库：workspace（根 = 主干检出）+ 各 app（.codespace/<app> = 主干检出） */
+function buildRepos(wsRoot, appFilter) {
+  const repos = [{ name: 'workspace', repo: wsRoot, work: wsRoot }];
+  for (const app of loadApps(wsRoot)) {
+    if (appFilter && !appFilter.has(app.name)) continue;
+    const dir = path.join(wsRoot, '.codespace', app.name);
+    repos.push({ name: app.name, repo: dir, work: dir });
+  }
+  return repos;
+}
+
+function hasRef(repoPath, ref) {
+  return run('git rev-parse --verify --quiet "' + ref + '"', repoPath).ok;
+}
+
+/** 清理临时 worktree（失败仅警告，不阻断） */
+function cleanupTempWorktree(repoPath, tmpDir) {
+  if (!tmpDir) return;
+  const removed = run('git worktree remove --force "' + tmpDir + '"', repoPath);
+  if (!removed.ok && fs.existsSync(tmpDir)) {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (e) { /* Windows 锁：留给用户 */ }
+  }
+  run('git worktree prune', repoPath);
+}
+
+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 merge-branches.js <ws_root> <branch> [--apps a,b] [--target b] [--allow-checkout] [--dry-run] [--check]');
+    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 targetIdx = args.indexOf('--target');
+  const targetArg = targetIdx >= 0 ? (args[targetIdx + 1] || '').trim() : '';
+  if (targetIdx >= 0 && !targetArg) {
+    console.error('--target 需要提供分支名');
+    process.exit(1);
+  }
+  const allowCheckout = args.includes('--allow-checkout');
+  const dryRun = args.includes('--dry-run');
+  const checkOnly = args.includes('--check');
+
+  const repos = buildRepos(wsRoot, appFilter);
+
+  // ── --check：仅判定每仓库是否已合并到目标 ─────────────────
+  if (checkOnly) {
+    const results = [];
+    for (const rp of repos) {
+      const rec = { name: rp.name, status: 'unmerged', merged: null, main: null, target: null };
+      if (!fs.existsSync(path.join(rp.repo, '.git'))) {
+        rec.status = 'no-repo';
+        results.push(rec);
+        continue;
+      }
+      run('git fetch --quiet origin', rp.repo);
+      const main = detectMain(rp.repo);
+      if (!main) {
+        rec.status = 'failed';
+        results.push(rec);
+        continue;
+      }
+      rec.main = main;
+      const target = targetArg || main;
+      rec.target = target;
+      if (!hasRef(rp.repo, 'refs/heads/' + branch)) {
+        rec.status = 'no-branch';
+        results.push(rec);
+        continue;
+      }
+      const merged = (!targetArg || target === main)
+        ? mergedToMain(rp.repo, branch, main)
+        : mergedToTarget(rp.repo, branch, target);
+      rec.merged = merged;
+      rec.status = merged ? 'merged' : 'unmerged';
+      results.push(rec);
+    }
+    results.forEach(r => console.log(r.status.toUpperCase() + ' ' + r.name + (r.merged ? ' → ' + r.merged : '') + (r.target ? ' [target: ' + r.target + ']' : '')));
+    const ok = results.every(r => r.status !== 'unmerged' && r.status !== 'failed');
+    console.log('---');
+    console.log('MERGE_CHECK_RESULT', JSON.stringify({ branch, target: targetArg || null, results }));
+    process.exit(ok ? 0 : 2);
+  }
+
+  // ── 阶段 1：预检 ──────────────────────────────────────────
+  const prechecks = [];
+  for (const rp of repos) {
+    const rec = { name: rp.name, status: 'ok', main: null, target: null, temp: false, reason: null };
+    if (!fs.existsSync(path.join(rp.repo, '.git'))) {
+      rec.status = 'skipped';
+      rec.reason = 'no-repo';
+      prechecks.push(rec);
+      continue;
+    }
+    const fetch = run('git fetch --quiet origin', rp.repo);
+    if (!fetch.ok) {
+      rec.status = 'failed';
+      rec.reason = 'fetch-failed';
+      prechecks.push(rec);
+      continue;
+    }
+    const main = detectMain(rp.repo);
+    if (!main) {
+      rec.status = 'failed';
+      rec.reason = 'cannot-detect-main';
+      prechecks.push(rec);
+      continue;
+    }
+    rec.main = main;
+    const target = targetArg || main;
+    rec.target = target;
+
+    if (!hasRef(rp.repo, 'refs/heads/' + branch)) {
+      rec.status = 'skipped';
+      rec.reason = 'no-branch';
+      prechecks.push(rec);
+      continue;
+    }
+    const targetLocal = hasRef(rp.repo, 'refs/heads/' + target);
+    const targetRemote = hasRef(rp.repo, 'refs/remotes/origin/' + target);
+    if (!targetLocal && !targetRemote) {
+      rec.status = 'failed';
+      rec.reason = 'target-not-found';
+      prechecks.push(rec);
+      continue;
+    }
+
+    if (target === main) {
+      // 主干路径（快路径，与 ADR 0007 收尾门禁一致）
+      if (mergedToMain(rp.repo, branch, main)) {
+        rec.status = 'skipped';
+        rec.reason = 'already-merged';
+        prechecks.push(rec);
+        continue;
+      }
+      const status = run('git status --porcelain', rp.work);
+      if (!status.ok || status.out) {
+        rec.status = 'failed';
+        rec.reason = 'dirty-worktree';
+        prechecks.push(rec);
+        continue;
+      }
+      const current = run('git branch --show-current', rp.work);
+      if (current.out && current.out !== main && !allowCheckout) {
+        rec.status = 'failed';
+        rec.reason = 'not-on-main';
+        prechecks.push(rec);
+        continue;
+      }
+      const ahead = run('git rev-list --count "origin/' + main + '..' + main + '"', rp.repo);
+      if (ahead.ok && ahead.out && parseInt(ahead.out, 10) > 0) {
+        rec.status = 'failed';
+        rec.reason = 'main-ahead-of-origin';
+        prechecks.push(rec);
+        continue;
+      }
+    } else {
+      // 指定分支路径：已合并则跳过；当前检出即目标且干净 → 就地；否则临时 worktree
+      if (mergedToTarget(rp.repo, branch, target)) {
+        rec.status = 'skipped';
+        rec.reason = 'already-merged';
+        prechecks.push(rec);
+        continue;
+      }
+      const current = run('git branch --show-current', rp.work);
+      if (current.out === target) {
+        const status = run('git status --porcelain', rp.work);
+        if (!status.ok || status.out) {
+          rec.status = 'failed';
+          rec.reason = 'dirty-worktree';
+          prechecks.push(rec);
+          continue;
+        }
+      } else {
+        rec.temp = true; // 执行阶段创建临时 worktree
+      }
+    }
+    prechecks.push(rec);
+  }
+
+  const hasPrecheckFailure = prechecks.some(p => p.status === 'failed');
+  prechecks.forEach(p => {
+    if (p.status === 'failed') console.log('FAIL ' + p.name + ': ' + p.reason);
+    else if (p.status === 'skipped') console.log('SKIP ' + p.name + ': ' + p.reason);
+    else console.log('OK   ' + p.name + ' → 合并至 ' + p.target + (p.temp ? '（临时 worktree）' : ''));
+  });
+
+  if (hasPrecheckFailure) {
+    console.log('---');
+    console.log('MERGE_RESULT', JSON.stringify({ phase: 'precheck', results: prechecks }));
+    process.exit(2);
+  }
+
+  if (dryRun) {
+    console.log('---');
+    console.log('MERGE_RESULT', JSON.stringify({ phase: 'precheck', dry_run: true, results: prechecks }));
+    process.exit(0);
+  }
+
+  // ── 阶段 2：执行（停止式，不回滚） ────────────────────────
+  const results = prechecks.map(p => ({ ...p, status: p.status, detail: null }));
+  let stopped = false;
+
+  for (let i = 0; i < prechecks.length; i += 1) {
+    const p = prechecks[i];
+    const rp = repos[i];
+    if (p.status !== 'ok') continue;
+    if (stopped) {
+      results[i].status = 'not-attempted';
+      continue;
+    }
+
+    const target = p.target;
+    const mergeMsg = "Merge branch '" + branch + "'";
+
+    if (target === p.main) {
+      // ── 主干路径（快路径） ──
+      const current = run('git branch --show-current', rp.work);
+      if (current.out !== target) {
+        const co = run('git checkout --quiet "' + target + '"', rp.work);
+        if (!co.ok) {
+          results[i].status = 'failed';
+          results[i].detail = 'checkout-failed: ' + co.err.split(/\r?\n/)[0];
+          stopped = true;
+          continue;
+        }
+      }
+      const pull = run('git pull --ff-only --quiet origin "' + target + '"', rp.repo);
+      if (!pull.ok) {
+        results[i].status = 'failed';
+        results[i].detail = 'pull-failed: ' + pull.err.split(/\r?\n/)[0];
+        stopped = true;
+        continue;
+      }
+      const merge = run('git merge --no-ff -m "' + mergeMsg + '" "' + branch + '"', rp.repo);
+      if (!merge.ok) {
+        run('git merge --abort', rp.repo);
+        results[i].status = 'failed';
+        results[i].detail = 'merge-failed: ' + merge.err.split(/\r?\n/)[0];
+        stopped = true;
+        continue;
+      }
+      let push = run('git push origin "' + target + '"', rp.repo);
+      if (!push.ok) {
+        const code = classifyPushError(push.err);
+        if (code === 'non-fast-forward') {
+          const retryPull = run('git pull --ff-only --quiet origin "' + target + '"', rp.repo);
+          push = retryPull.ok ? run('git push origin "' + target + '"', rp.repo) : retryPull;
+        }
+        if (!push.ok) {
+          const code2 = classifyPushError(push.err);
+          if (code2 === 'branch-protected') {
+            results[i].status = 'need-mr';
+            results[i].detail = 'branch-protected（目标分支受保护，请改用 MR 出口）';
+          } else {
+            results[i].status = 'failed';
+            results[i].detail = 'push-failed: ' + (push.err || '').split(/\r?\n/)[0];
+          }
+          stopped = true;
+          continue;
+        }
+      }
+      results[i].status = 'merged';
+      results[i].detail = 'merged+pushed origin/' + target;
+      continue;
+    }
+
+    // ── 指定分支路径（当前检出即目标 → 就地；否则临时 worktree） ──
+    let workDir = rp.work;
+    let tmpDir = null;
+    const current = run('git branch --show-current', rp.work);
+    if (current.out !== target) {
+      tmpDir = path.join(os.tmpdir(), 'cbb-merge-' + process.pid + '-' + i);
+      const base = hasRef(rp.repo, 'refs/remotes/origin/' + target) ? 'origin/' + target : target;
+      const add = run('git worktree add --detach "' + tmpDir + '" "' + base + '"', rp.repo);
+      if (!add.ok) {
+        results[i].status = 'failed';
+        results[i].detail = 'worktree-add-failed: ' + add.err.split(/\r?\n/)[0];
+        stopped = true;
+        continue;
+      }
+      workDir = tmpDir;
+    } else {
+      const pull = run('git pull --ff-only --quiet origin "' + target + '"', rp.repo);
+      if (!pull.ok) {
+        results[i].status = 'failed';
+        results[i].detail = 'pull-failed: ' + pull.err.split(/\r?\n/)[0];
+        stopped = true;
+        continue;
+      }
+    }
+
+    const merge = run('git merge --no-ff -m "' + mergeMsg + '" "' + branch + '"', workDir);
+    if (!merge.ok) {
+      run('git merge --abort', workDir);
+      cleanupTempWorktree(rp.repo, tmpDir);
+      results[i].status = 'failed';
+      results[i].detail = 'merge-failed: ' + merge.err.split(/\r?\n/)[0];
+      stopped = true;
+      continue;
+    }
+
+    let push = run('git push origin "HEAD:refs/heads/' + target + '"', workDir);
+    if (!push.ok) {
+      const code = classifyPushError(push.err);
+      if (code === 'non-fast-forward') {
+        // 远端已前进：在合并工作区 ff 同步后重试一次
+        const retry = run('git fetch --quiet origin "' + target + '" && git reset --hard FETCH_HEAD', workDir);
+        if (retry.ok) {
+          const rem = run('git merge --no-ff -m "' + mergeMsg + '" "' + branch + '"', workDir);
+          if (rem.ok) push = run('git push origin "HEAD:refs/heads/' + target + '"', workDir);
+        }
+      }
+      if (!push.ok) {
+        const code2 = classifyPushError(push.err);
+        cleanupTempWorktree(rp.repo, tmpDir);
+        if (code2 === 'branch-protected') {
+          results[i].status = 'need-mr';
+          results[i].detail = 'branch-protected（目标分支受保护，请改用 MR 出口）';
+        } else {
+          results[i].status = 'failed';
+          results[i].detail = 'push-failed: ' + (push.err || '').split(/\r?\n/)[0];
+        }
+        stopped = true;
+        continue;
+      }
+    }
+    cleanupTempWorktree(rp.repo, tmpDir);
+    results[i].status = 'merged';
+    results[i].detail = 'merged+pushed origin/' + target + (tmpDir ? '（临时 worktree）' : '');
+  }
+
+  results.forEach(r => {
+    console.log(r.status.toUpperCase() + ' ' + r.name + (r.detail ? ' — ' + r.detail : ''));
+  });
+
+  const ok = results.every(r => r.status === 'merged' || r.status === 'skipped');
+  console.log('---');
+  console.log('MERGE_RESULT', JSON.stringify({ phase: 'execute', target: targetArg || null, results }));
+  process.exit(ok ? 0 : 2);
+}
+
+if (require.main === module) main();
+
+module.exports = { run, detectMain, mergedTo, mergedToMain, mergedToTarget, classifyPushError, loadApps, buildRepos };

package/cbb/worktrees/_shared/scripts/push-core.js

@@ -3,7 +3,7 @@ require('./silence-popup');
  * openspec-shared 推送核心模块
  *
  * 唯一真源：cbb/worktrees/_shared/scripts/push-core.js
- * 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（init-worktree / extend-worktree / push-worktrees）。
+ * 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（init / push）。
  *
  * 公开 API：
  *   - tryExec(cmd, cwd, execImpl)             包装 execSync，统一返回 {ok, out|err}

package/cbb/worktrees/_shared/scripts/silence-popup.js

@@ -4,7 +4,7 @@
 // koffi is resolved from cbb global install (no local node_modules needed).
 //
 // 唯一真源：cbb/worktrees/_shared/scripts/silence-popup.js
-// 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（init / extend / close / push）。
+// 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（init / close / push / local-mode）。
 // skill 内同目录引用：脚本第一行 `require('./silence-popup')`。
 if (process.platform === 'win32') {
   try {

package/cbb/worktrees/skills/cbb-local-mode/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: cbb-local-mode
-description: "业务空间本地模式开发：空间根与各涉及应用在 .codespace/<app>/ 就地建同名分支，当前会话直接开发（不建 worktree、不换目录）。触发：用户说'本地模式'/'就地开发'/'不走 worktree'/'在这个窗口开发'，或双模式选择时用户选本地模式。覆盖开工（状态自检→布局确认→切分支）、开发、提交推送（转 cbb-worktree-push）、收尾（回 main + 删分支）、升级 worktree（重跑 cbb-worktree-init）。一次只承载一个需求。"
+description: "业务空间本地模式开发：空间根与各涉及应用在 .codespace/<app>/ 就地建同名分支，当前会话直接开发（不建 worktree、不换目录）。触发：用户说'本地模式'/'就地开发'/'不走 worktree'/'在这个窗口开发'，或双模式选择时用户选本地模式。覆盖开工（状态自检→布局确认→切分支）、开发、提交推送（转 cbb-worktree-push）、收尾（收尾合并门禁 ADR 0007：MR / 直合并 / 确认废弃后回 main + 删分支）、升级 worktree（重跑 cbb-worktree-init）。一次只承载一个需求。"
 ---
 
 # Local Mode（本地模式）
 
-业务空间的**就地开发**模式（ADR 0002）：需求涉及的所有仓库（空间根 + 各应用的标准本地检出 `.codespace/<app>/`）统一切到同名分支，当前会话在原地直接开发。与 worktree 模式**能力对称**（都能改 workspace 内容与应用代码、都强制分支隔离、交付都走 MR），差异仅是**无隔离目录、不可并行**——适合单线程快速推进的需求。
+业务空间的**就地开发**模式（ADR 0002）：需求涉及的所有仓库（空间根 + 各应用的标准本地检出 `.codespace/<app>/`）统一切到同名分支，当前会话在原地直接开发。与 worktree 模式**能力对称**（都能改 workspace 内容与应用代码、都强制分支隔离、交付均有 MR 与直合并两条通道，ADR 0007/0008），差异仅是**无隔离目录、不可并行**——适合单线程快速推进的需求。
 
 **启动时声明：** "我正在使用 cbb-local-mode 技能进行本地模式开发。"
 
@@ -14,7 +14,8 @@ description: "业务空间本地模式开发：空间根与各涉及应用在 .c
 - **两模式由用户选择，agent 只给推荐**：需要并行 / 隔离 → cbb-worktree-init；单线程快改 → 本技能。涉及应用代码不再是 worktree 独占——本地模式同样支持（`.codespace/<app>/` 就地切分支）
 - **基准 = `origin/main`（唯一真相源）；`.codespace/<app>/` 的检出 = 视图**：本地模式暂态占用视图合法；main 检出是基准快照，**严禁直接在 main 检出上提交**（pre-commit hook 会拦）
 - **一次只承载一个需求**：本地模式独占空间根与各 app 的本地检出；期间并行新需求只能走 worktree 模式（两模式互不干扰，worktree 分支从 `origin/main` 建，不依赖本地检出状态）
-- **提交防线在 hook**：分支感知 pre-commit hook 拦截一切 main 上的载荷提交（workspace 白名单外 / 应用全拦）；被拦 = 大声失败，按指引回分支，**禁止自动 `--no-verify` 绕过**
+- **提交防线在 hook**：分支感知 pre-commit hook 拦截一切 main 上的载荷提交（workspace 白名单外 / 应用全拦；merge 提交放行）；被拦 = 大声失败，按指引回分支，**禁止自动 `--no-verify` 绕过**
+- **收尾合并门禁（ADR 0007，与 worktree 模式对称）**：收尾前每个参与仓库必须为"已合并"，未合并时三选一——**提 MR** / **直合并**（`merge-branches.js --allow-checkout`）/ **确认废弃**（远程重命名 `<需求名>-deprecated`）。**硬门禁：未合并且非废弃一律不允许收尾**
 - 所有原子操作封装为 `scripts/*.js`（跨平台 Node.js），调用方式与 worktree 三件套一致：`node "<skill_dir>/scripts/<name>.js" <参数>`，cwd 保持空间根
 
 ---
@@ -41,7 +42,7 @@ node "<skill_dir>/scripts/check-local-state.js" "<ws_root>"
 
 ## Step 1：需求名与布局确认
 
-1. 对话中询问需求名（kebab-case，同时作分支名；禁 `..` / 路径分隔符 / 空格）
+1. 对话中询问需求名（kebab-case，同时作分支名；禁 `..` / 路径分隔符 / 空格）：直接给名，或输入需求描述由 agent 推荐 3–5 个英文候选（`AskUserQuestion` 选定；不满意可直接回复自己的名字）
 2. 从需求语境提取**涉及的应用子集**（改哪些 `.codespace/<app>`）；纯 workspace 内容则仅根参与。展示布局向用户确认：
 
 ```
@@ -73,18 +74,49 @@ node "<skill_dir>/scripts/start-local.js" "<ws_root>" "<branch>" --apps "<app1>,
 
 ## Step 4：提交推送（转 cbb-worktree-push）
 
-对话中说"提交并推送"即触发 `cbb-worktree-push`——其仓库发现已支持**本地布局**（根 + 持有同名分支的 `.codespace/<app>/`），dry-run 预览（含 agent 生成的 commit 信息）→ 批量 commit → push → MR 预填链接，全流程与 worktree 模式一致。
+对话中说"提交并推送"即触发 `cbb-worktree-push`——其仓库发现已支持**本地布局**（根 + 持有同名分支的 `.codespace/<app>/`），dry-run 预览（含 agent 生成的 commit 信息）→ 批量 commit → push → Step 7 交付选择（提 MR 预填链接 / 直接合并 / 暂不处理，ADR 0008），全流程与 worktree 模式一致。
 
-## Step 5：收尾（MR 合并后）
+## Step 5：收尾（收尾合并门禁 · ADR 0007）
 
-MR 合并、验收通过后回到本会话收尾（各参与仓库）：
+MR 合并、验收通过后回到本会话收尾。**与 worktree 模式同门禁**：每个参与仓库（空间根 + 各参与 `.codespace/<app>/`）必须为"已合并"。
+
+**5.1 交付前置**：未提交改动 → 先提交；未归档 change → 先归档并提交（**合并前必须已归档 + 已提交**）。
+
+**5.2 判定是否已合并**（复用共享判定，算法与 close 的 `safety-check` 同源）：
+
+```bash
+node "<skill_dir>/scripts/merge-branches.js" "<ws_root>" "<需求名>" --apps "<app1,app2>" --check
+```
+
+- 解读末行 `MERGE_CHECK_RESULT`：每仓库 `merged`（含 `origin/main` / `main-via-release-*`）/ `unmerged` / `no-branch`
+- 全部 `merged` / `no-branch`（退出码 0）→ 直接进 5.4
+- 存在 `unmerged`（退出码 2）→ 进 5.3
+
+**5.3 门禁三选一**（`AskUserQuestion`，同 close Step 3.4）：
+
+- **提 MR** → **中止收尾**，引导用户运行 `cbb-worktree-push`（说"提交并推送"）生成 MR 预填链接（其 Step 7：目标分支候选交互 + `make-mr-urls.js`）→ 合并完重跑本步
+- **直合并** → `merge-branches.js`（本地检出被需求分支占用，**必须加 `--allow-checkout`** 切回主干）：
+
+  ```bash
+  node "<skill_dir>/scripts/merge-branches.js" "<ws_root>" "<需求名>" --apps "<app1,app2>" --allow-checkout
+  ```
+
+  `need-mr`（远端主干受保护）→ 改用提 MR；`failed` → 输出明细、修复后重跑
+- **确认废弃** → `deprecate-branches.js`（远程重命名 `<需求名>-deprecated`；本地分支保留原名）
+
+**5.4 交付完成 → 各仓库回主干并删分支**：
 
 ```bash
 git -C "<仓库>" checkout main && git -C "<仓库>" pull && git -C "<仓库>" branch -d "<需求名>"
 ```
 
+- 各仓库本地分支删除后，远程分支删除由共享脚本完成（删除前输出将删清单）：
+
+```bash
+node "<skill_dir>/scripts/delete-branches.js" "<ws_root>" "<需求名>" local_remote
+```
 - `checkout` 被 hook 拦（说明 main 落后或本地 main 有分叉）→ 先 `pull --ff-only`，再删分支
-- openspec change 归档（`/opsx:archive`）在合并前按 worktree 模式同款纪律执行（产物在分支上随 MR 合入）
+- openspec change 归档在合并前执行（产物在分支上随交付合入）
 - 全部仓库回 main 后向用户报告"本地模式已收尾，空间回到干净态"
 
 ## 升级 worktree（中途要并行 / 要隔离）
@@ -98,13 +130,13 @@ git -C "<仓库>" checkout main && git -C "<仓库>" pull && git -C "<仓库>" b
 | 场景 | 处理方式 |
 |------|----------|
 | 任何触发 | 先跑 Step 0 状态自检（clean 零交互 / active 用户四选一） |
-| 需求名 | 对话自由文本输入（禁 AskUserQuestion 收集自由文本） |
+| 需求名 | 对话输入：直接给名，或给需求描述（agent 推荐 3–5 个英文候选供选）；自由文本本身禁走 AskUserQuestion |
 | 涉及应用 | 需求语境提取子集，`--apps` 传入；中途补齐重跑（幂等） |
 | 切分支失败（dirty 冲突） | 报告详情，用户处理；禁止自动 stash |
 | commit 被 hook 拦（main 载荷） | 大声报错是预期行为：回分支重做；禁止自动 --no-verify |
 | 误在 main 检出上写了文件 | `git checkout -b <需求名>` 后改动随分支走；已 staged 则 unstage 后再切 |
 | 提交推送 | 说"提交并推送" → cbb-worktree-push（本地布局自动发现） |
-| 收尾 | 各仓库 checkout main + pull + 删分支；openspec 归档随 MR 合入 |
+| 收尾 | 收尾合并门禁（ADR 0007）：`merge-branches.js --check` 判已合并 → 全合并则各仓库 checkout main + pull + 删分支；否则三选一（MR / 直合并 `--allow-checkout` / 确认废弃） |
 | 要并行新需求 | 转 worktree 模式（init 分支从 origin/main 建，不占本地检出）；本地需求继续占用根 |
 | 升级隔离 | 重跑 cbb-worktree-init（提交随身带走）；先回 main 腾检出 |
 
@@ -148,11 +180,15 @@ git -C "<仓库>" checkout main && git -C "<仓库>" pull && git -C "<仓库>" b
 - 自动 stash 兜底切换失败（用户决策）
 - 同时承载第二个本地需求（并行走 worktree）
 - 把 `.codespace/<app>/` 的 main 检出当开发区（基准快照，本地模式只在分支上开发）
+- **未合并且未确认为废弃时收尾**（违反 ADR 0007 硬门禁）
+- 未经二次确认执行废弃重命名（远程重命名不可逆）
 
 **必须执行**
 
 - Step 0 自检 → clean 才开工
 - 布局展示 + 用户确认后才切分支
 - 切分支统一走 `start-local.js`（基线 = `<remote>/<main>`，不取 HEAD）
+- 收尾先过门禁判定（`merge-branches.js --check`）；未合并必须三选一后收尾
+- 直合并走 `merge-branches.js --allow-checkout`（本地检出需从需求分支切回主干）
 - 收尾三连（checkout main / pull / 删分支）完成后报告干净态
 - 所有写操作前的分支确认（当前检出 = 需求分支）