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

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

@@ -1,40 +1,42 @@
 ---
 name: cbb-worktree-init
-description: "为一个需求在 workspace 与各关联应用仓库（= workspace-config.json 全量 apps）同步创建同名物理 git worktree，直聚在 `.worktrees/worktree-<需求名>/` 下。触发：用户明确要求创建需求工作空间/开发隔离环境，或为已有需求补齐新增应用（重跑本技能即幂等）。禁止自动串联 cbb-worktree-close——除非用户明确说了要关闭。"
-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
+description: "为一个需求在 workspace 与各关联应用仓库同步创建同名物理 git worktree，直聚在 `.worktrees/worktree-<需求名>/` 下，并把 AI 配置以 junction 链入工作树（开发会话开进 worktree）。触发：用户明确要求创建需求工作空间/开发隔离环境/并行开发，或双模式选择时用户选 worktree 模式，或为已有需求补齐新增应用（重跑本技能即幂等）。单线程快改且不需要隔离时引导用 cbb-local-mode（本地模式）。禁止自动串联 cbb-worktree-close——除非用户明确说了要关闭。"
 ---
 
-# Init Worktree（跨平台脚本化版本 v2.0）
+# Init Worktree（跨平台脚本化版本 v3.0）
 
-为一个需求在 workspace 与各关联应用仓库同步创建同名 git worktree，物理直聚在 `.worktrees/worktree-<需求名>/` 目录下。当你需要跨多个微服务仓库并行开发某个需求时，本技能一次性完成工作空间和所有关联应用仓库的 worktree 创建。
+为一个需求在 workspace 与各关联应用仓库同步创建同名 git worktree，物理直聚在 `.worktrees/worktree-<需求名>/` 目录下。当你需要跨多个微服务仓库并行开发某个需求、或需要隔离环境时，本技能一次性完成工作空间和关联应用仓库的 worktree 创建（ADR 0002 worktree 模式）。
 
 **启动时声明：** "我正在使用 cbb-worktree-init 技能来创建多仓库联动的隔离 worktree 环境。"
 
 ## 核心原则
 
 - 本技能的所有原子操作封装为 `scripts/*.js` Node.js 脚本，**跨平台执行**（Windows PowerShell / macOS bash / Linux bash / Git Bash 均无需适配）
-- 物理位置与 `init-worktree` 兼容：`.worktrees/worktree-<需求名>/<应用名>/`
-- 所有仓库使用统一的分支名（不加前缀）；worktree 目录名自动加 `worktree-` 前缀
-- **本技能必须在业务工作空间根目录执行**（即由 `cbb setup` 初始化、包含 `workspace-config.json` 的目录）
+- 物理位置（ADR 0003）：workspace worktree 在 `.worktrees/worktree-<需求名>/`，各 app worktree 收拢在其 `.codespace/<应用名>/` 容器内——**镜像空间根布局**（应用检出恒在 `.codespace/<app>/`，相对路径两模式通用）
+- 所有仓库使用统一的分支名（不加前缀）；worktree 目录名自动加 `worktree-` 前缀；**分支基线统一取 `origin/<main>`（ADR 0002，不取 HEAD）**
+- **lazy push（ADR 0002）**：本技能**不向远端推送任何分支**——远端副作用收敛到 `cbb-worktree-push` 唯一出口；推送失败早暴露的职责由 push 技能的 dry-run 承担
+- **AI 配置 junction（ADR 0002 防线 B）**：创建 worktree 后把根的 AI 配置**内容子目录**（rules / skills / commands）junction 进工作树——开发会话开在 `<wt_path>`（上游 `/opsx:*` 相对路径原样生效，零翻译）；工具状态落在工作树自建空壳目录，不互相污染；`cbb update` 在根跑一次全 worktree 生效
+- **本技能必须在业务工作空间根目录执行**（即由 `cbb setup` 初始化、包含 `CBB-WORKSPACE.json` 的目录）
 - 输入约定：**自由文本**（需求名等）直接在对话中提问并等待回复，禁止使用 `AskUserQuestion`；`AskUserQuestion` 仅用于固定选项决策场景（如 push 失败处理、远程分支已存在时的二选一）
-- 关联应用固定为 `workspace-config.json` 的**全量 apps**（无勾选选择）；需要增减应用时编辑该文件并重跑本技能（幂等）
+- 关联应用恒为 `CBB-WORKSPACE.json` 的**全量 apps**，AI 不询问范围、不从需求语境收窄（worktree 单仓库创建成本低，全量镜像空间根布局）；仅当**用户显式点名**应用时才经 `--apps` 传子集（见 Step 1），需要增减应用时编辑该文件并重跑本技能（幂等）
+- **模式选择（ADR 0002）**：接到需求先判断用户要哪种模式——要**并行 / 隔离** → 本技能；**单线程快改、当前会话就地干** → 引导 `cbb-local-mode`。用户明确指定即遵从，agent 只给推荐不代决
 
 ---
 
 ## 调用脚本的统一方式
 
-**重要**：所有脚本必须用**绝对路径**调用。`./scripts/...` 相对路径在 Agent 运行环境中不适用（AI agent 的 cwd 不一定是技能目录）。
+**重要**：本技能的所有脚本位于**本 SKILL.md 所在目录的 `scripts/` 下**（skill 目录）。
 
-调用方式（推荐用绝对路径）：
-```
-node "D:\workspace\<用户工作空间>\.qoder\skills\cbb-worktree-init\scripts\<name>.js" <参数>
+调用时用**本技能目录的绝对路径**拼接脚本名（AI 读取本 SKILL.md 时即已知该目录），例如：
+
+```bash
+node "<skill_dir>/scripts/<name>.js" <参数>
 ```
 
+> - `<skill_dir>` = 本 SKILL.md 所在目录的绝对路径（AI 从读取路径即可推出）
+> - **cwd 必须保持在工作空间根目录**：脚本按 cwd 定位 `CBB-WORKSPACE.json` 与 git 仓库
+> - 不要用 `./scripts/...` 裸相对路径（AI 的 cwd 不是技能目录，会解析失败）
+
 脚本输出：
 - 人类可读报告（OK / FAIL / WARN）
 - 机器可读摘要（末行以 XXX_OK / XXX_FAILED / XXX_RESULT 开头）
@@ -45,7 +47,7 @@ node "D:\workspace\<用户工作空间>\.qoder\skills\cbb-worktree-init\scripts\
 - `<branch>`：需求名字符串
 - `<wt_path>`：worktree 绝对路径
 
-所有脚本读 workspace-config.json：app 列表从 `<ws_root>/workspace-config.json` 读取，不需要传 JSON 参数。
+所有脚本读 CBB-WORKSPACE.json：app 列表从 `<ws_root>/CBB-WORKSPACE.json` 读取，不需要传 JSON 参数。
 
 ---
 
@@ -54,7 +56,7 @@ node "D:\workspace\<用户工作空间>\.qoder\skills\cbb-worktree-init\scripts\
 ### 0.1 环境健康探活
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-env.js"
+node "<skill_dir>/scripts/check-env.js"
 ```
 
 **解读输出**：
@@ -67,7 +69,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-env.j
 提前检测权限/版本问题，把可能在后续步骤暴露的失败前移到流程最开始：
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-env-deep.js"
+node "<skill_dir>/scripts/check-env-deep.js"
 ```
 
 **解读输出**：
@@ -78,10 +80,10 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-env-d
 - Node.js >= 16.7.0
 - `.worktrees/` 目录可写
 
-### 0.2 读取并校验 workspace-config.json
+### 0.2 读取并校验 CBB-WORKSPACE.json
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/parse-config.js"
+node "<skill_dir>/scripts/parse-config.js"
 ```
 
 **解读输出**：
@@ -91,23 +93,23 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/parse-confi
 
 ### 0.3 配置引导
 
-当 `workspace-config.json` 缺失、`apps` 为空或格式错误时，向用户说明情况并给出两个选项：
+当 `CBB-WORKSPACE.json` 缺失、`apps` 为空或格式错误时，向用户说明情况并给出两个选项：
 
 ```
-⚠️ 当前工作空间尚未配置关联应用（workspace-config.json 缺失或 apps 为空）。
+⚠️ 当前工作空间尚未配置关联应用（CBB-WORKSPACE.json 缺失或 apps 为空）。
 worktree 需要知道要关联哪些应用仓库。
 
 请选择：
-  [1] 我自行配置 workspace-config.json，配好后告诉你继续
-  [2] 提供应用仓库地址，我帮你写入 workspace-config.json
+  [1] 我自行配置 CBB-WORKSPACE.json，配好后告诉你继续
+  [2] 提供应用仓库地址，我帮你写入 CBB-WORKSPACE.json
 ```
 
 **选项 1：用户自行配置**
 - 停止当前技能流程
-- 提示用户：*"请编辑 workspace-config.json 后回复'继续'，或重新执行 init-worktree。"*
+- 提示用户：*"请编辑 CBB-WORKSPACE.json 后回复'继续'，或重新执行 init-worktree。"*
 - 用户回复"继续"后，重新从 Step 0 开始校验
 
-**选项 2：帮用户写入 workspace-config.json**
+**选项 2：帮用户写入 CBB-WORKSPACE.json**
 - 直接在对话中请用户提供应用信息，格式示例：
   ```
   应用名: ep-user-auth-app
@@ -118,7 +120,7 @@ worktree 需要知道要关联哪些应用仓库。
   仓库地址: git@code.example.com:team/ep-user-info-server.git
   类型: back（可选值：front 前端 / back 后端 / mixed 前后端混合）
   ```
-- 解析后写入 `workspace-config.json`：
+- 解析后写入 `CBB-WORKSPACE.json`：
   ```json
   {
     "apps": [
@@ -129,43 +131,43 @@ worktree 需要知道要关联哪些应用仓库。
   ```
 - 写入成功后提交到当前分支（确保 Step 2 状态检查通过）：
   ```bash
-  git add workspace-config.json
-  git commit -m "chore: add workspace-config.json"
+  git add CBB-WORKSPACE.json
+  git commit -m "chore: add CBB-WORKSPACE.json"
   ```
   > 若当前不在主分支上，提示用户切回主分支后再提交；若已在主分支上则直接提交。
 - 提交后重新从 Step 0 校验，通过后继续 Step 1
 
-> ⚠️ **禁止**：在 workspace-config.json 无效时跳过本步骤直接创建 worktree，否则无法确定关联应用。
+> ⚠️ **禁止**：在 CBB-WORKSPACE.json 无效时跳过本步骤直接创建 worktree，否则无法确定关联应用。
 
 ---
 
 ## Step 1：关联应用与代码同步
 
-> ⓘ **关联应用 = `workspace-config.json` 的全量 apps，无勾选选择**。所有脚本自行从 `<ws_root>/workspace-config.json` 读取应用列表，无需 AI 传递应用参数。
-> 需要增减应用时，编辑 `workspace-config.json` 后**重跑本技能**即可（幂等，已存在的分支/worktree 自动复用，详见「幂等重跑」章节）。
+> ⓘ **关联应用 = 全量 apps**：直接使用 `CBB-WORKSPACE.json` 的全部应用，**不询问范围、不从需求语境收窄**。仅当用户显式点名应用（如"只建 jspg-cvat"，典型用于排除状态异常的无关仓库）时才传子集。范围判断错了零代价——重跑本技能幂等补齐（已存在的分支/worktree 自动复用，详见「幂等重跑」章节）。
+> 需要增减应用时，编辑 `CBB-WORKSPACE.json` 后**重跑本技能**即可。
 
 ### 1.1 同步 `.codespace/` 目录代码
 
 ```bash
 # ws_root 来自 AI agent 维护的状态
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/sync-repos.js" "<ws_root>"
+node "<skill_dir>/scripts/sync-repos.js" "<ws_root>"
 ```
 
 **用法**：
-- `<ws_root>`：工作空间根绝对路径（apps 由脚本内部从 `<ws_root>/workspace-config.json` 读取）
+- `<ws_root>`：工作空间根绝对路径（apps 由脚本内部从 `<ws_root>/CBB-WORKSPACE.json` 读取，全量 fetch/clone）
 
 **解读输出**：
 - 退出码 0 + 末行 `SYNC_RESULT [...]` → 全部成功
 - 退出码 2 + 末行 `SYNC_RESULT [...]`（含 `clone-failed` 项）→ 部分 clone 失败，**终止流程**
 
-> ⓘ **`.codespace/` 目录**：所有应用代码统一存放在工作空间的 `.codespace/` 下。基准代码由 `cbb setup` 命令首次 clone，本脚本检查时如已存在则 fetch 更新（秒级），不存在则 clone 兜底。该目录在 Step 3.2 加入 `.gitignore`，不被 workspace 仓库跟踪。
+> ⓘ **`.codespace/` 目录**：各应用的**标准本地检出**（基准 = `origin/main`，ADR 0002）。首次由 `cbb setup` clone，本脚本如已存在则 fetch 更新（秒级），不存在则 clone 兜底（并补装提交防线 hook）。该目录已 gitignore，不被 workspace 仓库跟踪。本地模式进行中本脚本仍可安全执行（fetch 不动工作区/分支）。
 
 ### 1.2 最终输出
 
-列出本次关联的应用（`workspace-config.json` 全量）及本地路径（保留序号便于复核），向用户展示并确认：
+列出本次关联的应用（全量，或用户显式指定的子集）及本地路径（保留序号便于复核），**仅作信息展示，不作为提问确认点**：
 
 ```
-确认关联应用（workspace-config.json 全量）：
+关联应用（需求 <需求名>，全量）：
   后端：
     [1] ep-user-auth-app  → .codespace/ep-user-auth-app
     [2] ep-user-info-server → .codespace/ep-user-info-server
@@ -173,7 +175,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/sync-repos.
     [3] ep-user-web → .codespace/ep-user-web
 ```
 
-> 后续所有步骤中的 `APP_REPOS` 均指向 `$WS_ROOT/.codespace/<应用名>/`，不再依赖开发者手动配置本地路径。
+> 后续所有步骤中的 `APP_REPOS` 均指向 `$WS_ROOT/.codespace/<应用名>/`，不再依赖开发者手动配置本地路径。**缺省不传 `--apps`（= 全量）；仅当用户显式点名应用时，才把子集名单经 `--apps` 参数传给 Step 3.3 / 3.5 脚本（逗号分隔）。**
 
 ---
 
@@ -192,7 +194,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/sync-repos.
 | 当前在主分支上 | ✅ | ❌ |
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-repos.js" "<ws_root>"
+node "<skill_dir>/scripts/check-repos.js" "<ws_root>"
 ```
 
 **解读输出**：
@@ -220,84 +222,69 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-repos
 ### 3.2 安全更新 .gitignore（前置）
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/update-gitignore.js "<ws_root>" "<branch>"
+node "<skill_dir>/scripts/update-gitignore.js" "<ws_root>" "<branch>"
 ```
 
-脚本内部自动完成：stash 保护 → 切分支 → 添加 `.worktrees/` 和 `.codespace/` → 提交 → 切回 → pop stash
+脚本内部自动完成：stash 保护 → 分支不存在则从 HEAD 创建 → 切分支 → 添加 `.worktrees/` 和 `.codespace/` → 提交 → 切回 → pop stash
 
 **解读输出**：
 - 退出码 0 + 末行 `GITIGNORE_OK` → 成功
 - 退出码 2 → 执行失败，**终止流程**
 
-> ⚠️ 必须在提交后切回主分支，否则 Step 3.4 的 `git worktree add` 会因分支已检出而失败（脚本已自动处理）。
+> ⓘ **分支自动创建**：本步骤先于 Step 3.3 执行，workspace 分支此时不存在，脚本会自动从 HEAD 创建（与 `create-branches.js` 对 workspace 的行为一致，Step 3.3 报 `reused`）。`.gitignore` 提交正好落在需求分支上，由 Step 3.4 push 一并推送。
+
+> ⚠️ 必须在提交后切回主分支，否则 Step 3.5 的 `git worktree add` 会因分支已检出而失败（脚本已自动处理）。
 
 ### 3.3 创建分支
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/create-branches.js" "<ws_root>" "<branch>"
+node "<skill_dir>/scripts/create-branches.js" "<ws_root>" "<branch>" [--apps "app1,app2"]
 ```
 
+- `--apps`：仅用户显式点名应用时传入（逗号分隔）；缺省 = 全量
+
 **解读输出**：
 - 退出码 0 + 末行 `BRANCH_RESULT [...]` → 全部创建或复用成功
 - 退出码 2 + 末行 `BRANCH_RESULT [...]`（含 `failed` 项）→ 部分失败，**终止流程**
 
 **报告示例**：
 ```
-✅ workspace: 分支 feature-login 创建成功（从 HEAD）
+✅ workspace: 分支 feature-login 创建成功（from origin/main）
 ⏭️  ep-user-auth-app: 分支已存在，复用
 ✅ ep-user-info-server: 分支 feature-login 创建成功（从 origin/main）
 ```
 
-> ⓘ **app 仓库从 `origin/main` 创建分支**：Step 2 已 fetch 确保 `origin/main` 引用是最新的。此方式不依赖 app 仓库当前在哪个分支、是否有未提交修改，实现与本地工作目录状态完全解耦。
+> ⓘ **统一从 `origin/main` 创建分支（ADR 0002）**：workspace 与 app 仓库的分支基线均为 `origin/<main>`（Step 2 已 fetch 刷新）——不取 HEAD，本地模式进行中重跑本技能不被根检出状态污染；与 app 仓库当前在哪个分支、是否有未提交修改完全解耦。
 
-> ⚠️ 必须用 `git branch` 而非 `git checkout -b`：因为同一分支不能同时在主目录和 worktree 中检出，切换后 Step 3.4 的 `git worktree add` 会报 `fatal: '<branch>' is already checked out`。
+> ⚠️ 必须用 `git branch` 而非 `git checkout -b`：因为同一分支不能同时在主目录和 worktree 中检出，切换后 Step 3.5 的 `git worktree add` 会报 `fatal: '<branch>' is already checked out`。
 
 **情况 B：任一仓库已存在该分支 → 复用**
 - 脚本自动跳过已存在分支（`status: 'reused'`），不阻塞流程
 - 不再提供「复用/修改/中断」选项（脚本自动处理）
+- 本地模式遗留的分支同样直接复用（本地升级 worktree 场景：提交随身带走）
 
-### 3.4 推送并建立 upstream
+### 3.4 分支就位（lazy push，不推远端）
 
-```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/push-branches.js" "<ws_root>" "<branch>"
-```
+**本技能不执行任何远端推送（ADR 0002 lazy push）**：分支创建止步于本地。远端副作用收敛到 `cbb-worktree-push` 唯一出口（dry-run 预览 → agent 生成 commit 信息并提交 → push → MR 链接）——推送类失败（认证/网络/保护分支）在 push 技能内暴露并处理，不在创建流程中阻塞。
 
-脚本内部自动完成：
-1. **远程探测**：每个仓库先 `git remote` 确认存在远程名
-2. **推送**：执行 `git push -u <remote> <branch>` 推送并建立 upstream
-3. **错误归类**：stderr 含 `Permission denied (publickey)` / `Authentication failed` / `Could not resolve host` / `protected branch` / `already exists` / `non-fast-forward` 时归类为对应错误码
-4. **远程分支已存在**：自动采集 `git rev-parse` + `git log -1` 元信息（hash/author/date/message），附加到 PUSH_RESULT
-
-**解读输出：**
-- 退出码 0 + 末行 `PUSH_RESULT [...]` → 全部推送成功，继续 Step 3.5
-- 结果项 `skipped`（远程分支已存在且与本地一致）→ 幂等跳过，非失败
-- 退出码 2 + 末行 `PUSH_RESULT [...]`（含 `failed` 或 `remote-exists` 项）→ **阻塞流程，AI agent 必须询问用户决策**（见下方"失败处理"）
-
-**失败处理（AI agent 行为）：**
-
-| 错误码 | 处理 |
-|--------|------|
-| `ssh-auth-failed` / `https-auth-failed` / `network-unreachable` / `branch-protected` / `no-remote` / `non-fast-forward` / `unknown` | 输出失败明细，按 error 码分组汇总。AskUserQuestion 提供三个选项：1) 修复后重试（推荐） 2) 跳过失败仓库继续 3) 完全终止 |
-| `remote-exists` | 先在纯文本中输出远程 commit 元信息 + 本地 HEAD hash（**二次确认**），再 AskUserQuestion 提供两个选项：1) 关联到 origin/&lt;branch&gt;（执行 set-upstream-to） 2) 终止流程，关闭需求空间后重新创建 |
+> 旧版在本步骤推送空分支建立 upstream（`push-branches.js`），自 0.0.3-beta.22 起移除：避免每个需求在远端留下空分支尸体；`push-worktrees.js` 首次推送时自动建立 upstream，行为等价。
 
-**禁止：** 脚本**禁止**自动 `git branch --set-upstream-to=origin/<branch>`；AI 在询问关联前**必须**先输出 commit 元信息。
-
-**为什么 push 放在 worktree 之前：** 失败早暴露，无 worktree 损失；成功后再创建 worktree，分支天然有 upstream；独立脚本便于单测。
-
-### 3.5 创建 Worktree（含自愈清理）
+### 3.5 创建 Worktree
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/create-worktrees.js" "<ws_root>" "<branch>"
+node "<skill_dir>/scripts/create-worktrees.js" "<ws_root>" "<branch>" [--apps "app1,app2"]
 ```
 
+- `--apps`：与 Step 3.3 相同（仅用户显式点名时传入）；缺省 = 全量
+
 脚本内部自动完成：
-1. **自愈清理**：`git worktree prune` + 物理目录清理（close 因 IDE 锁未能删除的物理目录）
+1. **元数据自愈**：仅 `git worktree prune`（清理"目录已缺失/失效"的注册项）；**绝不删除任何物理目录**（0.0.3-beta.11 起——旧版"清理无元数据残留目录"因 Windows 路径分隔符不匹配会误删活跃 worktree，已整体移除）
 2. **workspace worktree 创建**：`git worktree add .worktrees/worktree-<branch> <branch>`
-3. **app worktree 创建**（物理嵌套在 workspace worktree 内）
+3. **app worktree 创建**（收拢在 workspace worktree 的 `.codespace/` 容器内，镜像空间根布局）；≤beta.23 旧平铺布局自动 `git worktree move` 迁移
 
 **解读输出**：
 - 退出码 0 + 末行 `WT_PATH <绝对路径>` → 全部成功，AI 解析出 worktree 绝对路径供后续 Step 4 使用
-- 退出码 2 → workspace worktree 创建失败（分支已检出/权限不足），**终止流程**
+- 退出码 2 → workspace worktree 创建失败（分支已检出/权限不足），或目标目录存在但非有效 worktree（上次 close 被 IDE 锁残留）——**终止流程**，按脚本提示引导用户跑 `cbb-worktree-close` 或手动删除该目录 + `git worktree prune` 后重跑
 - 退出码 3 → 部分 app worktree 创建失败，**报告已创建/失败详情，用户需手动清理**
 
 **报告示例**：
@@ -309,9 +296,23 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/create-work
 WT_PATH d:\workspace\xxx\.worktrees\worktree-feature-login
 ```
 
-> ⓘ **tracked 内容自动 checkout**：workspace 主分支 tracked 的所有内容（openspec/、cbb/ 等）在 workspace 工作树创建时**自动从 git 对象库 checkout**——**不需要 `cp`、`git clone` 或任何“带过来”动作**。各应用 worktree 同理。
+> ⓘ **tracked 内容自动 checkout**：workspace 主分支 tracked 的所有内容（openspec/、cbb/ 等）在 workspace 工作树创建时**自动从 git 对象库 checkout**——**不需要 `cp`、`git clone` 或任何"带过来"动作**。各应用 worktree 同理。
 
-> ⓘ **AI 配置目录（.claude/、.qoder/、.opencode/ 等）**：统一安装在业务空间根（`cbb setup` / `cbb update`），**worktree 内不安装**；AI 会话始终以空间根为基础，开发动作指向本 worktree 路径。
+### 3.6 链入 AI 配置（junction，ADR 0002 防线 B）
+
+```bash
+node "<skill_dir>/scripts/junction-ai-config.js" "<ws_root>" "<wt_path>"
+```
+
+脚本把根的 AI 配置**内容子目录**（`.claude/`、`.qoder/`、`.opencode/`、`.workbuddy/`、`.trae/`、`.minimax/` 下的 rules / skills / commands）junction 进工作树；`.opencode/opencode.json` 为文件则复制。
+
+**解读末行 `JUNCTION_RESULT`**：
+- 退出码 0 → linked / copied / skipped（幂等）任一组合均成功
+- 退出码 2 → junction 失败（权限/文件系统），报告后继续——**AI 配置缺失不阻塞流程**，开发会话仍可退回"根会话 + 显式路径"模式（hook 会拦住写错位置的 commit）
+
+> ⓘ **为何只 junction 内容子目录**：工具向配置根写状态（如 `.claude/settings.local.json`）落在工作树自建空壳目录，按项目隔离不串扰（ADR 0001 否决整目录链接的污染点由此规避）；内容唯一物理副本仍在根——`cbb update` 跑一次，全部 worktree 经 junction 即时生效。
+
+> ⓘ **AI 配置目录形态**：worktree 内 `<wt_path>/.claude/rules` 等是链接（指向根），`.claude/` 本身是物理目录（装工具状态）。**勿在 worktree 内手动改 rules/skills/commands**——改的是根的同一份；规范变更应走 `cbb update`。
 
 ---
 
@@ -319,37 +320,54 @@ WT_PATH d:\workspace\xxx\.worktrees\worktree-feature-login
 
 不执行脚本。AI agent 向用户输出最终报告（格式见「最终报告」），并完成以下交接声明：
 
-1. **继续在当前会话开发**：本技能不打开新窗口；需求工作目录为 `<wt_path>`
-2. **目录纪律**：本会话后续所有产生写操作的命令（git commit / openspec / 构建 / 测试等）必须以 `<wt_path>`（或其应用子目录）为工作目录（显式 `cd` 或绝对路径）；**禁止在空间根（主分支）执行任何写操作**
+1. **开发会话开进 worktree**（按工具形态，**能自动则 agent 亲自做，不推给用户**）：
+   - **OpenCode 等支持会话搬移的工具（桌面端单窗口工作流）**：由 **agent 自己**把当前会话的工作目录切到 `<wt_path>`（经 code-mode 调用 `opencode.session_move`，`directory = <wt_path>`）——聊天上下文保留、无需新窗口、**不列入用户待办**；AI 配置已 junction 就位（`/opsx:*` 等命令照常可用），`.codespace/<app>/...` 相对路径原样生效
+   - **无会话搬移能力的桌面端工具（Claude Code / Qoder 等）**：提示用户把当前窗口的工作区根切到 `<wt_path>`（打开文件夹 / Open Folder / 切换工作目录）
+   - **CLI / TUI agent**：新开会话于 `<wt_path>`；根会话保留作控制面——后续创建/关闭 worktree、`cbb update` 等空间级操作在此执行
+   - 无论哪种形态，**必须向用户报出空间根绝对路径 `<ws_root>`**（控制面地址：close 关闭 worktree 后回切用）
+2. **目录纪律（worktree 会话内自然成立）**：会话 cwd == 开发目录，上游相对路径原样生效；**分支感知 hook 已覆盖全部仓库**——任何落 main 的载荷提交会被拦截（大声失败是防线，不是故障）
 3. 不自动安装依赖：各仓库技术栈不一（Maven 依赖本机 `~/.m2` 全局共享、无需初始化；Node/Python 等由你进入 worktree 后执行正确的命令，如 `npm ci` / `pnpm`）
+4. **输出下一步建议**：最终报告必须包含「下一步建议」段（格式见「最终报告」），告知用户后续可走的流程；仅提示，不自动串联执行任何后续技能
 
 ---
 
 ## 最终报告
 
+> **输出纪律**：严格按下方格式输出，禁止追加规则提醒等额外段落；规则由 rules 系统在触发点呈现，不复述。
+
 最终报告格式：
 
 ```
 ✅ worktree 已创建：<wt_path>
-   关联应用：<应用名 → 嵌套路径> 列表
-📌 继续在当前会话开发：后续写操作命令一律以上述目录为工作目录
+   关联应用：<应用名 → .codespace/<应用名> 路径> 列表（全量，或用户显式指定的子集）
+🔗 AI 配置已 junction 就位：rules / skills / commands（cbb update 一处生效）
+📌 开发会话已开进 <wt_path>（OpenCode：agent 已自动切换会话工作目录；CLI 端：新开会话；无搬移能力的桌面端：已提示用户切根）
+   空间根路径（控制面，close 后回切）：<ws_root>
+👉 下一步建议：
+   1. 开始需求开发（开发会话内，二选一）：
+      - 走 OpenSpec 工作流：/opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive
+      - 或直接对话开发：把需求告诉我，在 <wt_path> 内实现
+   2. 开发中提交推送：说"提交并推送"（cbb-worktree-push；首次 push 自动建立 upstream）
+   3. 需求完成后：说"关闭工作空间"（cbb-worktree-close）
 ```
 
-> 若 Step 3.5 为部分失败（退出码 3），报告必须列出已创建/失败详情与回滚清理命令。
+> 若 Step 3.5 为部分失败（退出码 3），报告必须列出已创建/失败详情与回滚清理命令。
 
 ---
 
-## 幂等重跑（增减应用 / 中断恢复）
+## 幂等重跑（增减应用 / 中断恢复 / 本地模式升级）
 
 本技能可安全重跑：在业务工作空间根目录用**同一个需求名**再执行一次即可。
 
 | 场景 | 重跑行为 |
 |------|----------|
-| 空间新增了应用（编辑 `workspace-config.json` 后） | Step 1 拉取新应用代码 → Step 3.3 为新应用建分支 → Step 3.4 推送（已一致的分支 `skipped`，不一致则阻塞询问）→ Step 3.5 创建缺失的嵌套 worktree |
+| 空间新增了应用（编辑 `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` 关闭后重建 |
+| 应用从 config 移除 | 已创建的分支 / worktree **不会**自动删除；如需清理用 `cbb-worktree-close` skill 关闭后重建 |
+| **本地模式升级 worktree**（ADR 0002） | Step 3.3 分支已存在 → reused（本地阶段提交随身带走）；先 `git checkout main` 腾出各仓库本地检出，再重跑本技能 |
+| 本地模式进行中重跑 | 安全：分支基线取 `origin/main`（非 HEAD），不受根/应用检出状态影响；fetch 不动工作区 |
 
-> ⓘ 重跑**不会静默推送**开发中的本地提交：远程分支已存在但与本地不一致时，Step 3.4 走阻塞式 `remote-exists` 决策（展示 commit 元信息让用户选择）。
+> ⓘ 本技能**零远端副作用**（lazy push）：不存在"重跑推送开发中提交"的风险面——推送只发生在 `cbb-worktree-push`。
 
 ---
 
@@ -357,27 +375,27 @@ WT_PATH d:\workspace\xxx\.worktrees\worktree-feature-login
 
 | 场景 | 处理方式 |
 |------|----------|
-| `.worktrees/` 或 `.codespace/` 未在 `.gitignore` | workspace 仓库自动添加并提交（在 Step 3.2） |
+| `.worktrees/` / `.codespace/` 未在 `.gitignore` | `cbb setup` / `cbb update` 已写入（0.0.3-beta.22 起含 `.worktrees/`）；存量空间由 Step 3.2 补写提交 |
 | `git worktree add` 权限被拒 | 运行环境降级，中断并告知用户 |
 | 状态检查任一失败 | 终止并报告所有问题 |
 | 部分应用 worktree 创建失败 | 提示已创建的回滚清理命令 |
 | workspace 主分支 tracked 内容（openspec/、cbb/ 等） | 自动 checkout 到工作树，无需额外动作（cp/clone 都是多余的） |
-| AI 配置目录（.claude/、.qoder/、.opencode/ 等） | 统一安装在空间根（`cbb setup` / `cbb update`）；worktree 内不安装、也不需要 |
+| AI 配置目录（.claude/、.qoder/、.opencode/ 等） | Step 3.6 junction 内容子目录进工作树；唯一物理副本在空间根，`cbb update` 一处生效 |
 | 需求名（同时作分支名和工作树目录名） | 用户在对话中纯文本输入，参考 Step 3.1 命名规则（kebab-case，禁 `..`、路径分隔符、空格） |
-| 关联应用范围 | 固定为 `workspace-config.json` 全量 apps（无勾选）；增减应用后重跑本技能（幂等） |
+| 关联应用范围 | 恒为全量（不询问、不从需求语境收窄）；用户显式点名应用时 `--apps` 传子集；增减应用后重跑本技能（幂等） |
+| 单线程快改 / 不需要隔离 | 引导 cbb-local-mode（本地模式，就地切分支） |
 | 运行环境 node 不可用 | 脚本 fail-fast 并提示用户到系统终端重试 |
-| push 失败（SSH/HTTPS/网络/保护） | push-branches.js 退出码 2，AI 阻塞并询问用户三选项（修复后重试/跳过失败仓库/完全终止） |
-| 远程分支已存在 | push-branches.js 输出 metadata，AI 展示 commit 元信息后询问两选项（关联/终止+重新创建） |
-| 开发过程中推送所有 worktree | Step 3.4 仅覆盖创建时的空 commit；开发过程中产生的提交必须调 `/cbb:worktree-push` 或 `cbb-worktree-push` skill 推送（详见该 skill） |
+| 推送（认证/网络/保护分支/远程已存在） | 不在本技能——`cbb-worktree-push` 处理（lazy push，ADR 0002） |
+| 开发过程中推送所有 worktree | 对 cbb-worktree-push 说"提交并推送"；首次 push 自动建立 upstream |
 
 ---
 
 ## 常见错误
 
-### 跳过 workspace-config.json 直接硬编码仓库地址
+### 跳过 CBB-WORKSPACE.json 直接硬编码仓库地址
 
 - **问题：** 直接在代码中写死仓库 URL 或本地路径，不同团队的仓库地址不同
-- **修复：** 始终从 `workspace-config.json` 读取应用与远程仓库的映射；配置缺失/为空时按 Step 0.3 配置引导处理，不支持在流程中临时指定配置外的仓库
+- **修复：** 始终从 `CBB-WORKSPACE.json` 读取应用与远程仓库的映射；配置缺失/为空时按 Step 0.3 配置引导处理，不支持在流程中临时指定配置外的仓库
 
 ### 状态检查对 app 仓库执行完整五项检查
 
@@ -414,22 +432,12 @@ WT_PATH d:\workspace\xxx\.worktrees\worktree-feature-login
 - **问题：** 需求名需要用户自由输入文本，却用了 `AskUserQuestion` 工具，被迫提供预设选项
 - **修复：** 自由文本输入场景一律**直接在对话中提问**并等待用户文本回复；`AskUserQuestion` 仅用于固定选项的选择场景
 
-### 完成后未进入 worktree
-
-- **问题：** 流程结束后仍停留在工作空间根目录，或跨多次 Bash 调用后丢失 cwd，后续命令作用在错误上下文
-- **修复：** Step 5 起的所有命令用 `cd "<worktree 绝对路径>" && <cmd>` 单次 Bash 调用发起，首条命令后接 `pwd` 确认；最终报告首行输出 `当前目录`
-
-### push 失败时跳过失败仓库继续
-
-- **问题：** push 失败但 init-worktree 流程继续，导致后续 agent 在 worktree 中遇到无 upstream 分支
-- **修复：** push-branches.js 退出码 2 时必须阻塞流程并询问用户；不允许脚本或 AI 自动跳过失败仓库
+### 完成后开发会话未开进 worktree
 
-### 远程分支已存在时自动 set-upstream
+- **问题：** 流程结束后开发会话仍停留在工作空间根目录（junction 好的 AI 配置没人加载），agent 在根会话里靠路径翻译干活，回到第一代失败模式
+- **修复：** Step 4 交接必须确保"开发会话开在 `<wt_path>`"（OpenCode 等支持会话搬移的工具 = agent 亲自经 `session_move` 切换、不列入用户待办；无该能力的桌面端 = 提示用户切根；CLI = 新开会话）；根会话保留作控制面（worktree 生灭、`cbb update`）
 
-- **问题：** 看到 origin/&lt;branch&gt; 已存在就直接 `git branch --set-upstream-to`，可能关联到他人的同名分支
-- **修复：** 与本地完全一致时脚本幂等跳过（`skipped`，非失败）；不一致时输出 metadata 由用户决策（关联 vs 终止）；AI 在 AskUserQuestion 之前必须先输出 commit 元信息作为二次确认
-
-### 用 `git checkout -b` 在 push 后切分支
+### 用 `git checkout -b` 在创建 worktree 前切分支
 
 - **问题：** Step 3.5 创建 worktree 前先切到新分支，导致 worktree 创建时分支已检出冲突
 - **修复：** Step 3.3 已统一用 `git branch`（不切换）；Step 3.5 的 `git worktree add` 会自动处理 checkout
@@ -437,12 +445,13 @@ WT_PATH d:\workspace\xxx\.worktrees\worktree-feature-login
 ### 把脚本调用与 Shell 变量混用
 
 - **问题：** 试图在 Bash 调用中嵌套 Node 脚本与 shell 变量，导致变量解析失败
-- **修复：** 所有脚本参数（`<ws_root>`、`<branch>`）由 AI agent 在对话上下文中维护，**作为字符串参数传入脚本**，不要在 Bash 命令中拼 shell 变量
+- **修复：** 所有脚本参数（`<ws_root>`、`<branch>`、`--apps` 列表）由 AI agent 在对话上下文中维护，**作为字符串参数传入脚本**，不要在 Bash 命令中拼 shell 变量
+
+### 误把 hook 拦截当故障
 
-### 在空间根执行写操作命令
+- **问题：** 开发会话在 main 上误打载荷 commit 被分支感知 hook 拦截，agent 以为是环境故障，尝试绕过或反复重试
+- **修复：** 拦截是防线（ADR 0002）的正确行为——回需求分支重做；`--no-verify` 绕过仅限用户显式要求
 
-- **问题：** worktree 创建成功后，会话仍在空间根运行 git commit / openspec / 构建命令，污染主分支或把变更产物生成在主分支上
-- **修复：** Step 4 交接已声明需求工作目录 `<wt_path>`；所有写操作命令必须显式 `cd` 或用绝对路径指向 worktree
 
 ---
 
@@ -457,19 +466,17 @@ WT_PATH d:\workspace\xxx\.worktrees\worktree-feature-login
 - 用 `git checkout -b` 切分支后再建 worktree（分支检出冲突）
 - 用 `AskUserQuestion` 收集自由文本（需求名 / 分支选项等）
 - 运行环境 node 不可用时强行继续 → 改为 fail-fast 提示用户
-- **Step 3.4 推送失败后跳过失败仓库直接继续** → 必须阻塞并询问用户决策
-- **远程分支已存在时脚本自动 set-upstream-to** → 必须由用户决策，避免关联到他人的同名分支
-- **AI 询问关联选项前不输出 commit 元信息** → 必须先在 AskUserQuestion 之前输出远程 hash/author/date/message + 本地 hash
-- **在空间根执行 git/openspec/构建等写操作命令** → 必须显式指定需求工作树路径（`<wt_path>` 或其应用子目录）
+- **在本技能内向远端推送任何分支**（lazy push，ADR 0002）——推送只发生在 `cbb-worktree-push`
+- **hook 拦截 main 载荷提交后用 `--no-verify` 绕过**——仅限用户显式要求
 
 **必须执行**
 
 - workspace 仓库标准检查（当前在主分支等），app 仓库轻量检查（fetch + `origin/main` 可用即可）
-- app 仓库分支从 `origin/main` 创建（`git branch <需求名> ${REMOTE}/${MAIN}`），不依赖本地主分支状态
-- 严格 Step 3.3 → Step 3.4 顺序（先统一创建分支，再统一创建 worktree；workspace 工作树先建，各应用按序补建）
-- 所有脚本调用以 `node "<WS_ROOT>\.qoder\skills\cbb-worktree-init\scripts\<name>.js" "<绝对路径>" "<branch>"` 形式发起（apps 由脚本内部从 workspace-config.json 读取），**不依赖跨调用的 cwd**
-- **Step 3.4 push 步骤必须执行且插入在 create-branches.js (3.3) 之后、create-worktrees.js (3.5) 之前** — 失败时阻塞整个 init-worktree 流程
-- **Step 3.4 仅覆盖创建 worktree 时的空 commit** — 开发过程中产生的本地 commit（如 apply 任务实现）必须由用户在 worktree 中手动提交并调 `cbb-worktree-push` 推送；不允许依赖 Step 3.4 之后的自动推送（不存在）
+- 所有仓库分支统一从 `origin/<main>` 创建（`git branch <需求名> ${REMOTE}/${MAIN}`），不依赖本地检出状态（本地模式进行中重跑不受污染）
+- 严格 Step 3.3 → Step 3.5 顺序（先统一创建分支，再统一创建 worktree；workspace 工作树先建，各应用按序补建）
+- Step 3.6 junction AI 配置（失败不阻塞，但要报告）
+- 所有脚本调用以 `node "<skill_dir>/scripts/<name>.js" "<绝对路径>" "<branch>"` 形式发起（apps 缺省由脚本内部从 CBB-WORKSPACE.json 读取，子集用 `--apps` 传入）；**执行时 cwd 保持在工作空间根**（`check-env.js` / `parse-config.js` 按 cwd 定位）
+- Step 4 交接必须确保"开发会话开在 `<wt_path>`"（支持会话搬移的工具 = agent 自动 `session_move` 切换，**禁止把切根列入用户待办**；其余 = 用户切根 / CLI 新开会话）、空间根路径在案作控制面
 
 ---
 
@@ -478,11 +485,13 @@ WT_PATH d:\workspace\xxx\.worktrees\worktree-feature-login
 | 脚本 | 功能 | 参数 | 退出码 |
 |------|------|------|--------|
 | `check-env.js` | 环境探活 | 无 | 0/1/2 |
-| `parse-config.js` | 解析 workspace-config.json | 无 | 0/1/2 |
-| `sync-repos.js` | 同步 .codespace/ 仓库 | ws_root | 0/1/2 |
+| `parse-config.js` | 解析 CBB-WORKSPACE.json | 无 | 0/1/2 |
+| `sync-repos.js` | 同步 .codespace/ 仓库（兜底 clone 时补装提交防线 hook） | ws_root | 0/1/2 |
 | `check-repos.js` | 状态检查 | ws_root | 0/1/2 |
 | `update-gitignore.js` | 安全更新 .gitignore | ws_root, branch | 0/1/2 |
-| `create-branches.js` | 创建分支 | ws_root, branch | 0/1/2 |
-| `create-worktrees.js` | 创建 worktree（含自愈清理） | ws_root, branch | 0/1/2/3 |
-| `push-branches.js` | 推送并建立 upstream（已一致则 skipped；带错误归类 + 元信息采集） | ws_root, branch | 0/1/2 |
+| `create-branches.js` | 创建分支（统一从 origin/<main> 建） | ws_root, branch, [--apps] | 0/1/2 |
+| `create-worktrees.js` | 创建 worktree（仅 prune 元数据，不删物理目录） | ws_root, branch, [--apps] | 0/1/2/3 |
+| `junction-ai-config.js` | AI 配置内容子目录 junction 进工作树（ADR 0002 防线 B） | ws_root, wt_path | 0/1/2 |
 | `check-env-deep.js` | 环境健康自检（Node 版本 / 权限） | 无 | 0/2 |
+
+> `push-branches.js` 自 0.0.3-beta.22 起从本技能流程移除（lazy push，ADR 0002）；文件保留作历史参考，不再被任何步骤调用。

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

@@ -48,7 +48,7 @@ console.log('✅ git OK:', checks.git.out);
 const insideRepo = tryExec('git rev-parse --is-inside-work-tree');
 if (!insideRepo.ok || insideRepo.out !== 'true') {
   console.error('❌ 当前目录不是 Git 仓库');
-  console.error('   init-worktree 必须在工作空间根目录（包含 workspace-config.json）下执行');
+  console.error('   init-worktree 必须在工作空间根目录（包含 CBB-WORKSPACE.json）下执行');
   process.exit(2);
 }
 console.log('✅ 当前目录是 git 仓库');

package/cbb/worktrees/skills/cbb-worktree-init/scripts/check-repos.js

@@ -36,7 +36,7 @@ if (!wsRoot) {
 }
 
 function loadAppsFromConfig() {
-  const configPath = path.join(wsRoot, "workspace-config.json");
+  const configPath = path.join(wsRoot, "CBB-WORKSPACE.json");
   if (!fs.existsSync(configPath)) return null;
   try {
     const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
@@ -46,7 +46,7 @@ function loadAppsFromConfig() {
 
 const apps = loadAppsFromConfig();
 if (!apps) {
-  console.error("workspace-config.json missing or apps empty");
+  console.error("CBB-WORKSPACE.json missing or apps empty");
   process.exit(1);
 }