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

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/return-to-trunk.js

@@ -0,0 +1,184 @@
+#!/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 <主干>
+ *      （本地主干与 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 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 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,14 +88,15 @@ 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>"
@@ -104,24 +105,33 @@ node "<skill_dir>/scripts/merge-branches.js" "<ws_root>" "<需求名>" --apps "<
   `need-mr`（远端主干受保护）→ 改用提 MR；`failed` → 输出明细、修复后重跑
 - **确认废弃** → `deprecate-branches.js`（远程重命名 `<需求名>-deprecated`；本地分支保留原名）
 
-**5.4 交付完成 → 各仓库回主干并删分支**：
+**5.4 交付完成 → 各仓库回主干并删分支**（脚本化；主干名逐仓库经远端 HEAD 探测，兼容 main / master）：
+
+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 → 全部已回主干并追平
+- 某仓库 `dirty-worktree` → 检出上有未提交改动（回归 5.1 前置，先处理再重跑）；**不自动 stash**
+- 某仓库 `pull-failed`（本地主干与 origin 分叉）→ 输出详情，交用户决策
+- 某仓库 `cannot-detect-main` → 检查该仓库远端与主干分支（`fetch-failed` 同理）
+- 幂等：已在主干的仓库仅追平远端，重复执行无害
+
+2. 本地 + 远程需求分支删除（本地删除含 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 +146,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 +171,8 @@ 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` 删分支
 
 ### 中途插单静默混入
 
@@ -189,6 +199,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`（临时 worktree，零接触；本地检出由 5.4 收尾三连切回主干）
-- 收尾三连（checkout main / pull / 删分支）完成后报告干净态
+- 直合并走 `merge-branches.js`（临时 worktree，零接触；本地检出由 5.4 `return-to-trunk.js` 切回主干）
+- 收尾脚本化（`return-to-trunk.js` 回主干 + `delete-branches.js` 删分支）完成后报告干净态
 - 所有写操作前的分支确认（当前检出 = 需求分支）

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

@@ -0,0 +1,184 @@
+#!/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 <主干>
+ *      （本地主干与 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 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 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-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.3",
   "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",