@jspg-ai/coding-bb 0.0.3-beta.3 → 0.0.3-beta.31

package/cbb/worktrees/skills/cbb-local-mode/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-worktree-close/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: cbb-worktree-close
 description: "关闭/清理/删除需求工作空间的 worktree 和分支。触发：用户明确说关闭/清理/删除 worktree、结束隔离开发、合并完要清理。禁止在 cbb-worktree-init 执行后自动调用——只有用户主动要求关闭时才触发。"
-license: MIT
-compatibility: Requires git (>=2.30) and Node.js (>=16.7.0). All commands are pure Node.js scripts under `scripts/`, fully cross-platform (Windows / macOS / Linux, bash / PowerShell / Git Bash).
-metadata:
-  author: Contributors
-  version: "2.0"
-  generatedBy: coding-bb
 ---
 
 # Close Worktree（跨平台脚本化版本 v2.0）
@@ -18,10 +12,10 @@ metadata:
 ## 核心原则
 
 - 本技能的所有原子操作封装为 `scripts/*.js` Node.js 脚本，**跨平台执行**
-- 本技能是 `cbb-worktree-init` 的逆操作：共用 `workspace-config.json`、共用 `.worktrees/worktree-<需求名>/` 物理直聚命名、共用统一的分支名（不加前缀）
-- App worktree **物理嵌套**在 workspace worktree 内（`.worktrees/worktree-<需求名>/<应用名>/`），但 git 上属于各自仓库的独立 worktree
+- 本技能是 `cbb-worktree-init` 的逆操作：共用 `CBB-WORKSPACE.json`、共用 `.worktrees/worktree-<需求名>/` 物理直聚命名、共用统一的分支名（不加前缀）
+- App worktree **物理嵌套**在 workspace worktree 的 `.codespace/` 容器内（`.worktrees/worktree-<需求名>/.codespace/<应用名>/`，镜像空间根布局，ADR 0003），但 git 上属于各自仓库的独立 worktree
 - 只操作 `.worktrees/worktree-<需求名>` 这一类精确路径，**绝不碰其它 worktree**（如 IDE/工具自动创建的 `~/.qoder/worktree/...` 会话 worktree）
-- 通过检查 `.worktrees/worktree-<需求名>/<应用名>/` **是否实际存在**来确定关联应用——创建时用户可能只关联了 `workspace-config.json` 中的部分应用，不能假设全部应用都关联
+- 通过检查 `.worktrees/worktree-<需求名>/.codespace/<应用名>/` **是否实际存在**来确定关联应用——创建时用户可能只关联了 `CBB-WORKSPACE.json` 中的部分应用，不能假设全部应用都关联
 - **顺序硬约束：先移除所有 worktree，再删除分支。** 目标分支当前正检出于 worktree 中，先删分支会报 `error: Cannot delete branch '<分支>' checked out at '<worktree 路径>'`
 - **破坏性操作必须先报告、经用户确认才执行**：未提交修改、未合并/未推送的提交，绝不静默 `--force` 或 `-D` 丢弃
 - 软性检查失败时报告详情，询问用户是否继续
@@ -29,12 +23,28 @@ metadata:
 
 ---
 
+## 调用脚本的统一方式
+
+**重要**：本技能的所有脚本位于**本 SKILL.md 所在目录的 `scripts/` 下**（skill 目录）。
+
+调用时用**本技能目录的绝对路径**拼接脚本名（AI 读取本 SKILL.md 时即已知该目录），例如：
+
+```bash
+node "<skill_dir>/scripts/<name>.js" <参数>
+```
+
+> - `<skill_dir>` = 本 SKILL.md 所在目录的绝对路径（AI 从读取路径即可推出）
+> - **cwd 必须保持在工作空间根目录**：脚本按 cwd 定位 `CBB-WORKSPACE.json` 与 git 仓库
+> - 不要用 `./scripts/...` 裸相对路径（AI 的 cwd 不是技能目录，会解析失败）
+
+---
+
 ## Step 0：前置校验
 
 ### 0.1 环境健康探活
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/check-env.js"
+node "<skill_dir>/scripts/check-env.js"
 ```
 
 **解读输出**：
@@ -45,16 +55,16 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/check-env.
 ### 0.2 定位工作空间根目录
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/find-workspace-root.js"
+node "<skill_dir>/scripts/find-workspace-root.js"
 ```
 
 **解读输出**：
 - 退出码 0 + 末行（纯路径） → WS_ROOT 绝对路径
 - 退出码 1 → 未找到工作空间根目录，**终止流程**
 
-> ⓘ **为什么不用 workspace-config.json 存在性判断**：init-worktree 会把 workspace-config.json 提交到主分支，`git worktree add` 会自动 checkout 副本到 worktree 目录中。若用 workspace-config.json 存在性判断，在 worktree 内执行时会错误地把 worktree 目录当作 WS_ROOT。使用 `git worktree list` 的第一行（git 契约上始终为主仓库绝对路径）则不受该问题影响。
+> ⓘ **为什么不用 CBB-WORKSPACE.json 存在性判断**：init-worktree 会把 CBB-WORKSPACE.json 提交到主分支，`git worktree add` 会自动 checkout 副本到 worktree 目录中。若用 CBB-WORKSPACE.json 存在性判断，在 worktree 内执行时会错误地把 worktree 目录当作 WS_ROOT。使用 `git worktree list` 的第一行（git 契约上始终为主仓库绝对路径）则不受该问题影响。
 
-> close-worktree 是 init-worktree 的逆操作，但本步骤的 WS_ROOT 定位逻辑与 init-worktree 不同：init-worktree 强制根目录执行（不需要处理 worktree 场景），close-worktree 支持 worktree 内执行（需要绕开 workspace-config.json 副本陷阱）。
+> close-worktree 是 init-worktree 的逆操作，但本步骤的 WS_ROOT 定位逻辑与 init-worktree 不同：init-worktree 强制根目录执行（不需要处理 worktree 场景），close-worktree 支持 worktree 内执行（需要绕开 CBB-WORKSPACE.json 副本陷阱）。
 
 ---
 
@@ -69,7 +79,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/find-works
 3. AI agent 列出 `.worktrees/` 下的所有 worktree：
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/find-target-worktree.js "<ws_root>"
+node "<skill_dir>/scripts/find-target-worktree.js "<ws_root>"
 ```
 
 > 注：本技能支持工作空间根目录或 worktree 内执行，find-target-worktree 自动从 cwd 反推或列出。
@@ -84,29 +94,30 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/find-targe
 ### 1.2 发现关联应用 worktree
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/discover-apps.js "<ws_root>" "<branch>"
+node "<skill_dir>/scripts/discover-apps.js "<ws_root>" "<branch>"
 ```
 
-脚本自动从 `workspace-config.json` 读取应用列表，扫描 `.worktrees/worktree-<branch>/<应用名>/` 实际存在的子目录。
+脚本自动从 `CBB-WORKSPACE.json` 读取应用列表，扫描 `.worktrees/worktree-<branch>/.codespace/<应用名>/`（兼容 ≤beta.23 旧平铺 `<应用名>/`）实际存在的子目录。
 
 **解读末行 `DISCOVER_RESULT`**：
 - `workspace` 字段：workspace worktree 绝对路径（AI agent 记录供后续命令使用）
 - `apps` 数组：实际存在的应用 worktree 列表（每项含 `name`, `repo`, `side`, `wt_path`, `app_path`）
 
-> 说明：app worktree 物理嵌套在 workspace worktree 内，移除 workspace worktree 时嵌套的子目录会一并消失，但各 app 仓库的 git worktree 元数据（`.git/worktrees/`）仍需通过 `git worktree remove` 逐个清理。AI 配置目录（`.claude/`、`.qoder/`、`.cbb/`）在每个 worktree 内由 init-worktree 独立安装，随 worktree 目录删除而清理，skill 无需特殊处理。
+> 说明：app worktree 物理嵌套在 workspace worktree 的 `.codespace/` 容器内，移除 workspace worktree 时嵌套的子目录会一并消失，但各 app 仓库的 git worktree 元数据（`.git/worktrees/`）仍需通过 `git worktree remove` 逐个清理。AI 配置经 junction 链入 worktree（只读内容子目录指向空间根唯一物理副本），随 worktree 目录一并消失，无需特殊处理。
 
 ### 1.3 检查未归档 change
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/check-unarchived.js "<ws_root>"
+node "<skill_dir>/scripts/check-unarchived.js "<ws_root>" "<branch>"
 ```
 
-脚本扫描 `openspec/changes/` 目录，筛选出非 `archive/` 子目录的 change 名称列表。
+脚本**双扫**（ADR 0002）：空间根当前检出的 `openspec/changes/`（本地模式产物）与 `.worktrees/worktree-<branch>/openspec/changes/`（worktree 模式产物），返回未归档 change 名称合集。
 
 **解读末行 `UNARCHIVED_RESULT`**：
-- `changes`：未归档 change 名称数组（空数组 = 全部已归档）
-- 退出码 0 → 检查完成（无论是否有未归档 change）
-- 退出码 1 → `openspec/changes/` 目录不存在，视为无未归档 change
+- `changes`：未归档 change 名称合集（空数组 = 两处全部已归档）
+- `detail`：每个 change 的来源（`root` / `worktree` / `both`）——Step 3.2 归档与 Step 4.1 执行归档时按来源定位目录
+- 退出码 0 → 检查完成（无论是否有未归档 change；目录不存在视为该处无 change）
+- 退出码 1 → 参数错误
 
 > ⓘ 本检查为信息收集性质，不阻断流程。结果将在 Step 3 用户决策时展示。
 
@@ -117,7 +128,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/check-unar
 对 workspace worktree 和每个关联应用 worktree，依次执行三项检查并汇总成安全状态表。**这是破坏性操作前的必经环节，结果将驱动 Step 3 的用户决策。**
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/safety-check.js "<ws_root>" "<branch>"
+node "<skill_dir>/scripts/safety-check.js "<ws_root>" "<branch>"
 ```
 
 脚本内部对每个仓库自动执行：
@@ -201,10 +212,12 @@ AskUserQuestion({
 
 **归档执行逻辑**（用户选择归档后，在 Step 4 中依次对每个待归档 change 执行）：
 
+> 落点按 Step 1.3 `detail` 的来源决定：`root` → 在 `<ws_root>/openspec/changes/` 执行；`worktree` → 在 `.worktrees/worktree-<branch>/openspec/changes/` 执行；`both` → 先向用户确认以哪份为准（通常 worktree 内为最新）。
+
 1. `openspec status --change "<name>" --json` → 检查 artifacts 完成状态
 2. 读取 `tasks.md` → 检查任务完成状态
 3. 检查 `openspec/changes/<name>/specs/` → 判断 delta specs 是否需要同步
-4. 执行归档（`mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>`）
+4. 执行归档（`mv <来源目录>/openspec/changes/<name> <来源目录>/openspec/changes/archive/YYYY-MM-DD-<name>`）
 
 **逐项确认规则**：
 - 若某个 change 有 artifacts 或 tasks 未完成 → 对该 change 单独弹出确认：*"<name> 有 N 个任务未完成，仍要归档吗？"*
@@ -226,10 +239,10 @@ AskUserQuestion({
 
 ```bash
 # 仅删本地分支（已合并自动 -d，未合并自动 -D；含 squash 合并 -D 兜底）
-node "<skill>/scripts/delete-branches.js" "<ws_root>" "<branch>" local
+node "<skill_dir>/scripts/delete-branches.js" "<ws_root>" "<branch>" local
 
 # 删本地 + 远程分支
-node "<skill>/scripts/delete-branches.js" "<ws_root>" "<branch>" local_remote
+node "<skill_dir>/scripts/delete-branches.js" "<ws_root>" "<branch>" local_remote
 ```
 
 **调用前的强警告**（调用方需自评）：
@@ -260,7 +273,7 @@ node "<skill>/scripts/delete-branches.js" "<ws_root>" "<branch>" local_remote
   [中止] 终止流程，我先手动处理
 ```
 
-- 用户选择「先推送」→ AI 引导用户执行 `cbb-worktree-push`（或 `/cbb:worktree-push`），完成后**重新跑** Step 2 safety-check 确认 `unpushed_count = 0` 再回到本步骤
+- 用户选择「先推送」→ AI 引导用户执行 `cbb-worktree-push` skill（或 `/cbb-worktree-push`），完成后**重新跑** Step 2 safety-check 确认 `unpushed_count = 0` 再回到本步骤
 - 用户选择「接受丢失」→ 必须二次确认（ahead 提交真的会丢），确认后继续 Step 4
 - 用户选择「中止」→ 终止流程
 
@@ -289,14 +302,14 @@ node "<skill>/scripts/delete-branches.js" "<ws_root>" "<branch>" local_remote
 **顺序：先移除各应用 worktree，再移除 workspace worktree**（逆序于创建；也为后续删分支扫清"分支仍被检出"的障碍）。
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/remove-worktrees.js "<ws_root>" "<branch>" "<force>"
+node "<skill_dir>/scripts/remove-worktrees.js "<ws_root>" "<branch>" "<force>"
 ```
 
 **三层降级策略**：`git worktree remove` 实际包含两个动作——①清理 git 元数据（`.git/worktrees/`）②删除物理目录。当 IDE 占用目录时 ② 会被 Windows 文件锁阻塞，但 ① 永远不受影响。脚本将这两个动作解耦：
 
 - **第 1 层（正常路径）：** `git worktree remove` 一步完成元数据 + 物理目录清理
 - **第 2 层（解耦清理）：** 当目录被锁时，先 `prune` 清理 git 元数据（始终成功），再 `rmdir`/`rm -rf` 尝试物理删除
-- **第 3 层（延迟清理）：** Windows 下 IDE 持有排他句柄时触发。元数据已清理保证分支删除不受影响；物理目录留给 init-worktree 下次创建时自愈（见 init Step 4.0）
+- **第 3 层（延迟清理）：** Windows 下 IDE 持有排他句柄时触发。元数据已清理保证分支删除不受影响；物理目录**不会被 init 自动删除**（0.0.3-beta.11 起 init 只 prune 元数据、绝不删目录，防误删活跃 worktree），需用户关闭 IDE 后手动删除，或重跑 close 补删
 
 **解读末行 `REMOVE_RESULT`**：
 - `has_locked: false` → 全部清理成功
@@ -310,21 +323,23 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/remove-wor
 
 所有 worktree 已成功移除后，如果当前 shell 的工作目录位于**已被关闭的 worktree 内**，需要主动让 IDE 窗口切回 `WS_ROOT`，避免 IDE 窗口指向已删除的目录。
 
-> ⓘ **本节是 close-worktree 专属逻辑**：与 init-worktree 的 Step 5 不共享、不交叉同步。init-worktree 负责"创建后**在新窗口打开** worktree"，本节负责"关闭后切回根目录"，两者职责独立。
+> ⓘ **本节是 close-worktree 专属逻辑**：与 init-worktree 的 Step 5 不共享、不交叉同步。init-worktree 负责"创建后把开发会话开进 worktree"，本节负责"关闭后切回根目录"，两者职责独立。
 
 **AI agent 行为**：
-1. 检查当前 cwd 是否在被关闭的 worktree 内
-2. 仅当匹配时，调用对应 IDE 的 `--reuse-window` 命令切回 WS_ROOT：
+1. 检查当前会话 / IDE 窗口是否指向被关闭的 worktree
+2. **OpenCode 等支持会话搬移的工具**：agent 亲自经 code-mode 调用 `opencode.session_move` 把会话切回 `<ws_root>`——自动完成、上下文保留、**不列入用户待办**，切完核对工作目录
+3. **Qoder / Cursor / VS Code**：调用对应 IDE 的 `--reuse-window` 命令切回 WS_ROOT：
    - Qoder → `qoder --reuse-window "<ws_root>"`
    - Cursor → `cursor --reuse-window "<ws_root>"`
    - VS Code → `code --reuse-window "<ws_root>"`
-3. **JetBrains 跳过主动切换**——`idea64 <path>` 会启动新进程或提示"打开/在新窗口打开"，让用户手动操作
+4. **JetBrains 跳过主动切换**——`idea64 <path>` 会启动新进程或提示"打开/在新窗口打开"，让用户手动操作
 
 **关键点**：
-- **只在 pwd 匹配被关闭的 worktree 时触发**——如果 IDE 窗口本身在 WS_ROOT 内，或会话位于其他目录，再切一次是多余的
+- **只在会话 / 窗口匹配被关闭的 worktree 时触发**——如果已在 WS_ROOT 内，再切一次是多余的
+- **OpenCode 会话切回是零成本自动动作**——`session_move` 复用当前会话（上下文保留、无新窗口），agent 亲自做，严禁推给用户
 - **仅切 Qoder / Cursor / VS Code**——这三者的 `--reuse-window` 是轻量级"切目录"，不重启 IDE
 - **不会产生孤立窗口**——`--reuse-window` 是复用当前窗口切换目录，**不会打开新窗口**。即使 IDE 已开着指向 WS_ROOT 的其他窗口，本步骤也不会重复创建，仅是把当前指向已删除目录的窗口切走
-- **失败不致命**——`--reuse-window` 失败时仅警告，后续分支删除不受影响
+- **失败不致命**——`session_move` / `--reuse-window` 失败时仅警告，后续分支删除不受影响
 
 ### 4.4 分支处理（默认跳过，按需手动调用）
 
@@ -333,9 +348,9 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/remove-wor
 如用户在 Step 1.1 选定 worktree 时已要求"删除分支"，或运行后需要单独清理，可在此步骤**手动调用**：
 
 ```bash
-node "<skill>/scripts/delete-branches.js" "<ws_root>" "<branch>" local
+node "<skill_dir>/scripts/delete-branches.js" "<ws_root>" "<branch>" local
 # 或
-node "<skill>/scripts/delete-branches.js" "<ws_root>" "<branch>" local_remote
+node "<skill_dir>/scripts/delete-branches.js" "<ws_root>" "<branch>" local_remote
 ```
 
 脚本内部对每个仓库：
@@ -371,6 +386,8 @@ git -C "<ws_root>" worktree list
 
 目标 worktree 应已不在列表中。
 
+**工作区回根交接（必须执行）**：若用户的开发会话工作在 worktree 内（当前会话工作目录 = 已删除的 `<wt_path>`），此刻目录已悬空——**OpenCode 等支持会话搬移的工具由 agent 自动 `session_move` 切回 `<ws_root>`，不列入用户待办**；无该能力的工具才提示用户把工作区切回 `<ws_root>`（打开文件夹 / Open Folder / 切换工作目录），并在最终报告中给出该绝对路径。
+
 ---
 
 ## 最终报告
@@ -380,16 +397,16 @@ git -C "<ws_root>" worktree list
   当前目录：<工作空间根目录绝对路径>
   已移除 worktree：
     - .worktrees/worktree-feature-xxx（workspace）
-    - .worktrees/worktree-feature-xxx/ep-user-info-server（嵌套，ep-user-info-server 仓库）
-    - .worktrees/worktree-feature-xxx/ep-user-management-app（嵌套，ep-user-management-app 仓库）
+    - .worktrees/worktree-feature-xxx/.codespace/ep-user-info-server（嵌套，ep-user-info-server 仓库）
+    - .worktrees/worktree-feature-xxx/.codespace/ep-user-management-app（嵌套，ep-user-management-app 仓库）
   未提交修改：已丢弃（--force）/ 无
   未归档 change 处理：
     ✅ ai-call-send-im-msg → 已归档到 archive/2026-07-08-ai-call-send-im-msg
     ⏭️  fix-payment-timeout → 用户选择跳过
     （无未归档 change 时不显示本节）
   分支处理：feature-xxx 已保留（默认行为；如需删除分支，手动调用 scripts/delete-branches.js）
-  AI 配置：worktree 内独立安装，随 worktree 删除而清理；工作空间根目录的 AI 配置保留
   剩余工作空间 worktree：<列出仍存在的，或 "无" >
+  👉 仅当所用工具不支持自动切根、且你的窗口仍停在已删除的 worktree 时，请手动切回工作空间根：<ws_root 绝对路径>
   Workspace cleaned up.
 ```
 
@@ -411,14 +428,14 @@ git -C "<ws_root>" worktree list
 - 未经用户确认用 `--force` 丢弃未提交修改，或主动调用 `delete-branches.js` 对未合并分支执行 `-D` 强删
 - 操作 `.worktrees/worktree-<需求名>` 以外的任何 worktree（如 `~/.qoder/worktree/...` 会话 worktree）
 - 移除/删除前跳过 Step 2 安全评估
-- 删除工作空间根目录的 AI 配置目录（`.claude/`、`.qoder/`、`.cbb/` 等源目录）
+- 删除工作空间根目录的 AI 配置目录（`.claude/`、`.qoder/`、`.opencode/` 等）
 - 用 `AskUserQuestion` 收集自由文本（分支名等直接对话提问）
 - 手动改任何仓库的 `.gitignore`（关闭流程不碰它）
 - 运行环境 node 不可用时强行继续 → 改为 fail-fast 提示用户
 
 ### 必须执行
 
-- 读 `workspace-config.json` 取应用名列表；以 `.worktrees/worktree-<需求名>/<应用名>/` 实际存在性确定关联清单
+- 读 `CBB-WORKSPACE.json` 取应用名列表；以 `.worktrees/worktree-<需求名>/.codespace/<应用名>/` 实际存在性确定关联清单
 - 移除/删除前执行安全评估（未提交修改 / 是否合并 / 是否推远程）并报告
 - 严格按 Step 4.2（移除 worktree）→ Step 4.4（删分支）顺序
 - 移除 workspace worktree 前先把会话移出（`cd "<WS_ROOT>" &&` 或 `git -C` 绝对路径）
@@ -429,7 +446,7 @@ git -C "<ws_root>" worktree list
 - **合并判定依赖刷新后的远程引用，故 Step 2.0 先主动 `git fetch`**：feature 多由他人经 MR 合入远端，本地引用否则会陈旧误判
 - **并行块用临时文件收结果、不用共享变量**：原 bash 版本中 `&` 后台任务跑在独立子 shell；Node.js 同步执行无此问题
 - **`.gitignore` 无需清理**：创建时的 `.worktrees/` 条目提交在 feature 分支上，删分支时随分支消失（未合并）或无害保留（已合并）
-- **AI 配置目录在每个 worktree 内独立安装**：关闭 worktree 时这些目录随 worktree 目录一起删除
+- **AI 配置在 worktree 内是 junction（链接）**：物理副本只在空间根（单层安装），worktree 删除时链接随目录树消失，无需清理动作
 - **部分 `worktree remove` 失败**：已移除的无需回退，未移除的报告详情让用户处理后重跑
 - **Windows IDE 目录锁的三层降级**：`git worktree remove` 内部做两件事——①清元数据 ②删目录。Windows 文件锁只阻塞 ②，不阻塞 ①
 

package/cbb/worktrees/skills/cbb-worktree-close/scripts/check-env.js

@@ -3,14 +3,14 @@ require('./silence-popup');
 /**
  * cbb-worktree-close 环境健康探活
  *
- * close-worktree 必须在工作空间根目录或 worktree 内执行，且需找到 workspace-config.json。
- * 与 init/extend 探活同构，但额外校验 workspace-config.json 存在性。
+ * close-worktree 必须在工作空间根目录或 worktree 内执行，且需找到 CBB-WORKSPACE.json。
+ * 与 init/extend 探活同构，但额外校验 CBB-WORKSPACE.json 存在性。
  *
  * 退出码：
  *   0 - 探活通过
  *   1 - 致命错误（git 不可用）
  *   2 - 当前不在 git 仓库
- *   3 - 未找到 workspace-config.json
+ *   3 - 未找到 CBB-WORKSPACE.json
  */
 
 const { execSync } = require('child_process');

package/cbb/worktrees/skills/cbb-worktree-close/scripts/check-unarchived.js

@@ -1,48 +1,75 @@
-#!/usr/bin/env node
-require('./silence-popup');
-/**
- * cbb-worktree-close 未归档 change 检查
- *
- * 用法：node check-unarchived.js <ws_root>
- *
- * 扫描 openspec/changes/ 目录，筛选出非 archive/ 子目录的 change 名称列表。
- * 本检查为信息收集性质，不阻断流程。
- *
- * 退出码：
- *   0 - 检查完成（无论是否有未归档 change）
- *   1 - 参数错误或 openspec/changes/ 目录不存在
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const wsRoot = process.argv[2];
-
-if (!wsRoot) {
-  console.error('Usage: node check-unarchived.js <ws_root>');
-  process.exit(1);
-}
-
-const changesDir = path.join(wsRoot, 'openspec', 'changes');
-
-if (!fs.existsSync(changesDir)) {
-  console.log('UNARCHIVED_RESULT {"changes":[]}');
-  process.exit(0);
-}
-
-let entries;
-try {
-  entries = fs.readdirSync(changesDir, { withFileTypes: true });
-} catch (e) {
-  console.error('Failed to read openspec/changes/:', e.message);
-  console.log('UNARCHIVED_RESULT {"changes":[]}');
-  process.exit(0);
-}
-
-const unarchived = entries
-  .filter(e => e.isDirectory() && e.name !== 'archive')
-  .map(e => e.name)
-  .sort();
-
-console.log('UNARCHIVED_RESULT', JSON.stringify({ changes: unarchived }));
-process.exit(0);
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * cbb-worktree-close 未归档 change 检查
+ *
+ * 用法：node check-unarchived.js <ws_root> [branch]
+ *
+ * 双扫（ADR 0002）：
+ *   - <ws_root>/openspec/changes/                       → 空间根当前检出（本地模式产物 / 空间根遗留）
+ *   - <ws_root>/.worktrees/worktree-<branch>/openspec/changes/ → worktree 模式产物
+ *     （branch 未传时跳过 worktree 扫描，保持旧调用兼容）
+ *
+ * 输出：changes 为两处合集（去重）；detail 标注每个 change 的来源
+ *       （'root' / 'worktree'，同名两处共存时为 'both'）。
+ * 本检查为信息收集性质，不阻断流程。
+ *
+ * 退出码：
+ *   0 - 检查完成（无论是否有未归档 change）
+ *   1 - 参数错误
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const wsRoot = process.argv[2];
+const branch = process.argv[3];
+
+if (!wsRoot) {
+  console.error('Usage: node check-unarchived.js <ws_root> [branch]');
+  process.exit(1);
+}
+
+/**
+ * 扫描单个 changes 目录，返回未归档 change 名数组（目录不存在返回 []）。
+ */
+function scanDir(changesDir) {
+  if (!fs.existsSync(changesDir)) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(changesDir, { withFileTypes: true });
+  } catch (e) {
+    console.error('Failed to read ' + changesDir + ':', e.message);
+    return [];
+  }
+  return entries
+    .filter(e => e.isDirectory() && e.name !== 'archive')
+    .map(e => e.name);
+}
+
+const rootChanges = scanDir(path.join(wsRoot, 'openspec', 'changes'));
+
+const worktreeDir = branch
+  ? path.join(wsRoot, '.worktrees', 'worktree-' + branch, 'openspec', 'changes')
+  : null;
+const wtChanges = worktreeDir ? scanDir(worktreeDir) : [];
+
+const detail = {};
+for (const name of rootChanges) detail[name] = 'root';
+for (const name of wtChanges) {
+  detail[name] = detail[name] === 'root' ? 'both' : 'worktree';
+}
+
+const changes = Object.keys(detail).sort();
+
+if (rootChanges.length === 0 && wtChanges.length === 0) {
+  console.log('ℹ️  未发现未归档 change（根与 worktree' + (worktreeDir ? '' : '（未指定 branch，跳过）') + '均无）');
+} else {
+  console.log('ℹ️  未归档 change：' + (changes.join(', ') || '无'));
+  for (const name of changes) {
+    console.log('    - ' + name + '（来源：' + detail[name] + '）');
+  }
+}
+
+console.log('UNARCHIVED_RESULT', JSON.stringify({ changes, detail }));
+process.exit(0);

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

@@ -116,7 +116,7 @@ function deleteBranch(repoPath, name) {
   return true;
 }
 
-const configPath = path.join(wsRoot, 'workspace-config.json');
+const configPath = path.join(wsRoot, 'CBB-WORKSPACE.json');
 let config = {};
 try { config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch (e) {}