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

package/cbb/dev-standards/rules/cbb-workspace-discipline.md

@@ -10,7 +10,7 @@ trigger: always_on
 
 - 就地切分支：根 + 各涉及应用 `.codespace/<app>/` 同名 `checkout -b`（基线 = `origin/<main>`，经 `cbb-local-mode` 技能执行）
 - 当前会话原地开发，相对路径原样生效；**一次只承载一个需求**（独占本地检出；期间并行新需求走 worktree 模式，互不干扰）
-- 收尾（收尾合并门禁，ADR 0007）：`merge-branches.js --check` 判定已合并；未合并须三选一（提 MR / 直合并 `--allow-checkout` / 确认废弃）后方可收尾；各参与仓库 `checkout main && pull && 删分支`
+- 收尾（收尾合并门禁，ADR 0007）：`merge-branches.js --check` 判定已合并；未合并须三选一（提 MR / 直合并（临时 worktree 零接触，ADR 0008） / 确认废弃）后方可收尾；交付完成后各参与仓库回主干并删分支（`return-to-trunk.js` + `delete-branches.js`，主干名经远端 HEAD 探测，兼容 main / master）
 
 **模式二 · worktree 模式（并行 / 隔离）：**
 

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

@@ -9,9 +9,17 @@ require('./silence-popup');
  *
  * 用法：
  *   node deprecate-branches.js <ws_root> <branch> [--apps a,b]
+ *   node deprecate-branches.js <ws_root> <branch> [--apps a,b] --check   # 仅检查，不重命名
+ *
+ * 模式：
+ *   --check      只读检查：逐仓库报远端分支存在性与本地未推送提交数
+ *                （ls-remote 取远端权威 hash 与本地 <branch> 比对）。
+ *                用途：废弃重命名只覆盖远端已推送的部分——本地 ahead 提交
+ *                不会被带进 <branch>-deprecated，执行前须提示用户决策。
+ *   默认         执行远端重命名 <branch> → <branch>-deprecated
  *
  * 退出码：0 全部成功（含 skipped）/ 1 参数错误 / 2 存在失败
- * 末行：DEPRECATE_RESULT [...]
+ * 末行：DEPRECATE_RESULT [...] 或 DEPRECATE_CHECK_RESULT [...]
  */
 
 const { execSync } = require('child_process');
@@ -44,6 +52,51 @@ function loadApps(wsRoot) {
   }
 }
 
+/**
+ * 检查单个仓库（--check，只读）：
+ *   unpushed: 0 = 已全部推送；>0 = 本地领先远端 N 个提交；'all' = 远端无该分支（提交全部未推送）
+ */
+function checkRepo(name, repo, branch) {
+  const rec = { name, status: 'skipped', remote_exists: false, unpushed: 0, 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];
+  if (!run('git rev-parse --verify --quiet "refs/heads/' + branch + '"', repo).ok) {
+    rec.detail = 'no-local-branch';
+    return rec;
+  }
+  const ls = run('git ls-remote --heads "' + r + '" "refs/heads/' + branch + '"', repo);
+  if (!ls.ok) {
+    rec.status = 'failed';
+    rec.detail = 'ls-remote-failed';
+    return rec;
+  }
+  if (!ls.out) {
+    rec.status = 'ok';
+    rec.unpushed = 'all';
+    rec.detail = 'remote-has-no-branch';
+    return rec;
+  }
+  const remoteHash = ls.out.split(/\r?\n/)[0].split(/\s+/)[0];
+  const cnt = run('git rev-list --count "' + remoteHash + '..refs/heads/' + branch + '"', repo);
+  if (!cnt.ok) {
+    rec.status = 'failed';
+    rec.detail = 'rev-list-failed';
+    return rec;
+  }
+  rec.status = 'ok';
+  rec.remote_exists = true;
+  rec.unpushed = parseInt(cnt.out, 10) || 0;
+  return rec;
+}
+
 /** 对单个仓库执行废弃重命名 */
 function deprecateRepo(name, repo, branch) {
   const newName = branch + '-deprecated';
@@ -95,6 +148,7 @@ function main() {
   const appFilter = appsIdx >= 0
     ? new Set((args[appsIdx + 1] || '').split(',').map(s => s.trim()).filter(Boolean))
     : null;
+  const checkOnly = args.includes('--check');
 
   const repos = [{ name: 'workspace', repo: wsRoot }];
   for (const app of loadApps(wsRoot)) {
@@ -102,6 +156,17 @@ function main() {
     repos.push({ name: app.name, repo: path.join(wsRoot, '.codespace', app.name) });
   }
 
+  if (checkOnly) {
+    const results = repos.map(rp => checkRepo(rp.name, rp.repo, branch));
+    results.forEach(r => {
+      const up = r.status === 'ok' && r.unpushed !== 0 ? ' [unpushed: ' + r.unpushed + ']' : '';
+      console.log(r.status.toUpperCase() + ' ' + r.name + (r.detail ? ' — ' + r.detail : '') + up);
+    });
+    console.log('---');
+    console.log('DEPRECATE_CHECK_RESULT', JSON.stringify({ branch, results }));
+    process.exit(results.some(r => r.status === 'failed') ? 2 : 0);
+  }
+
   const results = repos.map(rp => deprecateRepo(rp.name, rp.repo, branch));
 
   results.forEach(r => {
@@ -116,4 +181,4 @@ function main() {
 
 if (require.main === module) main();
 
-module.exports = { run, loadApps, deprecateRepo };
+module.exports = { run, loadApps, checkRepo, deprecateRepo };

package/cbb/worktrees/_shared/scripts/return-to-trunk.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * 收尾回主干 —— 交付完成后把各参与仓库的本地检出切回主干并追平（ADR 0007 / 0008）
+ *
+ * 背景：merge-branches.js 统一零接触通道后，合并在临时 worktree 内完成、
+ * 不触碰本地检出（本地主干检出不随交付前移）。本地模式收尾需把各仓库
+ * 本地检出从需求分支切回主干——本脚本替代曾经写死 `git checkout main`
+ * 的裸命令：主干名逐仓库经远端 HEAD 探测（与 check-local-state.js 同源，
+ * 兼容 master 等），不再假设主干叫 main。
+ *
+ * 用法：
+ *   node return-to-trunk.js <ws_root> [--apps a,b] [--dry-run]
+ *
+ * 行为（逐仓库，相互独立、失败不停链）：
+ *   1. 目录无 .git → SKIP no-repo
+ *   2. git fetch --quiet origin（失败仅降级，后续判定退回本地主干）
+ *   3. 主干名 detectMain：远端 HEAD → 本地 main → 本地 master → origin/main → origin/master
+ *      → FAIL cannot-detect-main
+ *   4. 当前检出 ≠ 主干：
+ *      - 检出 dirty（含未跟踪）→ FAIL dirty-worktree（列未提交项数；不自动 stash，交用户决策）
+ *      - 本地有主干分支 → git checkout <主干>；仅远端有 → git checkout -b <主干> --track origin/<主干>
+ *   5. 追平远端：origin/<主干> 存在 → git pull --ff-only origin <主干>
+ *      （成功详情注记 `pulled origin/<主干>` / `up-to-date`；本地主干与 origin 分叉 → FAIL
+ *      pull-failed，交用户决策；远端无主干 → 注记跳过）
+ *   6. 已在主干 → 跳过切回，仍追平（幂等）
+ *
+ * 退出码：0 全部成功（含 no-repo / 已在主干）/ 1 参数错误 / 2 任一仓库失败
+ * 末行：TRUNK_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 hasRef(repoPath, ref) {
+  return run('git rev-parse --verify --quiet "' + ref + '"', repoPath).ok;
+}
+
+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 [];
+  }
+}
+
+/** 主干名：symbolic-ref 远端 HEAD → 本地 main/master → 远端跟踪 origin/main|master → 空串（与 check-local-state.js 同源，回退链更强） */
+function detectMain(repoPath) {
+  const remote = run('git remote', repoPath);
+  if (remote.ok && remote.out) {
+    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 + '/', '');
+  }
+  if (hasRef(repoPath, 'refs/heads/main')) return 'main';
+  if (hasRef(repoPath, 'refs/heads/master')) return 'master';
+  if (hasRef(repoPath, 'refs/remotes/origin/main')) return 'main';
+  if (hasRef(repoPath, 'refs/remotes/origin/master')) return 'master';
+  return '';
+}
+
+/** 检出未提交项数（含未跟踪，不含 ignored）；-1 = 状态不可读 */
+function countUncommitted(repoPath) {
+  const s = run('git status --porcelain', repoPath);
+  if (!s.ok) return -1;
+  return s.out ? s.out.split(/\r?\n/).filter(Boolean).length : 0;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const wsRoot = args[0];
+  if (!wsRoot || wsRoot.indexOf('--') === 0) {
+    console.error('Usage: node return-to-trunk.js <ws_root> [--apps a,b] [--dry-run]');
+    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 dryRun = args.includes('--dry-run');
+
+  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 = [];
+  let failed = false;
+
+  for (const rp of repos) {
+    const rec = { name: rp.name, status: 'ok', main: null, switched: false, uncommitted: 0, reason: null, detail: 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';
+      rec.reason = 'cannot-detect-main';
+      results.push(rec);
+      failed = true;
+      continue;
+    }
+    rec.main = main;
+    rec.uncommitted = countUncommitted(rp.repo);
+    const current = run('git branch --show-current', rp.repo);
+
+    if (current.ok && current.out !== main) {
+      // detached（out 为空）也需切回——「不在主干」含 detached
+      if (dryRun) {
+        rec.reason = 'would-switch (from ' + current.out + ')';
+        results.push(rec);
+        continue;
+      }
+      if (rec.uncommitted > 0) {
+        rec.status = 'failed';
+        rec.reason = 'dirty-worktree';
+        rec.detail = '检出 ' + current.out + ' 上有 ' + rec.uncommitted + ' 项未提交改动，不自动 stash——先处理再重跑';
+        results.push(rec);
+        failed = true;
+        continue;
+      }
+      const co = hasRef(rp.repo, 'refs/heads/' + main)
+        ? run('git checkout --quiet "' + main + '"', rp.repo)
+        : run('git checkout -b "' + main + '" --track origin/' + main, rp.repo);
+      if (!co.ok) {
+        rec.status = 'failed';
+        rec.reason = 'checkout-failed';
+        rec.detail = (co.err || '').split(/\r?\n/)[0];
+        results.push(rec);
+        failed = true;
+        continue;
+      }
+      rec.switched = true;
+    } else if (dryRun) {
+      rec.reason = 'already-on-trunk';
+      results.push(rec);
+      continue;
+    }
+
+    if (hasRef(rp.repo, 'refs/remotes/origin/' + main)) {
+      const before = run('git rev-parse --quiet HEAD', rp.repo);
+      const pull = run('git pull --ff-only --quiet origin "' + main + '"', rp.repo);
+      if (!pull.ok) {
+        rec.status = 'failed';
+        rec.reason = 'pull-failed';
+        rec.detail = (pull.err || '').split(/\r?\n/)[0];
+        failed = true;
+      } else {
+        const after = run('git rev-parse --quiet HEAD', rp.repo);
+        rec.detail = before.ok && after.ok && before.out !== after.out
+          ? 'pulled origin/' + main
+          : 'up-to-date';
+      }
+    } else if (!rec.reason) {
+      rec.reason = 'no-remote-trunk';
+    }
+    results.push(rec);
+  }
+
+  results.forEach(r => {
+    console.log(r.status.toUpperCase() + ' ' + r.name + (r.main ? ' → ' + r.main : '') + (r.reason ? ': ' + r.reason : '') + (r.detail ? ' — ' + r.detail : ''));
+  });
+  console.log('---');
+  console.log('TRUNK_RESULT', JSON.stringify({ results }));
+  process.exit(failed ? 2 : 0);
+}
+
+if (require.main === module) main();

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

@@ -1,6 +1,6 @@
 ---
 name: cbb-local-mode
-description: "业务空间本地模式开发：空间根与各涉及应用在 .codespace/<app>/ 就地建同名分支，当前会话直接开发（不建 worktree、不换目录）。触发：用户说'本地模式'/'就地开发'/'不走 worktree'/'在这个窗口开发'，或双模式选择时用户选本地模式。覆盖开工（状态自检→布局确认→切分支）、开发、提交推送（转 cbb-worktree-push）、收尾（收尾合并门禁 ADR 0007：MR / 直合并 / 确认废弃后回 main + 删分支）、升级 worktree（重跑 cbb-worktree-init）。一次只承载一个需求。"
+description: "业务空间本地模式开发：空间根与各涉及应用在 .codespace/<app>/ 就地建同名分支，当前会话直接开发（不建 worktree、不换目录）。触发：用户说'本地模式'/'就地开发'/'不走 worktree'/'在这个窗口开发'，或双模式选择时用户选本地模式。覆盖开工（状态自检→布局确认→切分支）、开发、提交推送（转 cbb-worktree-push）、收尾（收尾合并门禁 ADR 0007：MR / 直合并 / 确认废弃；交付完成回主干 + 删分支，废弃保留本地分支）、升级 worktree（重跑 cbb-worktree-init）。一次只承载一个需求。"
 ---
 
 # Local Mode（本地模式）
@@ -88,40 +88,77 @@ MR 合并、验收通过后回到本会话收尾。**与 worktree 模式同门
 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
+- 解读末行 `MERGE_CHECK_RESULT`：每仓库 `merged`（含 `origin/main` / `main-via-release-*`）/ `unmerged` / `no-branch`（该仓库无此本地分支，不参与放行）/ `no-repo`（目录缺失，不参与放行）/ `failed`（主干探测或 fetch 失败）
+- 全部 `merged` / `no-branch` / `no-repo`（退出码 0）→ 直接进 5.4
+- 存在 `unmerged`（退出码 2 且状态为 `unmerged`）→ 进 5.3
+- 存在 `failed`（退出码 2，**与 `unmerged` 撞码，先看状态再行动**）→ 这不是"未合并"：报告失败仓库与原因（`cannot-detect-main` / `fetch-failed`），修复环境（远端可达性 / 远端默认分支设置）后重跑 5.2；**禁止按未合并走 5.3 门禁**
 
 **5.3 门禁三选一**（`AskUserQuestion`，同 close Step 3.4）：
 
 - **提 MR** → **中止收尾**，引导用户运行 `cbb-worktree-push`（说"提交并推送"）生成 MR 预填链接（其 Step 7：目标分支候选交互 + `make-mr-urls.js`）→ 合并完重跑本步
-- **直合并** → `merge-branches.js`（临时 worktree 合并，**不碰本地检出**——被需求分支占用也无需处理；交付后本地主干检出不随之前移，由 5.4 的 checkout main + pull 追平）：
+- **直合并** → `merge-branches.js`（临时 worktree 合并，**不碰本地检出**——被需求分支占用也无需处理；交付后本地主干检出不随之前移，由 5.4 的 `return-to-trunk.js` 追平）：
 
   ```bash
   node "<skill_dir>/scripts/merge-branches.js" "<ws_root>" "<需求名>" --apps "<app1,app2>"
   ```
 
   `need-mr`（远端主干受保护）→ 改用提 MR；`failed` → 输出明细、修复后重跑
-- **确认废弃** → `deprecate-branches.js`（远程重命名 `<需求名>-deprecated`；本地分支保留原名）
+- **确认废弃** → 三步：检查未推送提交 → 二次确认 → 执行。**废弃后仍进 5.4 步骤 1 回主干，但跳过步骤 2（本地分支保留原名，不调用 `delete-branches.js`）**。
 
-**5.4 交付完成 → 各仓库回主干并删分支**：
+  1. 检查未推送提交（废弃重命名只覆盖远端已推送的部分，本地 ahead 提交不会进 `<需求名>-deprecated`）：
+
+  ```bash
+  node "<skill_dir>/scripts/deprecate-branches.js" "<ws_root>" "<需求名>" --apps "<app1,app2>" --check
+  ```
+
+  **解读末行 `DEPRECATE_CHECK_RESULT`**：每仓库 `unpushed`（本地领先远端的提交数；`all` = 远端无该分支、提交全部未推送；`0` = 已全部推送）。存在 `unpushed > 0` / `all` 时用 `AskUserQuestion`：
+
+  ```
+  ⚠️ 以下仓库存在未推送提交（将只保留在本地分支，不进 <需求名>-deprecated）：
+    - workspace: 3 个 commit
+
+  请选择处理方式：
+    [先推送]（推荐）调 cbb-worktree-push 推送全部提交后回到本步
+    [继续]            不推送直接废弃（这些提交只存在于被保留的本地分支）
+    [中止]            终止流程，我先手动处理
+  ```
+
+  2. 二次确认（远程重命名不可逆，`AskUserQuestion` 固定选项）：确认废弃 / 中止
+  3. 执行：
+
+  ```bash
+  node "<skill_dir>/scripts/deprecate-branches.js" "<ws_root>" "<需求名>" --apps "<app1,app2>"
+  ```
+
+  `failed` → 报告并终止；完成后进 5.4（**仅步骤 1**）
+
+**5.4 交付完成 → 各仓库回主干并删分支**（脚本化；主干名逐仓库经远端 HEAD 探测，兼容 main / master。**废弃出口仅执行步骤 1**——分支保留、不删）：
+
+1. 各仓库切回主干并追平远端（替代原裸 git 三连；不自动 stash，失败即报告）：
 
 ```bash
-git -C "<仓库>" checkout main && git -C "<仓库>" pull && git -C "<仓库>" branch -d "<需求名>"
+node "<skill_dir>/scripts/return-to-trunk.js" "<ws_root>" --apps "<app1,app2>"
 ```
 
-- 各仓库本地分支删除后，远程分支删除由共享脚本完成（删除前输出将删清单）：
+**解读末行 `TRUNK_RESULT`**：
+- 退出码 0 → 全部已回主干并追平（detail 注记 `pulled origin/<主干>` = 本次有追平；`up-to-date` = 本就最新）
+- 某仓库 `dirty-worktree` → 检出上有未提交改动（回归 5.1 前置，先处理再重跑）；**不自动 stash**
+- 某仓库 `pull-failed`（本地主干与 origin 分叉）→ 输出详情，交用户决策
+- 某仓库 `cannot-detect-main` → 检查该仓库远端与主干分支（`fetch-failed` 同理）
+- 幂等：已在主干的仓库仅追平远端，重复执行无害
+
+2. 本地 + 远程需求分支删除（**仅交付完成出口执行**——MR 已合入 / 直合并成功；**废弃出口跳过本步**，本地分支保留原名。本地删除含 squash 合并的 `-d` → `-D` 兜底；删除前输出将删清单）：
 
 ```bash
 node "<skill_dir>/scripts/delete-branches.js" "<ws_root>" "<需求名>" local_remote
 ```
-- `checkout` 被 hook 拦（说明 main 落后或本地 main 有分叉）→ 先 `pull --ff-only`，再删分支
+
 - openspec change 归档在合并前执行（产物在分支上随交付合入）
-- 全部仓库回 main 后向用户报告"本地模式已收尾，空间回到干净态"
+- 全部仓库回主干（交付完成出口含分支删除）后，向用户报告"本地模式已收尾，空间回到干净态"
 
 ## 升级 worktree（中途要并行 / 要隔离）
 
-**直接重跑 `cbb-worktree-init`（幂等）**：分支已存在自动复用（reused），worktree 从分支创建——本地阶段的提交**随身带走**，零成本升级。升级前提：本地检出先回 main（`git checkout main`，未提交改动先 commit 或用户决策），否则 worktree 检出与本地检出冲突。
+**直接重跑 `cbb-worktree-init`（幂等）**：分支已存在自动复用（reused），worktree 从分支创建——本地阶段的提交**随身带走**，零成本升级。升级前提：本地检出先回主干（跑 5.4 的 `return-to-trunk.js`，主干名以远端 HEAD 为准；未提交改动先 commit 或用户决策），否则 worktree 检出与本地检出冲突。
 
 ---
 
@@ -136,9 +173,9 @@ 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 / 直合并（临时 worktree） / 确认废弃） |
+| 收尾 | 收尾合并门禁（ADR 0007）：`merge-branches.js --check` 判已合并 → 全合并则 `return-to-trunk.js` 回主干 + `delete-branches.js` 删分支（主干名探测）；否则三选一（MR / 直合并（临时 worktree） / 确认废弃（仅回主干不删分支）） |
 | 要并行新需求 | 转 worktree 模式（init 分支从 origin/main 建，不占本地检出）；本地需求继续占用根 |
-| 升级隔离 | 重跑 cbb-worktree-init（提交随身带走）；先回 main 腾检出 |
+| 升级隔离 | 重跑 cbb-worktree-init（提交随身带走）；先回主干腾检出（return-to-trunk.js） |
 
 ---
 
@@ -161,8 +198,13 @@ node "<skill_dir>/scripts/delete-branches.js" "<ws_root>" "<需求名>" local_re
 
 ### 收尾忘记 pull
 
-- **问题：** `checkout main` 后直接删分支，本地 main 陈旧，下次 `start-local` 从旧基线建分支
-- **修复：** 收尾固定三连：checkout main && pull && branch -d
+- **问题：** 回主干后未追平远端，本地主干陈旧，下次 `start-local` 从旧基线建分支
+- **修复：** 收尾固定两步脚本：`return-to-trunk.js`（切回主干 + `pull --ff-only` 追平）→ `delete-branches.js` 删分支
+
+### 废弃出口误跑删分支
+
+- **问题：** 选"确认废弃"后照 5.4 全跑，`delete-branches.js` 对未合并的废弃分支 `-D` 强删——远端 `<需求名>-deprecated` 只含已推送部分，本地领先提交只剩 reflog 可捞
+- **修复：** 废弃出口仅执行 5.4 步骤 1（回主干 + 追平）；本地分支保留原名，**不调用** `delete-branches.js`
 
 ### 中途插单静默混入
 
@@ -189,6 +231,7 @@ node "<skill_dir>/scripts/delete-branches.js" "<ws_root>" "<需求名>" local_re
 - 布局展示 + 用户确认后才切分支
 - 切分支统一走 `start-local.js`（基线 = `<remote>/<main>`，不取 HEAD）
 - 收尾先过门禁判定（`merge-branches.js --check`）；未合并必须三选一后收尾
-- 直合并走 `merge-branches.js`（临时 worktree，零接触；本地检出由 5.4 收尾三连切回主干）
-- 收尾三连（checkout main / pull / 删分支）完成后报告干净态
+- 直合并走 `merge-branches.js`（临时 worktree，零接触；本地检出由 5.4 `return-to-trunk.js` 切回主干）
+- 废弃出口：先 `deprecate-branches.js --check` 查未推送提交（有 ahead 须用户决策）→ 二次确认后执行；废弃后**仅回主干**（5.4 步骤 1），不删本地分支
+- 收尾脚本化（`return-to-trunk.js` 回主干 + 交付完成出口 `delete-branches.js` 删分支）完成后报告干净态
 - 所有写操作前的分支确认（当前检出 = 需求分支）

package/cbb/worktrees/skills/cbb-local-mode/scripts/deprecate-branches.js

@@ -9,9 +9,17 @@ require('./silence-popup');
  *
  * 用法：
  *   node deprecate-branches.js <ws_root> <branch> [--apps a,b]
+ *   node deprecate-branches.js <ws_root> <branch> [--apps a,b] --check   # 仅检查，不重命名
+ *
+ * 模式：
+ *   --check      只读检查：逐仓库报远端分支存在性与本地未推送提交数
+ *                （ls-remote 取远端权威 hash 与本地 <branch> 比对）。
+ *                用途：废弃重命名只覆盖远端已推送的部分——本地 ahead 提交
+ *                不会被带进 <branch>-deprecated，执行前须提示用户决策。
+ *   默认         执行远端重命名 <branch> → <branch>-deprecated
  *
  * 退出码：0 全部成功（含 skipped）/ 1 参数错误 / 2 存在失败
- * 末行：DEPRECATE_RESULT [...]
+ * 末行：DEPRECATE_RESULT [...] 或 DEPRECATE_CHECK_RESULT [...]
  */
 
 const { execSync } = require('child_process');
@@ -44,6 +52,51 @@ function loadApps(wsRoot) {
   }
 }
 
+/**
+ * 检查单个仓库（--check，只读）：
+ *   unpushed: 0 = 已全部推送；>0 = 本地领先远端 N 个提交；'all' = 远端无该分支（提交全部未推送）
+ */
+function checkRepo(name, repo, branch) {
+  const rec = { name, status: 'skipped', remote_exists: false, unpushed: 0, 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];
+  if (!run('git rev-parse --verify --quiet "refs/heads/' + branch + '"', repo).ok) {
+    rec.detail = 'no-local-branch';
+    return rec;
+  }
+  const ls = run('git ls-remote --heads "' + r + '" "refs/heads/' + branch + '"', repo);
+  if (!ls.ok) {
+    rec.status = 'failed';
+    rec.detail = 'ls-remote-failed';
+    return rec;
+  }
+  if (!ls.out) {
+    rec.status = 'ok';
+    rec.unpushed = 'all';
+    rec.detail = 'remote-has-no-branch';
+    return rec;
+  }
+  const remoteHash = ls.out.split(/\r?\n/)[0].split(/\s+/)[0];
+  const cnt = run('git rev-list --count "' + remoteHash + '..refs/heads/' + branch + '"', repo);
+  if (!cnt.ok) {
+    rec.status = 'failed';
+    rec.detail = 'rev-list-failed';
+    return rec;
+  }
+  rec.status = 'ok';
+  rec.remote_exists = true;
+  rec.unpushed = parseInt(cnt.out, 10) || 0;
+  return rec;
+}
+
 /** 对单个仓库执行废弃重命名 */
 function deprecateRepo(name, repo, branch) {
   const newName = branch + '-deprecated';
@@ -95,6 +148,7 @@ function main() {
   const appFilter = appsIdx >= 0
     ? new Set((args[appsIdx + 1] || '').split(',').map(s => s.trim()).filter(Boolean))
     : null;
+  const checkOnly = args.includes('--check');
 
   const repos = [{ name: 'workspace', repo: wsRoot }];
   for (const app of loadApps(wsRoot)) {
@@ -102,6 +156,17 @@ function main() {
     repos.push({ name: app.name, repo: path.join(wsRoot, '.codespace', app.name) });
   }
 
+  if (checkOnly) {
+    const results = repos.map(rp => checkRepo(rp.name, rp.repo, branch));
+    results.forEach(r => {
+      const up = r.status === 'ok' && r.unpushed !== 0 ? ' [unpushed: ' + r.unpushed + ']' : '';
+      console.log(r.status.toUpperCase() + ' ' + r.name + (r.detail ? ' — ' + r.detail : '') + up);
+    });
+    console.log('---');
+    console.log('DEPRECATE_CHECK_RESULT', JSON.stringify({ branch, results }));
+    process.exit(results.some(r => r.status === 'failed') ? 2 : 0);
+  }
+
   const results = repos.map(rp => deprecateRepo(rp.name, rp.repo, branch));
 
   results.forEach(r => {
@@ -116,4 +181,4 @@ function main() {
 
 if (require.main === module) main();
 
-module.exports = { run, loadApps, deprecateRepo };
+module.exports = { run, loadApps, checkRepo, deprecateRepo };

package/cbb/worktrees/skills/cbb-local-mode/scripts/return-to-trunk.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * 收尾回主干 —— 交付完成后把各参与仓库的本地检出切回主干并追平（ADR 0007 / 0008）
+ *
+ * 背景：merge-branches.js 统一零接触通道后，合并在临时 worktree 内完成、
+ * 不触碰本地检出（本地主干检出不随交付前移）。本地模式收尾需把各仓库
+ * 本地检出从需求分支切回主干——本脚本替代曾经写死 `git checkout main`
+ * 的裸命令：主干名逐仓库经远端 HEAD 探测（与 check-local-state.js 同源，
+ * 兼容 master 等），不再假设主干叫 main。
+ *
+ * 用法：
+ *   node return-to-trunk.js <ws_root> [--apps a,b] [--dry-run]
+ *
+ * 行为（逐仓库，相互独立、失败不停链）：
+ *   1. 目录无 .git → SKIP no-repo
+ *   2. git fetch --quiet origin（失败仅降级，后续判定退回本地主干）
+ *   3. 主干名 detectMain：远端 HEAD → 本地 main → 本地 master → origin/main → origin/master
+ *      → FAIL cannot-detect-main
+ *   4. 当前检出 ≠ 主干：
+ *      - 检出 dirty（含未跟踪）→ FAIL dirty-worktree（列未提交项数；不自动 stash，交用户决策）
+ *      - 本地有主干分支 → git checkout <主干>；仅远端有 → git checkout -b <主干> --track origin/<主干>
+ *   5. 追平远端：origin/<主干> 存在 → git pull --ff-only origin <主干>
+ *      （成功详情注记 `pulled origin/<主干>` / `up-to-date`；本地主干与 origin 分叉 → FAIL
+ *      pull-failed，交用户决策；远端无主干 → 注记跳过）
+ *   6. 已在主干 → 跳过切回，仍追平（幂等）
+ *
+ * 退出码：0 全部成功（含 no-repo / 已在主干）/ 1 参数错误 / 2 任一仓库失败
+ * 末行：TRUNK_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 hasRef(repoPath, ref) {
+  return run('git rev-parse --verify --quiet "' + ref + '"', repoPath).ok;
+}
+
+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 [];
+  }
+}
+
+/** 主干名：symbolic-ref 远端 HEAD → 本地 main/master → 远端跟踪 origin/main|master → 空串（与 check-local-state.js 同源，回退链更强） */
+function detectMain(repoPath) {
+  const remote = run('git remote', repoPath);
+  if (remote.ok && remote.out) {
+    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 + '/', '');
+  }
+  if (hasRef(repoPath, 'refs/heads/main')) return 'main';
+  if (hasRef(repoPath, 'refs/heads/master')) return 'master';
+  if (hasRef(repoPath, 'refs/remotes/origin/main')) return 'main';
+  if (hasRef(repoPath, 'refs/remotes/origin/master')) return 'master';
+  return '';
+}
+
+/** 检出未提交项数（含未跟踪，不含 ignored）；-1 = 状态不可读 */
+function countUncommitted(repoPath) {
+  const s = run('git status --porcelain', repoPath);
+  if (!s.ok) return -1;
+  return s.out ? s.out.split(/\r?\n/).filter(Boolean).length : 0;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const wsRoot = args[0];
+  if (!wsRoot || wsRoot.indexOf('--') === 0) {
+    console.error('Usage: node return-to-trunk.js <ws_root> [--apps a,b] [--dry-run]');
+    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 dryRun = args.includes('--dry-run');
+
+  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 = [];
+  let failed = false;
+
+  for (const rp of repos) {
+    const rec = { name: rp.name, status: 'ok', main: null, switched: false, uncommitted: 0, reason: null, detail: 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';
+      rec.reason = 'cannot-detect-main';
+      results.push(rec);
+      failed = true;
+      continue;
+    }
+    rec.main = main;
+    rec.uncommitted = countUncommitted(rp.repo);
+    const current = run('git branch --show-current', rp.repo);
+
+    if (current.ok && current.out !== main) {
+      // detached（out 为空）也需切回——「不在主干」含 detached
+      if (dryRun) {
+        rec.reason = 'would-switch (from ' + current.out + ')';
+        results.push(rec);
+        continue;
+      }
+      if (rec.uncommitted > 0) {
+        rec.status = 'failed';
+        rec.reason = 'dirty-worktree';
+        rec.detail = '检出 ' + current.out + ' 上有 ' + rec.uncommitted + ' 项未提交改动，不自动 stash——先处理再重跑';
+        results.push(rec);
+        failed = true;
+        continue;
+      }
+      const co = hasRef(rp.repo, 'refs/heads/' + main)
+        ? run('git checkout --quiet "' + main + '"', rp.repo)
+        : run('git checkout -b "' + main + '" --track origin/' + main, rp.repo);
+      if (!co.ok) {
+        rec.status = 'failed';
+        rec.reason = 'checkout-failed';
+        rec.detail = (co.err || '').split(/\r?\n/)[0];
+        results.push(rec);
+        failed = true;
+        continue;
+      }
+      rec.switched = true;
+    } else if (dryRun) {
+      rec.reason = 'already-on-trunk';
+      results.push(rec);
+      continue;
+    }
+
+    if (hasRef(rp.repo, 'refs/remotes/origin/' + main)) {
+      const before = run('git rev-parse --quiet HEAD', rp.repo);
+      const pull = run('git pull --ff-only --quiet origin "' + main + '"', rp.repo);
+      if (!pull.ok) {
+        rec.status = 'failed';
+        rec.reason = 'pull-failed';
+        rec.detail = (pull.err || '').split(/\r?\n/)[0];
+        failed = true;
+      } else {
+        const after = run('git rev-parse --quiet HEAD', rp.repo);
+        rec.detail = before.ok && after.ok && before.out !== after.out
+          ? 'pulled origin/' + main
+          : 'up-to-date';
+      }
+    } else if (!rec.reason) {
+      rec.reason = 'no-remote-trunk';
+    }
+    results.push(rec);
+  }
+
+  results.forEach(r => {
+    console.log(r.status.toUpperCase() + ' ' + r.name + (r.main ? ' → ' + r.main : '') + (r.reason ? ': ' + r.reason : '') + (r.detail ? ' — ' + r.detail : ''));
+  });
+  console.log('---');
+  console.log('TRUNK_RESULT', JSON.stringify({ results }));
+  process.exit(failed ? 2 : 0);
+}
+
+if (require.main === module) main();

package/cbb/worktrees/skills/cbb-worktree-close/scripts/deprecate-branches.js

@@ -9,9 +9,17 @@ require('./silence-popup');
  *
  * 用法：
  *   node deprecate-branches.js <ws_root> <branch> [--apps a,b]
+ *   node deprecate-branches.js <ws_root> <branch> [--apps a,b] --check   # 仅检查，不重命名
+ *
+ * 模式：
+ *   --check      只读检查：逐仓库报远端分支存在性与本地未推送提交数
+ *                （ls-remote 取远端权威 hash 与本地 <branch> 比对）。
+ *                用途：废弃重命名只覆盖远端已推送的部分——本地 ahead 提交
+ *                不会被带进 <branch>-deprecated，执行前须提示用户决策。
+ *   默认         执行远端重命名 <branch> → <branch>-deprecated
  *
  * 退出码：0 全部成功（含 skipped）/ 1 参数错误 / 2 存在失败
- * 末行：DEPRECATE_RESULT [...]
+ * 末行：DEPRECATE_RESULT [...] 或 DEPRECATE_CHECK_RESULT [...]
  */
 
 const { execSync } = require('child_process');
@@ -44,6 +52,51 @@ function loadApps(wsRoot) {
   }
 }
 
+/**
+ * 检查单个仓库（--check，只读）：
+ *   unpushed: 0 = 已全部推送；>0 = 本地领先远端 N 个提交；'all' = 远端无该分支（提交全部未推送）
+ */
+function checkRepo(name, repo, branch) {
+  const rec = { name, status: 'skipped', remote_exists: false, unpushed: 0, 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];
+  if (!run('git rev-parse --verify --quiet "refs/heads/' + branch + '"', repo).ok) {
+    rec.detail = 'no-local-branch';
+    return rec;
+  }
+  const ls = run('git ls-remote --heads "' + r + '" "refs/heads/' + branch + '"', repo);
+  if (!ls.ok) {
+    rec.status = 'failed';
+    rec.detail = 'ls-remote-failed';
+    return rec;
+  }
+  if (!ls.out) {
+    rec.status = 'ok';
+    rec.unpushed = 'all';
+    rec.detail = 'remote-has-no-branch';
+    return rec;
+  }
+  const remoteHash = ls.out.split(/\r?\n/)[0].split(/\s+/)[0];
+  const cnt = run('git rev-list --count "' + remoteHash + '..refs/heads/' + branch + '"', repo);
+  if (!cnt.ok) {
+    rec.status = 'failed';
+    rec.detail = 'rev-list-failed';
+    return rec;
+  }
+  rec.status = 'ok';
+  rec.remote_exists = true;
+  rec.unpushed = parseInt(cnt.out, 10) || 0;
+  return rec;
+}
+
 /** 对单个仓库执行废弃重命名 */
 function deprecateRepo(name, repo, branch) {
   const newName = branch + '-deprecated';
@@ -95,6 +148,7 @@ function main() {
   const appFilter = appsIdx >= 0
     ? new Set((args[appsIdx + 1] || '').split(',').map(s => s.trim()).filter(Boolean))
     : null;
+  const checkOnly = args.includes('--check');
 
   const repos = [{ name: 'workspace', repo: wsRoot }];
   for (const app of loadApps(wsRoot)) {
@@ -102,6 +156,17 @@ function main() {
     repos.push({ name: app.name, repo: path.join(wsRoot, '.codespace', app.name) });
   }
 
+  if (checkOnly) {
+    const results = repos.map(rp => checkRepo(rp.name, rp.repo, branch));
+    results.forEach(r => {
+      const up = r.status === 'ok' && r.unpushed !== 0 ? ' [unpushed: ' + r.unpushed + ']' : '';
+      console.log(r.status.toUpperCase() + ' ' + r.name + (r.detail ? ' — ' + r.detail : '') + up);
+    });
+    console.log('---');
+    console.log('DEPRECATE_CHECK_RESULT', JSON.stringify({ branch, results }));
+    process.exit(results.some(r => r.status === 'failed') ? 2 : 0);
+  }
+
   const results = repos.map(rp => deprecateRepo(rp.name, rp.repo, branch));
 
   results.forEach(r => {
@@ -116,4 +181,4 @@ function main() {
 
 if (require.main === module) main();
 
-module.exports = { run, loadApps, deprecateRepo };
+module.exports = { run, loadApps, checkRepo, deprecateRepo };

package/cbb/worktrees/skills/cbb-worktree-init/SKILL.md

@@ -367,7 +367,7 @@ node "<skill_dir>/scripts/junction-ai-config.js" "<ws_root>" "<wt_path>"
 | 空间新增了应用（编辑 `CBB-WORKSPACE.json` 后） | Step 1 拉取新应用代码 → Step 3.3 为新应用建分支 → Step 3.5 在 `.codespace/` 容器内创建缺失的 app worktree → Step 3.6 补 junction |
 | 上次 init 中途失败 | 已存在的分支 / worktree 自动复用，`.gitignore` 处理自动跳过，仅补齐缺失部分 |
 | 应用从 config 移除 | 已创建的分支 / worktree **不会**自动删除；如需清理用 `cbb-worktree-close` skill 关闭后重建 |
-| **本地模式升级 worktree**（ADR 0002） | Step 3.3 分支已存在 → reused（本地阶段提交随身带走）；先 `git checkout main` 腾出各仓库本地检出，再重跑本技能 |
+| **本地模式升级 worktree**（ADR 0002） | Step 3.3 分支已存在 → reused（本地阶段提交随身带走）；先把各仓库本地检出切回主干（主干名以远端 HEAD 为准，勿写死 main），再重跑本技能 |
 | 本地模式进行中重跑 | 安全：分支基线取 `origin/main`（非 HEAD），不受根/应用检出状态影响；fetch 不动工作区 |
 
 > ⓘ 本技能**零远端副作用**（lazy push）：不存在"重跑推送开发中提交"的风险面——推送只发生在 `cbb-worktree-push`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jspg-ai/coding-bb",
-  "version": "0.0.5-beta.2",
+  "version": "0.0.5-beta.4",
   "description": "整合业界热门且高价值的工具、框架与技能，为 AI CODING AGENT 提供统一的行为准则与工作流，辅助开发者将需求高效落地为符合规范的代码",
   "main": "cbb/lib/install/init.js",
   "bin": {
@@ -20,7 +20,7 @@
   "scripts": {
     "sync:shared": "node scripts/sync-shared.js",
     "pretest": "node scripts/sync-shared.js --check",
-    "test": "node test/lib/install/cleanup.test.js && node test/lib/utils/settings.test.js && node test/lib/utils/gitignore.test.js && node test/lib/utils/githook.test.js && node test/lib/utils/version.test.js && node test/lib/install/workspaces.test.js && node test/lib/utils/checkbox.test.js && node test/lib/utils/output.test.js && node test/lib/install/cli-help.test.js && node test/lib/install/adapters.test.js && node test/lib/install/tool-selection.test.js && node test/lib/install/agents-nav.test.js && node test/lib/install/command-skill.test.js && node test/lib/utils/plugin-hook.test.js && node test/lib/wiki/wiki-publish.test.js && node test/lib/wiki/wiki-parse-args.test.js && node test/lib/wiki/wiki-split.test.js && node test/lib/superpowers/superpowers.test.js && node test/lib/external/external.test.js && node test/worktrees/push-branches.test.js && node test/worktrees/commit-worktrees.test.js && node test/worktrees/push-worktrees.test.js && node test/worktrees/check-env-deep.test.js && node test/worktrees/create-worktrees.test.js && node test/worktrees/make-mr-urls.test.js && node test/lib/install/setup-decision.test.js && node test/lib/openspec/protected-paths.test.js && node test/worktrees/merge-branches.test.js && node test/worktrees/deprecate-branches.test.js && node test/worktrees/delete-branches.test.js && node test/worktrees/skill-refs.test.js"
+    "test": "node test/lib/install/cleanup.test.js && node test/lib/utils/settings.test.js && node test/lib/utils/gitignore.test.js && node test/lib/utils/githook.test.js && node test/lib/utils/version.test.js && node test/lib/install/workspaces.test.js && node test/lib/utils/checkbox.test.js && node test/lib/utils/output.test.js && node test/lib/install/cli-help.test.js && node test/lib/install/adapters.test.js && node test/lib/install/tool-selection.test.js && node test/lib/install/agents-nav.test.js && node test/lib/install/command-skill.test.js && node test/lib/utils/plugin-hook.test.js && node test/lib/wiki/wiki-publish.test.js && node test/lib/wiki/wiki-parse-args.test.js && node test/lib/wiki/wiki-split.test.js && node test/lib/superpowers/superpowers.test.js && node test/lib/external/external.test.js && node test/worktrees/push-branches.test.js && node test/worktrees/commit-worktrees.test.js && node test/worktrees/push-worktrees.test.js && node test/worktrees/check-env-deep.test.js && node test/worktrees/create-worktrees.test.js && node test/worktrees/make-mr-urls.test.js && node test/lib/install/setup-decision.test.js && node test/lib/openspec/protected-paths.test.js && node test/worktrees/merge-branches.test.js && node test/worktrees/deprecate-branches.test.js && node test/worktrees/delete-branches.test.js && node test/worktrees/return-to-trunk.test.js && node test/worktrees/skill-refs.test.js"
   },
   "keywords": [
     "cbb",