@jspg-ai/coding-bb 0.0.3-beta.21 → 0.0.3-beta.22

package/cbb/dev-standards/rules/cbb-ai-behavior.md

@@ -99,30 +99,37 @@ trigger: always_on
 
 **检验标准：** 用户从未因"AI 直接改了代码没打招呼"而感到意外。
 
-## 8. 业务空间目录纪律
+## 8. 业务空间开发模式（双模式，用户选择制）
 
-**仅当工作目录是业务空间根（存在 `workspace-config.json`）时生效。空间根支持两种开发模式，接到需求先判定本次属于哪种，再动手。**
+**仅当工作目录是业务空间根（存在 `workspace-config.json` 且 `.git` 为目录）时生效。空间支持两种开发模式，能力对称（都能修改 workspace 内容与应用代码、都强制分支隔离、交付都走 MR），由用户显式选择，agent 只给推荐不代决。**
 
-**模式一 · worktree 模式（默认；凡涉及应用代码改动必走此路）：**
+**模式一 · 本地模式（单线程快改，当前会话就地干）：**
 
-接到需求先建工作树（`cbb-worktree-init` skill，或斜杠命令 `/cbb-worktree-init`），之后：
+- 就地切分支：根 + 各涉及应用 `.codespace/<app>/` 同名 `checkout -b`（基线 = `origin/<main>`，经 `cbb-local-mode` 技能执行）
+- 当前会话原地开发，相对路径原样生效；**一次只承载一个需求**（独占本地检出；期间并行新需求走 worktree 模式，互不干扰）
+- 收尾：MR 合并后各参与仓库 `checkout main && pull && 删分支`
 
-- 一切产生写操作的命令（git commit / openspec / 构建 / 测试 / 文件修改）必须以 `.worktrees/worktree-<需求名>/`（或其应用子目录）为工作目录：显式 `cd` 或绝对路径
-- 不在空间根主分支提交应用代码、不在空间根创建本模式的 openspec 变更产物
-- 会话开始时确认本次需求对应的工作树路径；存在多个未完成工作树时，先与用户确认目标，不要猜
+**模式二 · worktree 模式（并行 / 隔离）：**
 
-**模式二 · 轻量模式（仅限空间根仓库自身内容：openspec 产物、docs、空间配置）：**
+- `cbb-worktree-init` 建隔离 worktree（AI 配置内容子目录已 junction 就位），**开发会话开进 `.worktrees/worktree-<需求名>/`**，可多需求并行
+- 根会话保留作控制面（worktree 生灭、`cbb update` 等空间级操作）
 
-需求完全不触碰任何应用代码文件时，可直接在空间根开发：变更产物落空间根 `openspec/`，走完整 opsx 流程后提交 main 分支，**提交后即 push——main 就是交付线，无 worktree、无 MR，不得悬空本地提交**。
+**基准与防线（两模式共同，ADR 0002）：**
 
-**两模式共同红线（无例外）：**
+- **基准 = `origin/main`（唯一真相源）；`.codespace/<app>/` 的检出 = 视图**——本地模式可暂态被需求分支占用，收尾恢复
+- **严禁直接在任何 main 检出上提交载荷**：分支感知 pre-commit hook 机械拦截（workspace 仓库仅放行控制面白名单：`workspace-config.json` / `.gitignore` / `AGENTS.md` / `openspec/config.yaml` / `openspec/schemas/**`；应用仓库 main 全拦）——**被拦是防线生效，不是故障**；`--no-verify` 绕过仅限用户显式要求
+- 远端推送唯一出口 = `cbb-worktree-push`（init 创建流程零远端操作，lazy push；空分支尸体不存在）
+- **模式误判零代价**：本地模式中途要并行/隔离 → 重跑 `cbb-worktree-init`（分支已存在自动复用，提交随身带走）
 
-- `.codespace/` 是工具维护的基准代码，不是开发区——任何模式下都不许在其中改应用代码
-- 只读命令（git status / log、查看文件）在空间根执行无妨
+**三时刻对齐（agent 必须遵守）：**
 
-**会话与工作目录是两回事：** AI 会话窗口始终停在**空间根**（worktree 内不装 AI 配置，无工作流命令），`/opsx:*` 等命令仍在空间根会话发起；worktree 模式下**产生写操作的工作目录**指向需求工作树（显式 `cd` 或绝对路径）。不要把会话切到 worktree 内。
+1. **开工前——状态自检**（`cbb-local-mode` 的 `check-local-state.js`）：干净态零交互直接开工；**遗留态（别的需求未收尾，任一仓库检出在非主干分支）必须让用户四选一**（继续 / 先收尾 / 升级 worktree / 丢弃），不得自行决定
+2. **开工时——布局确认**：向用户展示参与仓库与分支名，确认后执行
+3. **进行中——插单归属**：用户插入非本需求的改动，先确认归属（并入 / 收尾后处理 / 转 worktree），不得静默混入
 
-**检验标准：** worktree 模式的变更产物只出现在需求工作树内；空间根 main 的 `git status` 干净（除工具维护的配置文件外），且轻量模式产生的 main 提交都已 push（本地 main 不长期领先 origin/main）。
+**读基准代码约定：** 本地模式进行中，工作区是开发态而非基准——要读"main 现状"先确认检出分支，或直接 `git show main:<path>` / `git diff main`；不要默认工作区即基准。
+
+**检验标准：** 任何 main 检出上无载荷提交（hook 兜底，git log 可机械审计）；本地模式收尾后全部仓库回主干且 clean；worktree 模式的变更产物只出现在需求工作树内；远端分支只经 push 技能产生。
 
 ---
 

package/cbb/lib/install/init.js

@@ -76,7 +76,7 @@ const SUPERPOWERS_WHITELIST = [
 // worktree 管理 skill 清单：init / close / push 三件套（SKILL.md + scripts）。
 // 按 skill 形态部署到各工具的 skillsDir，使这三个能力可被 AI 在对话中自动触发
 // （description 驱动），同时工具也会把它们暴露为斜杠命令供用户手动指定。
-const WORKTREE_SKILLS = ['cbb-worktree-init', 'cbb-worktree-close', 'cbb-worktree-push'];
+const WORKTREE_SKILLS = ['cbb-worktree-init', 'cbb-worktree-close', 'cbb-worktree-push', 'cbb-local-mode'];
 
 // 装到空间的 tools skills：当前不分发。
 // cbb-design-to-wiki（Wiki 发布）与 cbb-wiki-ops 保留在源仓库，需要时加入本清单即恢复分发；Java 工具不装。
@@ -124,6 +124,9 @@ const { applyRuleRewrites } = require('./rule-rewrite');
 // .gitignore 条目决策（纯函数：检测/写入/卸载移除）
 const gitignore = require('../utils/gitignore');
 
+// git pre-commit hook：分支感知提交防线（ADR 0002，install/uninstall 调用）
+const githook = require('../utils/githook');
+
 // 业务空间配置（cbb setup 命令专用）
 const workspaces = require('./workspaces');
 
@@ -1232,6 +1235,14 @@ async function init(targetDir, options = {}) {
   // 更新 .gitignore
   updateGitignore();
 
+  // 安装分支感知提交防线（ADR 0002，仅业务空间根：空间根仓库 + .codespace/ 各应用）
+  let hookSummary = null;
+  if (isWorkspaceRoot) {
+    hookSummary = githook.installGitHooksForWorkspace(TARGET_DIR);
+    const appDone = hookSummary.apps.length;
+    log(`提交防线 pre-commit hook → 空间根 + ${appDone} 个应用仓库（${hookSummary.root}）`, 'success');
+  }
+
   // 完成摘要
   console.log(`\n  ✅ ${action}完成！\n`);
 
@@ -1266,6 +1277,7 @@ async function init(targetDir, options = {}) {
   if (hasSkills) extras.push('Skills');
   if (hasCommands) extras.push('Commands');
   if (hasHooks) extras.push('版本检查 hook');
+  if (hookSummary) extras.push('提交防线 pre-commit hook');
   if (agentsMdState === 'created') extras.push('AGENTS.md（空间导航）');
   if (extras.length > 0) {
     console.log(`  ${extras.join(' / ')} 已配置`);
@@ -2012,6 +2024,22 @@ async function uninstall() {
   // 清理 .gitignore
   cleanupGitignore();
 
+  // 移除分支感知提交防线（ADR 0002）：空间根 + .codespace/ 各应用（业务空间根专属）
+  if (detectWorkspaceRoot()) {
+    const results = [githook.uninstallGitHook(TARGET_DIR)];
+    const codeDir = path.join(TARGET_DIR, '.codespace');
+    if (fs.existsSync(codeDir)) {
+      for (const name of fs.readdirSync(codeDir)) {
+        const appDir = path.join(codeDir, name);
+        if (fs.existsSync(path.join(appDir, '.git'))) {
+          results.push(githook.uninstallGitHook(appDir));
+        }
+      }
+    }
+    const removedHooks = results.filter(r => r !== 'noop').length;
+    if (removedHooks > 0) log(`移除提交防线 pre-commit hook（${removedHooks} 个仓库）`, 'success');
+  }
+
   // 卸载用户级组件（如已确认）
   if (removeUserLevel) {
     console.log('');

package/cbb/lib/utils/githook.js

@@ -0,0 +1,224 @@
+'use strict';
+
+/**
+ * git pre-commit hook：分支感知提交防线（ADR 0002）。
+ *
+ * 策略（对当前仓库生效，worktree 与主仓库共享 .git/hooks 故一并覆盖）：
+ *   - 当前分支非主干（含 detached HEAD）→ 一律放行（两模式开发态都在需求分支上）
+ *   - workspace 仓库（检出含 workspace-config.json）在主干上 → 只放行控制面白名单路径：
+ *     workspace-config.json / .gitignore / AGENTS.md / openspec/config.yaml /
+ *     openspec/schemas/** / .cbb/**（配置变更与 cbb update 部署物，直改即推）
+ *   - 应用仓库在主干上 → 全拦（交付只走 MR）
+ *   - 逃生口：用户显式 git commit --no-verify（AI 侧纪律禁止自动绕过）
+ *
+ * 本模块是 hook 源码的唯一真源；cbb/worktrees/_shared/scripts/install-git-hook.js
+ * 部署到业务空间后独立运行，内嵌同一份源码副本（改动须两处同步）。
+ *
+ * 提供纯函数（isCbbHookContent / buildPreCommitSource）与 I/O 包装
+ * （installGitHook / uninstallGitHook），供 init.js 的 setup / update / uninstall 调用。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const HOOK_MARKER = 'managed-by-cbb';
+const HOOK_FILE = 'pre-commit';
+const BACKUP_SUFFIX = '.cbb-backup';
+
+// 部署到仓库后的 hook 源码（独立 Node 脚本，无外部依赖）。
+// 注意：源码内不使用反引号，便于本模块以模板字符串承载。
+const PRE_COMMIT_SOURCE = [
+  '#!/usr/bin/env node',
+  '// managed-by-cbb v1 —— 分支感知提交防线（ADR 0002）',
+  '// main 上：workspace 仓库只放行控制面白名单，应用仓库全拦；非 main 一律放行。',
+  '// 绕过逃生口仅限用户显式 git commit --no-verify。',
+  "const { execSync } = require('child_process');",
+  "const fs = require('fs');",
+  'function run(cmd) {',
+  "  try { return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim(); }",
+  '  catch (e) { return null; }',
+  '}',
+  "const branch = run('git branch --show-current') || '';",
+  '// 主干名：优先远端 HEAD 指向；探测失败按本地 main/master 存在性回退',
+  'let main = null;',
+  "const remotes = run('git remote');",
+  'if (remotes) {',
+  "  const r = remotes.split(/\\r?\\n/)[0];",
+  "  const sym = run('git symbolic-ref \"refs/remotes/' + r + '/HEAD\"');",
+  "  if (sym) main = sym.replace('refs/remotes/' + r + '/', '');",
+  '}',
+  "if (!main) {",
+  "  if (run('git rev-parse --verify --quiet refs/heads/main')) main = 'main';",
+  "  else if (run('git rev-parse --verify --quiet refs/heads/master')) main = 'master';",
+  '}',
+  '// 非主干（含 detached / 探测失败）→ 放行',
+  'if (!main || branch !== main) process.exit(0);',
+  '',
+  "// 主干上的提交：收集 staged 变更（空提交放行）",
+  "const staged = run('git diff --cached --name-only') || '';",
+  "const files = staged.split(/\\r?\\n/).filter(Boolean);",
+  'if (files.length === 0) process.exit(0);',
+  '',
+  '// 仓库类型：workspace 仓库 = 检出含 workspace-config.json',
+  "const isWorkspace = fs.existsSync('workspace-config.json');",
+  '',
+  'function deny(bad) {',
+  "  console.error('[cbb-guard] 主干上拦截载荷提交（ADR 0002）：');",
+  "  bad.forEach(f => console.error('  ' + f));",
+  "  console.error('需求载荷须在需求分支上提交：本地模式先 git checkout -b <需求名>；worktree 模式在 .worktrees/ 工作树内提交。');",
+  "  console.error('控制面白名单：workspace-config.json / .gitignore / AGENTS.md / openspec/config.yaml / openspec/schemas/** / .cbb/**');",
+  "  console.error('如确需在主干提交，须由用户显式 git commit --no-verify。');",
+  '  process.exit(1);',
+  '}',
+  '',
+  'if (isWorkspace) {',
+  "  const EXACT = new Set(['workspace-config.json', '.gitignore', 'AGENTS.md', 'openspec/config.yaml']);",
+  "  const PREFIXES = ['openspec/schemas/', '.cbb/'];",
+  '  const bad = files.filter(f => !EXACT.has(f) && !PREFIXES.some(p => f.indexOf(p) === 0));',
+  '  if (bad.length) deny(bad);',
+  '} else {',
+  '  deny(files);',
+  '}',
+  'process.exit(0);',
+].join('\n');
+
+/**
+ * 内容是否为本包管理的 hook（含标记行）。
+ */
+function isCbbHookContent(content) {
+  return typeof content === 'string' && content.includes(HOOK_MARKER);
+}
+
+/**
+ * hook 源码（纯函数，便于单测与未来按仓库定制）。
+ */
+function buildPreCommitSource() {
+  return PRE_COMMIT_SOURCE + '\n';
+}
+
+/**
+ * 解析仓库的 hooks 目录。
+ * 优先 core.hooksPath 配置（相对路径基于仓库根）；未配置或读取失败回退 .git/hooks。
+ * @returns {string|null} 绝对路径；目录不可用时返回 null（调用方跳过安装）
+ */
+function resolveHooksDir(repoPath) {
+  let configured = null;
+  try {
+    configured = execSync('git config core.hooksPath', {
+      cwd: repoPath,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    }).trim();
+  } catch (_) { /* 未配置 */ }
+
+  let dir;
+  if (configured) {
+    dir = path.isAbsolute(configured) ? configured : path.join(repoPath, configured);
+  } else {
+    const gitDir = path.join(repoPath, '.git');
+    if (!fs.existsSync(gitDir)) return null; // 非 git 仓库（或 .git 为 worktree 文件，见下）
+    // worktree 检出的 .git 是文件（内容 "gitdir: ..."）；hook 安装统一走主仓库，
+    // 调用方应传主仓库路径。此处对文件形态直接放弃，避免误建目录。
+    const st = fs.statSync(gitDir);
+    if (!st.isDirectory()) return null;
+    dir = path.join(gitDir, 'hooks');
+  }
+  return dir;
+}
+
+/**
+ * 安装（幂等，可用于升级覆盖）：
+ *   - 无既有 hook → 写入
+ *   - 既有本包 hook → 覆盖（升级）
+ *   - 既有用户 hook → 备份为 pre-commit.cbb-backup 后写入；卸载时恢复
+ * @param {string} repoPath 仓库根（主仓库；worktree 共享 hooks 无需重复安装）
+ * @returns {'installed' | 'updated' | 'skipped-not-git' | 'skipped-no-dir'}
+ */
+function installGitHook(repoPath) {
+  const dir = resolveHooksDir(repoPath);
+  if (!dir) return 'skipped-not-git';
+
+  const hookPath = path.join(dir, HOOK_FILE);
+  fs.mkdirSync(dir, { recursive: true });
+
+  let prev = null;
+  if (fs.existsSync(hookPath)) {
+    prev = fs.readFileSync(hookPath, 'utf-8');
+    if (isCbbHookContent(prev)) {
+      if (prev === buildPreCommitSource()) return 'updated'; // 幂等：同版本
+      fs.writeFileSync(hookPath, buildPreCommitSource());
+      return 'updated';
+    }
+    // 用户自有 hook：备份后接管
+    fs.writeFileSync(hookPath + BACKUP_SUFFIX, prev);
+  }
+  fs.writeFileSync(hookPath, buildPreCommitSource());
+  try { fs.chmodSync(hookPath, 0o755); } catch (_) { /* Windows 无压力 */ }
+  return 'installed';
+}
+
+/**
+ * 卸载：
+ *   - 当前 hook 是本包的 → 删除；有备份则恢复
+ *   - 当前 hook 非本包（用户已接管）→ 不动，仅清掉残留备份
+ * @returns {'removed' | 'restored-backup' | 'noop'}
+ */
+function uninstallGitHook(repoPath) {
+  const dir = resolveHooksDir(repoPath);
+  if (!dir) return 'noop';
+
+  const hookPath = path.join(dir, HOOK_FILE);
+  const backupPath = hookPath + BACKUP_SUFFIX;
+  let result = 'noop';
+
+  if (fs.existsSync(hookPath)) {
+    const content = fs.readFileSync(hookPath, 'utf-8');
+    if (isCbbHookContent(content)) {
+      fs.unlinkSync(hookPath);
+      result = 'removed';
+      if (fs.existsSync(backupPath)) {
+        fs.renameSync(backupPath, hookPath);
+        result = 'restored-backup';
+      }
+    }
+  } else if (fs.existsSync(backupPath)) {
+    // hook 已被用户删除但备份残留：不擅自恢复，只清备份
+    fs.unlinkSync(backupPath);
+  }
+  return result;
+}
+
+/**
+ * 对业务空间批量安装：空间根仓库 + .codespace/ 下每个应用仓库。
+ * @param {string} wsRoot 业务空间根
+ * @returns {{ root: string, apps: {name: string, status: string}[] }}
+ */
+function installGitHooksForWorkspace(wsRoot) {
+  const root = installGitHook(wsRoot);
+  const apps = [];
+  const codeDir = path.join(wsRoot, '.codespace');
+  if (fs.existsSync(codeDir)) {
+    for (const name of fs.readdirSync(codeDir)) {
+      const appDir = path.join(codeDir, name);
+      if (fs.existsSync(path.join(appDir, '.git'))) {
+        apps.push({ name, status: installGitHook(appDir) });
+      }
+    }
+  }
+  return { root, apps };
+}
+
+module.exports = {
+  HOOK_MARKER,
+  HOOK_FILE,
+  BACKUP_SUFFIX,
+  PRE_COMMIT_SOURCE,
+  isCbbHookContent,
+  buildPreCommitSource,
+  resolveHooksDir,
+  installGitHook,
+  uninstallGitHook,
+  installGitHooksForWorkspace,
+};

package/cbb/lib/utils/gitignore.js

@@ -4,7 +4,8 @@
  * .gitignore 管理的纯函数工具（无副作用，便于单测；由 init.js 的 I/O 层调用）。
  *
  * 安装时：若 .gitignore 已含某目录（认可带/不带尾斜杠两种形式），则不重复添加；
- *         否则新增无尾斜杠形式（.claude / .qoder，更通用）。.cbb/ 维持带斜杠。
+ *         否则新增无尾斜杠形式（.claude / .qoder，更通用）。.cbb/ / .codespace/ /
+ *         .worktrees/ 这类纯目录路径维持带斜杠。
  * 卸载时：移除本包曾写入的所有形式（新旧版本均覆盖）。
  *
  * 注意：.gitignore 条目无 _managedBy 之类的标记，卸载按"形式匹配"移除，
@@ -13,11 +14,14 @@
 
 // 各目录：add = 写入形式；accept = 视为"已存在 / 需卸载移除"的可接受形式（含尾斜杠变体）。
 // .claude / .qoder 写无尾斜杠形式，但检测/卸载时同时认可带斜杠变体，避免重复添加、覆盖旧版本。
+// .worktrees/ 自 0.0.3-beta.22 起随 setup 写入（ADR 0002：本地模式下 main 工作区恒净，
+// 不再依赖 worktree-init 把该条目提交到 feature 分支——那会导致首个分支合并前 main 恒脏）。
 const GITIGNORE_RULES = [
   { add: '.claude', accept: ['.claude', '.claude/'] },
   { add: '.qoder', accept: ['.qoder', '.qoder/'] },
   { add: '.cbb/', accept: ['.cbb/'] },
   { add: '.codespace/', accept: ['.codespace/', '.codespace'] },
+  { add: '.worktrees/', accept: ['.worktrees/', '.worktrees'] },
   { add: '.opencode', accept: ['.opencode', '.opencode/'] },
   // .codebuddy：beta.15 及以前写入的旧目录，不再新增（add: null），但卸载/清理时仍移除其行
   { add: null, accept: ['.codebuddy', '.codebuddy/'] },

package/cbb/worktrees/_shared/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);