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

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

@@ -10,33 +10,27 @@ require('./silence-popup');
  * "由 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 <分支>] [--dry-run]
  *   node merge-branches.js <ws_root> <branch> [--apps a,b] [--target <分支>] --check   # 仅判定，不合并
  *
- * 目标分支：
- *   缺省 / --target 等于该仓库探测主干 → 主干快路径（本地主干检出上 merge --no-ff → push；
- *                                        检出未提交改动 autostash 让路，交付后自动恢复）
- *   --target 指定非主干分支：目标 == 当前检出 → 就地合并（同主干快路径处理）
- *                                        否则 → 临时 worktree（基于 origin/<target>，不动用户检出）
+ * 执行模型（统一"零接触"）：
+ *   目标 = 缺省探测主干或 --target 指定；每仓库在**临时 worktree**（基于 origin/<目标>，
+ *   远端缺失时退回本地 <目标>）中 merge --no-ff → push origin HEAD:<目标> → 清理。
+ *   合并全程不触碰本地检出：被其他需求占用（本地模式进行中）、有未提交改动（含未跟踪）
+ *   均不影响，不产生 stash、不切分支、不改本地主干 ref。代价：本地主干检出不随交付前移，
+ *   由下次 pull 追平（基准 = origin/<主干>，ADR 0002）。
  *
  * 模式：
  *   --check      逐仓库判定是否已合并到目标（主干含 release-* 中转 / squash / cherry-pick 兜底，
  *                算法与 cbb-worktree-close 的 safety-check.js 同源）；不修改任何状态
  *   默认         两阶段（ADR 0007）：
- *                  1. 预检：逐仓库校验（目标可解析 / 分支存在 / 主干不领先 origin）；
- *                     检出上未提交改动（含未跟踪）不再拦截——执行阶段自动暂存让路（autostash）
+ *                  1. 预检：逐仓库校验（目标可解析 / 分支存在 / 目标分支存在）
  *                     任一不过 → 退出 2，不执行任何合并
- *                  2. 执行：autostash（如有）→ checkout 目标 → pull --ff-only → merge --no-ff
- *                     → push → 自动恢复暂存；执行中失败 → 先恢复暂存再停止并报告已完成清单
- *                     （不回滚；重跑幂等）。恢复冲突时保留 stash 条目交用户决策
- *                     （"后提交者解决"：暂存侧改动适配已交付主干，agent 代解或用户手动二选一）
+ *                  2. 执行：临时 worktree 合并 → push；执行中失败 → 停止并报告已完成清单
+ *                     （不回滚；重跑幂等）
  *   --dry-run    只做预检，不执行
  *
- * 恢复机制取舍：先 pop --index（还原 staged 分区）；若其失败且有冲突，reset --hard 回到
- *   本次合并的 HEAD 后 plain apply 一次——保证冲突只"单次应用"落盘（双重应用风险为零），
- *   代价是冲突场景下 staged/unstaged 分区扁平化（内容无损）。ignored 文件不参与暂存。
- * 退出码：0 全部成功（含 skipped / merged）/ 1 参数错误 / 2 预检或执行失败（含 need-mr /
- *   unmerged / autostashPending——交付已完成，只是暂存未恢复，按 AUTOSTASH_PENDING 行处理）
+ * 退出码：0 全部成功（含 skipped / merged）/ 1 参数错误 / 2 预检或执行失败（含 need-mr / unmerged）
  * 末行：MERGE_RESULT [...] 或 MERGE_CHECK_RESULT [...]
  */
 
@@ -151,108 +145,17 @@ function cleanupTempWorktree(repoPath, tmpDir) {
   run('git worktree prune', repoPath);
 }
 
-// ── autostash 让路 / 恢复（检出上的未提交改动不阻断直合并，ADR 0008 扩展） ──
-
-/** 统计检出上未提交项（含未跟踪），仅用于预检输出注记；-1 = 状态不可读 */
-function countUncommitted(workPath) {
-  const s = run('git status --porcelain', workPath);
-  if (!s.ok) return -1;
-  return s.out ? s.out.split(/\r?\n/).filter(Boolean).length : 0;
-}
-
-/**
- * 暂存检出上的未提交改动（含未跟踪，不含 ignored），为合并让路。
- * 经 refs/stash 前后对比判断是否真的建了条目（无改动时 stash 不建条目）。
- * 返回 { ok, created, oid, stashId } 或 { ok: false, err }
- */
-function autostashPush(workPath, tag) {
-  const before = run('git rev-parse -q --verify "refs/stash"', workPath);
-  const stamp = new Date().toISOString().slice(0, 19).replace('T', ' ');
-  const msg = 'cbb-autostash ' + tag + ' [' + stamp + ']';
-  const push = run('git stash push --include-untracked -m "' + msg + '"', workPath);
-  if (!push.ok) return { ok: false, err: (push.err || push.out || 'stash push 失败').split(/\r?\n/)[0] };
-  const after = run('git rev-parse -q --verify "refs/stash"', workPath);
-  const oid = after.out || '';
-  return { ok: true, created: !!oid && oid !== (before.out || ''), oid, stashId: msg };
-}
-
-function conflictedPaths(workPath) {
-  const d = run('git diff --name-only --diff-filter=U', workPath);
-  return d.ok && d.out ? d.out.split(/\r?\n/).filter(Boolean) : [];
-}
-
-/**
- * 单次恢复尝试 + 分类。返回：
- *   { done }            完全恢复（pop 成功，或 apply 完整成功 + drop 成功）
- *   { conflicted }      冲突标记留在树里，stash 条目保留
- *   { dirty, files }    有改动但非标记冲突 / apply 异常部分应用——现场保留，交人工核对
- *   { preserved }       无法自动恢复且树未被污染（如未跟踪占位冲突）
- * 防双重应用：pop --index 失败可能留下"半应用"树（工作区改了、index 没还原），
- * 盲目 plain pop 会在半应用之上再应用一次。故失败后先 reset --hard 回到 HEAD，
- * 再 plain apply 一次（干净基线上的单次应用），结果只有"标记冲突"或"完整应用"两种。
- */
-function tryRestoreStash(workPath, idx) {
-  const ref = '"stash@{' + idx + '}"';
-  const pop = run('git stash pop --index ' + ref, workPath);
-  if (pop.ok) return { done: true };
-  const conflicted = conflictedPaths(workPath);
-  if (conflicted.length === 0) {
-    // 非冲突类失败（如未跟踪文件还原撞车）：树可能已被部分应用——如实分类，绝不谎报"未动"
-    const s = run('git status --porcelain --untracked-files=no', workPath);
-    if (s.ok && s.out) return { dirty: true, files: s.out.split(/\r?\n/).filter(Boolean) };
-    return { preserved: true };
-  }
-  // 有冲突标记：--index 的失败树状态不透明（半应用 + unmerged 索引，checkout -- 会拒绝）。
-  // 先 reset --hard 回到本次合并的 HEAD（用户改动安全躺在 stash 里），再 plain apply 一次，
-  // 让冲突以标准 stash-pop-conflict 形态单次落盘（标记 + 条目保留），杜绝双重应用。
-  const undo = run('git reset --hard --quiet', workPath);
-  if (!undo.ok) return { conflicted: true };
-  const apply = run('git stash apply ' + ref, workPath);
-  if (conflictedPaths(workPath).length > 0) return { conflicted: true };
-  if (!apply.ok) {
-    const s2 = run('git status --porcelain --untracked-files=no', workPath);
-    if (s2.ok && s2.out) return { dirty: true, files: s2.out.split(/\r?\n/).filter(Boolean) };
-    return { preserved: true };
-  }
-  // plain apply 完全成功（首轮失败仅因 --index 还原不了 staged 分区）：补 drop 收尾
-  const drop = run('git stash drop ' + ref, workPath);
-  if (drop.ok) return { done: true };
-  return { dirty: true, files: conflictedPaths(workPath) };
-}
-
-/**
- * 恢复 autostash。返回 { state, files?, note? }：
- *   none         未建条目，无需恢复
- *   restored     已完全恢复
- *   conflict     恢复冲突（标记在树里、条目保留）——后提交者解决，交用户决策
- *   dirty        apply 异常 / 部分应用——现场保留交人工核对
- *   preserved    无法自动恢复且树未被污染——条目保留交人工
- *   stash-moved  stash 顶层已非本次条目——绝不动别人的 stash，保留现场
- */
-function autostashPop(workPath, st) {
-  if (!st.ok || !st.created) return { state: 'none' };
-  const cur = run('git rev-parse -q --verify "refs/stash"', workPath);
-  if (!cur.ok || cur.out !== st.oid) {
-    return { state: 'stash-moved', note: 'stash 顶层条目非本次自动暂存（' + st.stashId + '），未自动恢复' };
-  }
-  const list = run('git stash list', workPath);
-  const top = list.ok ? (list.out.split(/\r?\n/)[0] || '') : '';
-  const m = top.match(/^stash@\{(\d+)\}/);
-  if (!m) return { state: 'preserved', note: 'stash 列表解析失败（' + st.stashId + '）' };
-  const r = tryRestoreStash(workPath, m[1]);
-  if (r.done) return { state: 'restored' };
-  if (r.conflicted) return { state: 'conflict', files: conflictedPaths(workPath), note: '条目保留：' + top };
-  if (r.dirty) return { state: 'dirty', files: r.files, note: '条目保留：' + top };
-  return { state: 'preserved', note: '条目保留：' + top };
-}
-
 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]');
+    console.error('Usage: node merge-branches.js <ws_root> <branch> [--apps a,b] [--target b] [--dry-run] [--check]');
+    process.exit(1);
+  }
+  if (args.includes('--allow-checkout')) {
+    console.error('--allow-checkout 已退役：合并统一走临时 worktree，不触碰本地检出');
     process.exit(1);
   }
 
@@ -266,7 +169,6 @@ function main() {
     console.error('--target 需要提供分支名');
     process.exit(1);
   }
-  const allowCheckout = args.includes('--allow-checkout');
   const dryRun = args.includes('--dry-run');
   const checkOnly = args.includes('--check');
 
@@ -314,7 +216,7 @@ function main() {
   // ── 阶段 1：预检 ──────────────────────────────────────────
   const prechecks = [];
   for (const rp of repos) {
-    const rec = { name: rp.name, status: 'ok', main: null, target: null, temp: false, reason: null, uncommitted: 0 };
+    const rec = { name: rp.name, status: 'ok', main: null, target: null, reason: null };
     if (!fs.existsSync(path.join(rp.repo, '.git'))) {
       rec.status = 'skipped';
       rec.reason = 'no-repo';
@@ -354,45 +256,15 @@ function main() {
       continue;
     }
 
-    if (target === main) {
-      // 主干路径（快路径，与 ADR 0007 收尾门禁一致）
-      if (mergedToMain(rp.repo, branch, main)) {
-        rec.status = 'skipped';
-        rec.reason = 'already-merged';
-        prechecks.push(rec);
-        continue;
-      }
-      // 检出脏不再拦截：记录未提交项数，执行阶段 autostash 让路、合并后恢复（ADR 0008 扩展）
-      rec.uncommitted = countUncommitted(rp.work);
-      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 {
-      // 指定分支路径：已合并则跳过；当前检出即目标 → 就地（autostash）；否则临时 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) {
-        // 就地合并：同主干快路径，检出脏不拦截，执行阶段 autostash 让路 / 恢复
-        rec.uncommitted = countUncommitted(rp.work);
-      } else {
-        rec.temp = true; // 执行阶段创建临时 worktree（基于 origin/<target>，不碰用户检出）
-      }
+    // 合并一律走临时 worktree（零接触本地检出）：预检不看检出分支与脏状态
+    const merged = (!targetArg || target === main)
+      ? mergedToMain(rp.repo, branch, main)
+      : mergedToTarget(rp.repo, branch, target);
+    if (merged) {
+      rec.status = 'skipped';
+      rec.reason = 'already-merged';
+      prechecks.push(rec);
+      continue;
     }
     prechecks.push(rec);
   }
@@ -401,11 +273,7 @@ function main() {
   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 {
-      let note = p.temp ? '（临时 worktree）' : '';
-      if (!p.temp && p.uncommitted > 0) note += '（检出有 ' + p.uncommitted + ' 项未提交改动，将自动暂存、合并后恢复）';
-      console.log('OK   ' + p.name + ' → 合并至 ' + p.target + note);
-    }
+    else console.log('OK   ' + p.name + ' → 合并至 ' + p.target + '（临时 worktree，不碰本地检出）');
   });
 
   if (hasPrecheckFailure) {
@@ -435,141 +303,63 @@ function main() {
 
     const target = p.target;
     const mergeMsg = "Merge branch '" + branch + "'";
-    let st = null; // autostash 句柄（仅主干 / 就地路径建）
-    // 统一出口：凡建过暂存，离开本仓库前必恢复；恢复未完全 → autostashPending（退出码 2 交用户决策）
-    const finish = (status, detail) => {
-      let pending = false;
-      if (st) {
-        const pr = autostashPop(rp.work, st);
-        if (pr.state !== 'none' && pr.state !== 'restored') {
-          pending = true;
-          detail += '; autostash-' + pr.state +
-            (pr.files && pr.files.length ? ' [' + pr.files.join(', ') + ']' : '') +
-            (pr.note ? ' ' + pr.note : '');
-        }
-      }
-      results[i].status = status;
-      results[i].detail = detail;
-      results[i].autostashPending = pending;
-      if (status !== 'merged' && status !== 'skipped') stopped = true;
-    };
 
-    if (target === p.main) {
-      // ── 主干路径（快路径）：检出未提交改动 autostash 让路，交付后自动恢复 ──
-      st = autostashPush(rp.work, 'merge-' + branch + '-into-' + target);
-      if (!st.ok) {
-        finish('failed', 'autostash-failed: ' + st.err);
-        continue;
-      }
-      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) {
-          finish('failed', 'checkout-failed: ' + co.err.split(/\r?\n/)[0]);
-          continue;
-        }
-      }
-      const pull = run('git pull --ff-only --quiet origin "' + target + '"', rp.repo);
-      if (!pull.ok) {
-        finish('failed', 'pull-failed: ' + pull.err.split(/\r?\n/)[0]);
-        continue;
-      }
-      const merge = run('git merge --no-ff -m "' + mergeMsg + '" "' + branch + '"', rp.repo);
-      if (!merge.ok) {
-        run('git merge --abort', rp.repo);
-        finish('failed', 'merge-failed: ' + merge.err.split(/\r?\n/)[0]);
-        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') {
-            finish('need-mr', 'branch-protected（目标分支受保护，请改用 MR 出口）');
-          } else {
-            finish('failed', 'push-failed: ' + (push.err || '').split(/\r?\n/)[0]);
-          }
-          continue;
-        }
-      }
-      finish('merged', 'merged+pushed origin/' + target);
+    // ── 统一临时 worktree：基于 origin/<target>（远端缺失退回本地 <target>），零接触本地检出 ──
+    const 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;
     }
 
-    // ── 指定分支路径（当前检出即目标 → 就地 + autostash；否则临时 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) {
-        finish('failed', 'worktree-add-failed: ' + add.err.split(/\r?\n/)[0]);
-        continue;
-      }
-      workDir = tmpDir;
-    } else {
-      st = autostashPush(rp.work, 'merge-' + branch + '-into-' + target);
-      if (!st.ok) {
-        finish('failed', 'autostash-failed: ' + st.err);
-        continue;
-      }
-      const pull = run('git pull --ff-only --quiet origin "' + target + '"', rp.repo);
-      if (!pull.ok) {
-        finish('failed', 'pull-failed: ' + pull.err.split(/\r?\n/)[0]);
-        continue;
-      }
-    }
-
-    const merge = run('git merge --no-ff -m "' + mergeMsg + '" "' + branch + '"', workDir);
+    const merge = run('git merge --no-ff -m "' + mergeMsg + '" "' + branch + '"', tmpDir);
     if (!merge.ok) {
-      run('git merge --abort', workDir);
+      run('git merge --abort', tmpDir);
       cleanupTempWorktree(rp.repo, tmpDir);
-      finish('failed', 'merge-failed: ' + merge.err.split(/\r?\n/)[0]);
+      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);
+    let push = run('git push origin "HEAD:refs/heads/' + target + '"', tmpDir);
     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);
+        const retry = run('git fetch --quiet origin "' + target + '" && git reset --hard FETCH_HEAD', tmpDir);
         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);
+          const rem = run('git merge --no-ff -m "' + mergeMsg + '" "' + branch + '"', tmpDir);
+          if (rem.ok) push = run('git push origin "HEAD:refs/heads/' + target + '"', tmpDir);
         }
       }
       if (!push.ok) {
         const code2 = classifyPushError(push.err);
         cleanupTempWorktree(rp.repo, tmpDir);
         if (code2 === 'branch-protected') {
-          finish('need-mr', 'branch-protected（目标分支受保护，请改用 MR 出口）');
+          results[i].status = 'need-mr';
+          results[i].detail = 'branch-protected（目标分支受保护，请改用 MR 出口）';
         } else {
-          finish('failed', 'push-failed: ' + (push.err || '').split(/\r?\n/)[0]);
+          results[i].status = 'failed';
+          results[i].detail = 'push-failed: ' + (push.err || '').split(/\r?\n/)[0];
         }
+        stopped = true;
         continue;
       }
     }
     cleanupTempWorktree(rp.repo, tmpDir);
-    finish('merged', 'merged+pushed origin/' + target + (tmpDir ? '（临时 worktree）' : ''));
+    results[i].status = 'merged';
+    results[i].detail = 'merged+pushed origin/' + target + '（临时 worktree，本地检出一分未动）';
   }
 
   results.forEach(r => {
     console.log(r.status.toUpperCase() + ' ' + r.name + (r.detail ? ' — ' + r.detail : ''));
-    if (r.autostashPending) {
-      console.log('AUTOSTASH_PENDING ' + r.name + ': 暂存的未提交改动未自动恢复（stash 条目保留）——列冲突点，用户二选一：agent 解决 / 手动解决（协议见 SKILL 解读）');
-    }
   });
 
-  // autostashPending 按失败退出：交付可能已完成，但用户改动还挂在 stash，必须决策处理后重跑确认
-  const ok = results.every(r => (r.status === 'merged' || r.status === 'skipped') && !r.autostashPending);
+  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);
@@ -577,4 +367,4 @@ function main() {
 
 if (require.main === module) main();
 
-module.exports = { run, detectMain, mergedTo, mergedToMain, mergedToTarget, classifyPushError, loadApps, buildRepos, autostashPush, autostashPop };
+module.exports = { run, detectMain, mergedTo, mergedToMain, mergedToTarget, classifyPushError, loadApps, buildRepos };

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

@@ -15,7 +15,7 @@ description: "业务空间本地模式开发：空间根与各涉及应用在 .c
 - **基准 = `origin/main`（唯一真相源）；`.codespace/<app>/` 的检出 = 视图**：本地模式暂态占用视图合法；main 检出是基准快照，**严禁直接在 main 检出上提交**（pre-commit hook 会拦）
 - **一次只承载一个需求**：本地模式独占空间根与各 app 的本地检出；期间并行新需求只能走 worktree 模式（两模式互不干扰，worktree 分支从 `origin/main` 建，不依赖本地检出状态）
 - **提交防线在 hook**：分支感知 pre-commit hook 拦截一切 main 上的载荷提交（workspace 白名单外 / 应用全拦；merge 提交放行）；被拦 = 大声失败，按指引回分支，**禁止自动 `--no-verify` 绕过**
-- **收尾合并门禁（ADR 0007，与 worktree 模式对称）**：收尾前每个参与仓库必须为"已合并"，未合并时三选一——**提 MR** / **直合并**（`merge-branches.js --allow-checkout`）/ **确认废弃**（远程重命名 `<需求名>-deprecated`）。**硬门禁：未合并且非废弃一律不允许收尾**
+- **收尾合并门禁（ADR 0007，与 worktree 模式对称）**：收尾前每个参与仓库必须为"已合并"，未合并时三选一——**提 MR** / **直合并**（`merge-branches.js`，临时 worktree 零接触）/ **确认废弃**（远程重命名 `<需求名>-deprecated`）。**硬门禁：未合并且非废弃一律不允许收尾**
 - 所有原子操作封装为 `scripts/*.js`（跨平台 Node.js），调用方式与 worktree 三件套一致：`node "<skill_dir>/scripts/<name>.js" <参数>`，cwd 保持空间根
 
 ---
@@ -95,13 +95,13 @@ node "<skill_dir>/scripts/merge-branches.js" "<ws_root>" "<需求名>" --apps "<
 **5.3 门禁三选一**（`AskUserQuestion`，同 close Step 3.4）：
 
 - **提 MR** → **中止收尾**，引导用户运行 `cbb-worktree-push`（说"提交并推送"）生成 MR 预填链接（其 Step 7：目标分支候选交互 + `make-mr-urls.js`）→ 合并完重跑本步
-- **直合并** → `merge-branches.js`（本地检出被需求分支占用，**必须加 `--allow-checkout`** 切回主干）：
+- **直合并** → `merge-branches.js`（临时 worktree 合并，**不碰本地检出**——被需求分支占用也无需处理；交付后本地主干检出不随之前移，由 5.4 的 checkout main + pull 追平）：
 
   ```bash
-  node "<skill_dir>/scripts/merge-branches.js" "<ws_root>" "<需求名>" --apps "<app1,app2>" --allow-checkout
+  node "<skill_dir>/scripts/merge-branches.js" "<ws_root>" "<需求名>" --apps "<app1,app2>"
   ```
 
-  `need-mr`（远端主干受保护）→ 改用提 MR；`failed` → 输出明细、修复后重跑；`AUTOSTASH_PENDING`（`MERGED` 但退出码 2）→ 交付已完成，仅暂存恢复遇冲突——**本地模式的改动会被恢复到已合入需求的 trunk 上（基线已变，冲突概率高于 worktree 模式）**，列冲突点问用户二选一（agent 解决 / 手动解决，协议同 close 出口二），处理前不得 drop stash
+  `need-mr`（远端主干受保护）→ 改用提 MR；`failed` → 输出明细、修复后重跑
 - **确认废弃** → `deprecate-branches.js`（远程重命名 `<需求名>-deprecated`；本地分支保留原名）
 
 **5.4 交付完成 → 各仓库回主干并删分支**：
@@ -136,7 +136,7 @@ node "<skill_dir>/scripts/delete-branches.js" "<ws_root>" "<需求名>" local_re
 | commit 被 hook 拦（main 载荷） | 大声报错是预期行为：回分支重做；禁止自动 --no-verify |
 | 误在 main 检出上写了文件 | `git checkout -b <需求名>` 后改动随分支走；已 staged 则 unstage 后再切 |
 | 提交推送 | 说"提交并推送" → cbb-worktree-push（本地布局自动发现） |
-| 收尾 | 收尾合并门禁（ADR 0007）：`merge-branches.js --check` 判已合并 → 全合并则各仓库 checkout main + pull + 删分支；否则三选一（MR / 直合并 `--allow-checkout` / 确认废弃） |
+| 收尾 | 收尾合并门禁（ADR 0007）：`merge-branches.js --check` 判已合并 → 全合并则各仓库 checkout main + pull + 删分支；否则三选一（MR / 直合并（临时 worktree） / 确认废弃） |
 | 要并行新需求 | 转 worktree 模式（init 分支从 origin/main 建，不占本地检出）；本地需求继续占用根 |
 | 升级隔离 | 重跑 cbb-worktree-init（提交随身带走）；先回 main 腾检出 |
 
@@ -189,6 +189,6 @@ node "<skill_dir>/scripts/delete-branches.js" "<ws_root>" "<需求名>" local_re
 - 布局展示 + 用户确认后才切分支
 - 切分支统一走 `start-local.js`（基线 = `<remote>/<main>`，不取 HEAD）
 - 收尾先过门禁判定（`merge-branches.js --check`）；未合并必须三选一后收尾
-- 直合并走 `merge-branches.js --allow-checkout`（本地检出需从需求分支切回主干）
+- 直合并走 `merge-branches.js`（临时 worktree，零接触；本地检出由 5.4 收尾三连切回主干）
 - 收尾三连（checkout main / pull / 删分支）完成后报告干净态
 - 所有写操作前的分支确认（当前检出 = 需求分支）