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

package/cbb/worktrees/_shared/scripts/start-local.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * 本地模式开工（ADR 0002）：根 + 指定应用就地切需求分支。
+ *
+ * 用法：node start-local.js <ws_root> <branch> [--apps app1,app2] [--all-apps]
+ *
+ * 行为：
+ *   1. 前置自检：根与所有 .codespace/<app>/ 若任一检出在非主干分支 → 遗留态，
+ *      退出码 2（agent 应升级为用户决策：继续 / 收尾 / 升级 / 丢弃，不在本脚本内处理）
+ *   2. 参与仓库 = workspace + 应用子集：
+ *      - --apps a,b  → 指定应用（本地模式推荐：从需求语境提取涉及应用）
+ *      - --all-apps  → CBB-WORKSPACE.json 全量应用
+ *      - 缺省       → 仅 workspace（后续重跑幂等补齐，与 worktree-init 增补语义一致）
+ *   3. 每个仓库：
+ *      - 当前已在 <branch> → reused
+ *      - 分支存在（未检出）→ git checkout
+ *      - 否则 → git checkout -b <branch> <remote>/<main>（基线不取 HEAD，ADR 0002；
+ *        remote 不可用回退本地 main/master，再回退 HEAD）
+ *      - dirty 仓库切换失败 → 报错退出（不 stash 兜底，交给用户决策）
+ *   4. 参与的应用仓库幂等补装提交防线 hook（cbb setup 已装，此处兜底）
+ *
+ * 幂等：重跑同一 branch 安全（reused / checkout 跳过）。
+ *
+ * 退出码：
+ *   0 - 全部切换成功
+ *   1 - 参数错误
+ *   2 - 遗留态 / 部分切换失败
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { installTo: installGitHook } = require('./install-git-hook');
+
+const wsRoot = process.argv[2];
+const branch = process.argv[3];
+
+if (!wsRoot || !branch) {
+  console.error('Usage: node start-local.js <ws_root> <branch> [--apps a,b] [--all-apps]');
+  process.exit(1);
+}
+
+function run(cmd, cwd) {
+  try {
+    return { ok: true, out: execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim() };
+  } catch (e) {
+    return { ok: false, err: (e.stderr ? e.stderr.toString() : e.message || String(e)).trim() };
+  }
+}
+
+/** 主干名：symbolic-ref 远端 HEAD → 本地 main/master 回退 */
+function detectMain(cwd) {
+  const remotes = run('git remote', cwd);
+  if (remotes.ok && remotes.out) {
+    const r = remotes.out.split(/\r?\n/)[0];
+    const sym = run('git symbolic-ref "refs/remotes/' + r + '/HEAD"', cwd);
+    if (sym.ok && sym.out) return { remote: r, main: sym.out.replace('refs/remotes/' + r + '/', '') };
+  }
+  if (run('git rev-parse --verify --quiet refs/heads/main', cwd).ok) return { remote: null, main: 'main' };
+  if (run('git rev-parse --verify --quiet refs/heads/master', cwd).ok) return { remote: null, main: 'master' };
+  return { remote: null, main: null };
+}
+
+function currentBranch(cwd) {
+  const r = run('git branch --show-current', cwd);
+  return r.ok ? r.out : '';
+}
+
+// ── 1. 前置自检：遗留态检测 ───────────────────────────────
+// 「非主干」且「不是本次 branch」才是遗留（别的需求没收尾）；
+// 已检出在本次 branch 上 = 幂等补齐场景，放行（reused）。
+
+function isOnMain(cwd) {
+  const info = detectMain(cwd);
+  return info.main ? currentBranch(cwd) === info.main : false;
+}
+
+function isOnTarget(cwd) {
+  return currentBranch(cwd) === branch || isOnMain(cwd);
+}
+
+const leftovers = [];
+if (!isOnTarget(wsRoot)) leftovers.push({ name: 'workspace', branch: currentBranch(wsRoot) });
+const codeDir = path.join(wsRoot, '.codespace');
+if (fs.existsSync(codeDir)) {
+  for (const name of fs.readdirSync(codeDir).sort()) {
+    const appDir = path.join(codeDir, name);
+    if (fs.existsSync(path.join(appDir, '.git')) && !isOnTarget(appDir)) {
+      leftovers.push({ name, branch: currentBranch(appDir) });
+    }
+  }
+}
+if (leftovers.length > 0) {
+  console.error('❌ 遗留态：以下仓库检出在非主干分支，先由用户决策处理（继续/收尾/升级/丢弃）：');
+  leftovers.forEach(l => console.error('   - ' + l.name + ': ' + l.branch));
+  console.log('---');
+  console.log('LOCAL_START_FAILED', JSON.stringify({ reason: 'leftover', leftovers }));
+  process.exit(2);
+}
+
+// ── 2. 参与仓库集合 ───────────────────────────────────────
+
+let appNames = [];
+const argApps = process.argv.indexOf('--apps');
+const argAll = process.argv.includes('--all-apps');
+if (argApps >= 0) {
+  const raw = process.argv[argApps + 1] || '';
+  appNames = raw.split(',').map(s => s.trim()).filter(Boolean);
+} else if (argAll) {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(wsRoot, 'CBB-WORKSPACE.json'), 'utf-8'));
+    appNames = (config.apps || []).map(a => a.name);
+  } catch (e) {
+    console.error('❌ 读取 CBB-WORKSPACE.json 失败：' + e.message);
+    process.exit(2);
+  }
+}
+
+const targets = [{ name: 'workspace', dir: wsRoot }];
+for (const name of appNames) {
+  const appDir = path.join(wsRoot, '.codespace', name);
+  if (!fs.existsSync(path.join(appDir, '.git'))) {
+    console.error('❌ 应用仓库不存在：.codespace/' + name + '（请检查 CBB-WORKSPACE.json 或先跑 cbb setup）');
+    process.exit(2);
+  }
+  targets.push({ name, dir: appDir });
+}
+
+// ── 3. 逐仓库切换 ─────────────────────────────────────────
+
+const results = [];
+let hasFailure = false;
+
+for (const t of targets) {
+  const cur = currentBranch(t.dir);
+  if (cur === branch) {
+    console.log('⏭️  ' + t.name + ': 已在 ' + branch + '（reused）');
+    results.push({ name: t.name, status: 'reused' });
+    continue;
+  }
+
+  const exists = run('git rev-parse --verify --quiet refs/heads/' + branch, t.dir).ok;
+  const info = detectMain(t.dir);
+  let cmd;
+  let base = 'HEAD';
+  if (exists) {
+    cmd = 'git checkout "' + branch + '"';
+    base = '(existing)';
+  } else {
+    if (info.remote && info.main) base = info.remote + '/' + info.main;
+    else if (info.main) base = info.main;
+    cmd = 'git checkout -b "' + branch + '" "' + base + '"';
+  }
+  const r = run(cmd, t.dir);
+  if (r.ok) {
+    console.log('✅ ' + t.name + ': ' + (exists ? 'checkout' : 'created from ' + base) + ' → ' + branch);
+    results.push({ name: t.name, status: exists ? 'switched' : 'created', base });
+  } else {
+    console.error('❌ ' + t.name + ': 切换失败 — ' + r.err);
+    results.push({ name: t.name, status: 'failed', error: r.err });
+    hasFailure = true;
+  }
+}
+
+// ── 4. 参与应用补装提交防线 hook（幂等）────────────────────
+
+const hookResults = [];
+for (const t of targets) {
+  if (t.name === 'workspace') continue; // 根仓库 hook 由 cbb setup 安装
+  hookResults.push({ name: t.name, status: installGitHook(t.dir) });
+}
+
+console.log('---');
+console.log('LOCAL_START_RESULT', JSON.stringify({
+  branch,
+  results,
+  hooks: hookResults,
+  worktreeHint: '如需升级隔离：重跑 cbb-worktree-init（分支已存在自动复用，worktree 从分支创建，提交随身带走）',
+}));
+process.exit(hasFailure ? 2 : 0);

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

@@ -0,0 +1,194 @@
+---
+name: cbb-local-mode
+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 0007/0008），差异仅是**无隔离目录、不可并行**——适合单线程快速推进的需求。
+
+**启动时声明：** "我正在使用 cbb-local-mode 技能进行本地模式开发。"
+
+## 核心原则
+
+- **两模式由用户选择，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 白名单外 / 应用全拦；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 保持空间根
+
+---
+
+## Step 0：状态自检（必跑，零交互常态）
+
+```bash
+node "<skill_dir>/scripts/check-local-state.js" "<ws_root>"
+```
+
+**解读末行 `LOCAL_STATE`**：
+- `state: "clean"` → 全部仓库在主干 → **直接进 Step 1**（零交互）
+- `state: "active"` → 存在遗留（非主干检出，`branches` 为遗留需求名）→ **必须在对话中让用户四选一，不得自行决定**：
+
+```
+检测到本地需求 <分支名> 进行中（参与仓库：…）：
+  [1] 继续该需求（推荐若同名）—— 重建上下文接着干
+  [2] 先收尾 —— 走收尾流程（见 Step 5）后重新开工
+  [3] 升级 worktree —— 转跑 cbb-worktree-init 腾出本地检出
+  [4] 丢弃 —— 确认无未推送/未合并后清理分支（需二次确认）
+```
+
+> 自检同时是**会话恢复**机制：新会话"继续刚才的需求"靠它还原布局（同名分支的仓库集合 = 参与仓库）。
+
+## Step 1：需求名与布局确认
+
+1. 对话中询问需求名（kebab-case，同时作分支名；禁 `..` / 路径分隔符 / 空格）：直接给名，或输入需求描述由 agent 推荐 3–5 个英文候选（`AskUserQuestion` 选定；不满意可直接回复自己的名字）
+2. 从需求语境提取**涉及的应用子集**（改哪些 `.codespace/<app>`）；纯 workspace 内容则仅根参与。展示布局向用户确认：
+
+```
+本地模式布局（需求 <需求名>）：
+  workspace     → 空间根 checkout -b <需求名>
+  ep-foo-app    → .codespace/ep-foo-app checkout -b <需求名>
+  ep-bar-app    → 不参与（本需求不涉及）
+确认后开工；中途涉及新应用可重跑本技能幂等补齐。
+```
+
+> 布局确认属于方案确认（先批准后动工）；应用子集判断错了没有代价——重跑一次即补。
+
+## Step 2：切分支（开工）
+
+```bash
+node "<skill_dir>/scripts/start-local.js" "<ws_root>" "<branch>" --apps "<app1>,<app2>"
+```
+
+- `--apps`：指定涉及应用（逗号分隔）；`--all-apps`：全量；缺省仅 workspace
+- **解读末行 `LOCAL_START_RESULT`**：逐仓库 created / switched / reused + hook 补装结果
+- 退出码 2（`LOCAL_START_FAILED leftover`）→ 回 Step 0 用户决策；切换失败（dirty 冲突）→ 报告详情让用户先处理，**不自动 stash**
+
+## Step 3：开发（会话 cwd == 开发目录）
+
+- 当前会话**原地**开发：workspace 内容用根相对路径，应用代码用 `.codespace/<app>/...` 相对路径——上游 `/opsx:propose → apply → verify` 的相对路径指令**原样生效**，零翻译（worktree 模式自 ADR 0003 起同布局，两模式路径通用）
+- 需求产物落 `openspec/changes/<需求名>/`（在分支上，hook 已保证不会误进 main）
+- **读基准代码约定**：本地模式进行中工作区是开发态——要读"main 上是什么"先看 `git -C .codespace/<app> branch --show-current`，或直接 `git show main:<path>`，不要默认工作区即基准
+- **中途插单**：用户插入非本需求的改动 → 先确认归属（并入当前需求 / 收尾后处理 / 转 worktree），不得静默混入
+
+## Step 4：提交推送（转 cbb-worktree-push）
+
+对话中说"提交并推送"即触发 `cbb-worktree-push`——其仓库发现已支持**本地布局**（根 + 持有同名分支的 `.codespace/<app>/`），dry-run 预览（含 agent 生成的 commit 信息）→ 批量 commit → push → Step 7 交付选择（提 MR 预填链接 / 直接合并 / 暂不处理，ADR 0008），全流程与 worktree 模式一致。
+
+## Step 5：收尾（收尾合并门禁 · ADR 0007）
+
+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` → 输出明细、修复后重跑；`AUTOSTASH_PENDING`（`MERGED` 但退出码 2）→ 交付已完成，仅暂存恢复遇冲突——**本地模式的改动会被恢复到已合入需求的 trunk 上（基线已变，冲突概率高于 worktree 模式）**，列冲突点问用户二选一（agent 解决 / 手动解决，协议同 close 出口二），处理前不得 drop stash
+- **确认废弃** → `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 归档在合并前执行（产物在分支上随交付合入）
+- 全部仓库回 main 后向用户报告"本地模式已收尾，空间回到干净态"
+
+## 升级 worktree（中途要并行 / 要隔离）
+
+**直接重跑 `cbb-worktree-init`（幂等）**：分支已存在自动复用（reused），worktree 从分支创建——本地阶段的提交**随身带走**，零成本升级。升级前提：本地检出先回 main（`git checkout main`，未提交改动先 commit 或用户决策），否则 worktree 检出与本地检出冲突。
+
+---
+
+## 快速参考
+
+| 场景 | 处理方式 |
+|------|----------|
+| 任何触发 | 先跑 Step 0 状态自检（clean 零交互 / active 用户四选一） |
+| 需求名 | 对话输入：直接给名，或给需求描述（agent 推荐 3–5 个英文候选供选）；自由文本本身禁走 AskUserQuestion |
+| 涉及应用 | 需求语境提取子集，`--apps` 传入；中途补齐重跑（幂等） |
+| 切分支失败（dirty 冲突） | 报告详情，用户处理；禁止自动 stash |
+| 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` / 确认废弃） |
+| 要并行新需求 | 转 worktree 模式（init 分支从 origin/main 建，不占本地检出）；本地需求继续占用根 |
+| 升级隔离 | 重跑 cbb-worktree-init（提交随身带走）；先回 main 腾检出 |
+
+---
+
+## 常见错误
+
+### 跳过 Step 0 直接开工
+
+- **问题：** 上一个本地需求没收尾，新需求改动混入旧分支
+- **修复：** 状态自检必跑；active 态必须用户决策后才能动
+
+### 把工作区当基准代码读
+
+- **问题：** 本地模式进行中 `.codespace/<app>/` 是 feature 分支，agent 读它当"main 现状"，得出错误结论
+- **修复：** 读基准前确认检出分支，或 `git show main:<path>`；`git diff main` 看开发态差异
+
+### 同时开两个本地需求
+
+- **问题：** 单检出单分支，第二个需求的 checkout 会顶掉第一个
+- **修复：** 一次一个本地需求；并行需求走 worktree 模式（`cbb-worktree-init` 从 `origin/main` 建分支，不受本地占用影响）
+
+### 收尾忘记 pull
+
+- **问题：** `checkout main` 后直接删分支，本地 main 陈旧，下次 `start-local` 从旧基线建分支
+- **修复：** 收尾固定三连：checkout main && pull && branch -d
+
+### 中途插单静默混入
+
+- **问题：** 用户插的"顺手改一下"与本需求改动混在同一 commit，评审困难
+- **修复：** 插单必问归属：并入 / 收尾后处理 / 转 worktree
+
+---
+
+## 红线规则
+
+**绝不允许**
+
+- 跳过 Step 0 状态自检（active 态未决策就开工）
+- 直接在 main 检出上提交载荷（hook 会拦；被拦后 --no-verify 绕过仅限用户显式要求）
+- 自动 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 / 删分支）完成后报告干净态
+- 所有写操作前的分支确认（当前检出 = 需求分支）

package/cbb/worktrees/skills/cbb-local-mode/scripts/check-local-state.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * 本地模式状态自检（ADR 0002,改动清单 #12）。
+ *
+ * 用法：node check-local-state.js <ws_root>
+ *
+ * 扫描空间根 + 所有 .codespace/<app>/ 的 { 当前分支, dirty }，
+ * 判定「干净态」（全部在主干且 clean）或「遗留态」（任一仓库检出在非主干分支）。
+ * 干净态 → 零交互直接进入模式选择；遗留态 → agent 升级为用户决策
+ * （继续 / 收尾 / 升级 worktree / 丢弃）。同名分支集合 = 遗留需求的仓库布局。
+ *
+ * 输出：
+ *   人类可读报告（逐仓库状态 + 态判定 + 推断的需求名）
+ *   末行 LOCAL_STATE { state, branches[], repos[{name,branch,dirty}] }
+ *     - state: 'clean' | 'active'（active = 存在非主干检出）
+ *     - branches: 非主干分支名集合（通常为 1 个 = 遗留需求名；多个不同名 → 多头遗留，需用户逐个处理）
+ *
+ * 退出码：
+ *   0 - 扫描完成（无论何种状态；态判定交给 agent 解读）
+ *   1 - 参数错误
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const wsRoot = process.argv[2];
+
+if (!wsRoot) {
+  console.error('Usage: node check-local-state.js <ws_root>');
+  process.exit(1);
+}
+
+function run(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch (e) {
+    return null;
+  }
+}
+
+/** 主干名：symbolic-ref 远端 HEAD → 本地 main/master 存在性回退；探测失败 null */
+function detectMain(cwd) {
+  const remotes = run('git remote', cwd);
+  if (remotes) {
+    const r = remotes.split(/\r?\n/)[0];
+    const sym = run('git symbolic-ref "refs/remotes/' + r + '/HEAD"', cwd);
+    if (sym) return sym.replace('refs/remotes/' + r + '/', '');
+  }
+  if (run('git rev-parse --verify --quiet refs/heads/main', cwd)) return 'main';
+  if (run('git rev-parse --verify --quiet refs/heads/master', cwd)) return 'master';
+  return null;
+}
+
+function scanRepo(cwd, name) {
+  const branch = run('git branch --show-current', cwd) || '(detached)';
+  const status = run('git status --porcelain', cwd);
+  const dirty = !!(status && status.length);
+  const main = detectMain(cwd);
+  const repo = { name, branch, dirty };
+  if (main) repo.main = main;
+  return repo;
+}
+
+// ── 扫描空间根 ─────────────────────────────────────────────
+
+if (!fs.existsSync(path.join(wsRoot, '.git'))) {
+  console.error('❌ ' + wsRoot + ' 不是 git 仓库');
+  process.exit(1);
+}
+
+const repos = [scanRepo(wsRoot, 'workspace')];
+
+// ── 扫描 .codespace/ 各应用 ───────────────────────────────
+
+const codeDir = path.join(wsRoot, '.codespace');
+if (fs.existsSync(codeDir)) {
+  for (const name of fs.readdirSync(codeDir).sort()) {
+    const appDir = path.join(codeDir, name);
+    if (fs.existsSync(path.join(appDir, '.git'))) {
+      repos.push(scanRepo(appDir, name));
+    }
+  }
+}
+
+// ── 态判定 ─────────────────────────────────────────────────
+
+for (const r of repos) {
+  const icon = (r.main && r.branch === r.main) ? '📄' : '🌿';
+  const dirtyTag = r.dirty ? '（有未提交修改）' : '';
+  const baseTag = (r.main && r.branch !== r.main) ? ' ← 主干 ' + r.main : '';
+  console.log(icon + ' ' + r.name + ': ' + r.branch + dirtyTag + baseTag);
+}
+
+const active = repos.filter(r => !(r.main && r.branch === r.main));
+const branches = [...new Set(active.map(r => r.branch))];
+
+let state;
+if (active.length === 0) {
+  state = 'clean';
+  console.log('✅ 干净态：全部仓库在主干且可开工（模式选择不受限）');
+} else {
+  state = 'active';
+  console.log('⚠️  遗留态：检测到本地需求进行中（分支：' + branches.join(', ') + '）');
+  console.log('   参与仓库：' + active.map(r => r.name).join(', '));
+  if (branches.length > 1) {
+    console.log('   ⚠️  存在多个不同分支名——多头遗留，需用户逐个处理');
+  }
+  console.log('   处理选项：继续该需求 / 先收尾 / 升级 worktree（git worktree add）/ 丢弃');
+}
+
+console.log('---');
+console.log('LOCAL_STATE', JSON.stringify({ state, branches, repos }));
+process.exit(0);

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

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