sillyspec 3.27.2 → 3.27.6

package/src/worktree.js

@@ -9,10 +9,10 @@
  */
 
 import { execFileSync } from 'child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, readlinkSync, unlinkSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, readlinkSync, unlinkSync, copyFileSync } from 'fs';
 import { join, resolve, dirname, relative, isAbsolute } from 'path';
 import { createHash } from 'crypto';
-import { provisionDeps, checkDepsFreshness } from './worktree-deps.js';
+import { provisionDeps, checkDepsFreshness, detectEditableInstallEscape } from './worktree-deps.js';
 import { writeAtomicSync } from './fs-atomic.js';
 import { git, gitQuiet } from './git-helper.js';
 
@@ -24,6 +24,65 @@ const WORKTREES_REL = '.sillyspec/.runtime/worktrees';
 const BRANCH_PREFIX = 'sillyspec/';
 const META_FILE = 'meta.json';
 
+/**
+ * 解除 worktree 内全部 node_modules junction/symlink（根 + meta.depsModules 各子模块）。
+ *
+ * 坑 ghost-dir-junction-pierce（2026-08-23 实证：worktree apply 后目录残留，人工 rm -rf 经
+ * junction 穿透删主仓 node_modules——user-inputs 两次事故实录；npm ci / git worktree remove
+ * 同样跟随 junction）。任何删除 worktree 目录的路径（cleanup / create 幽灵强删 / doctor 修复）
+ * 必须先解链；此前解链逻辑三处复制粘贴且**不覆盖 modules 子模块 junction**
+ * （meta.depsModules 记录的 wt/<module>/node_modules）。
+ *
+ * lstat/rmdir 失败 fail-loud（D-001@v1：静默跳过解链的后果是穿透删主仓，宁可阻断）。
+ *
+ * @param {string} worktreePath worktree 根目录
+ * @param {object} [meta] 可含 depsModules（[{path}] 子模块清单）；null 时只解根
+ * @param {string[]} [details] 可选，记录解链明细（cleanup details 兼容）
+ * @returns {number} 实际解除的链接数
+ */
+export function unlinkNodeModulesLinks(worktreePath, meta = null, details = null) {
+  let removed = 0;
+  const targets = [join(worktreePath, 'node_modules')];
+  for (const m of Array.isArray(meta && meta.depsModules) ? meta.depsModules : []) {
+    // 子模块 path 安全校验（与 worktree-deps isSafeModulePath 同口径）：拒绝绝对路径与 .. 段
+    if (m && typeof m.path === 'string' && m.path && !isAbsolute(m.path) && !m.path.split(/[\\/]+/).includes('..')) {
+      targets.push(join(worktreePath, m.path, 'node_modules'));
+    }
+  }
+  for (const nm of targets) {
+    if (!existsSync(nm)) continue;
+    let isLink;
+    try {
+      isLink = lstatSync(nm).isSymbolicLink();
+    } catch (e) {
+      throw new Error(`worktree node_modules junction 检测失败（疑似 EPERM：杀毒/索引锁 junction），阻断删除以保护主仓 node_modules：${e.message}。请关闭占用进程或手动 rmdir "${nm}" 后重试`);
+    }
+    if (!isLink) continue;
+    try {
+      if (process.platform === 'win32') {
+        // Windows rmdir 删 junction（reparse point）不跟随目标；execFileSync 数组形式不经 shell
+        execFileSync('cmd.exe', ['/c', 'rmdir', nm]);
+      } else {
+        unlinkSync(nm);
+      }
+      removed++;
+      if (details) details.push(`worktree node_modules junction/symlink removed: ${relative(worktreePath, nm) || '(root)'} (protect main checkout)`);
+    } catch (e) {
+      throw new Error(`worktree node_modules junction 解链失败，阻断删除以保护主仓 node_modules：${e.message}。请手动 rmdir "${nm}" 后重试`);
+    }
+  }
+  return removed;
+}
+
+/**
+ * 安全删除 worktree 目录：先解链全部 node_modules junction 再 rmSync。
+ * 幽灵目录清理（create 强删 / doctor ghost 修复）的统一出口——不再裸 rmSync。
+ */
+export function safeRemoveWorktreeDir(worktreePath, meta = null) {
+  unlinkNodeModulesLinks(worktreePath, meta);
+  rmSync(worktreePath, { recursive: true, force: true });
+}
+
 // 进程级缓存：cwd → 主仓库根目录。避免每次 new WorktreeManager 都 spawn 一次
 // `git rev-parse --git-common-dir`（Windows 上每次 spawn 约 30-100ms，execute 一次命令
 // 会 new 多个 WorktreeManager）。git-common-dir 在进程内对同一 cwd 稳定，缓存安全。
@@ -357,7 +416,7 @@ export class WorktreeManager {
    * @returns {{ branch: string, worktreePath: string, baseHash: string }}
    * @throws {Error} worktree 已存在、git 不可用、changeName 为空
    */
-  create(changeName, { base } = {}) {
+  create(changeName, { base, adoptBranch = false } = {}) {
     const name = validateChangeName(changeName);
     const worktreePath = this.getWorktreePath(name);
     const branch = BRANCH_PREFIX + name;
@@ -416,19 +475,35 @@ export class WorktreeManager {
           );
         }
         console.log(`⚠️  检测到幽灵 worktree 目录（无 meta.json，无未提交改动），自动清理...`);
-        try { rmSync(worktreePath, { recursive: true, force: true }); } catch {}
-        // 同步清理 git worktree 注册 + 残留分支，否则目录虽删但 git 内部状态未清，
-        // 后续 git worktree add 会因「worktree 已注册」或「分支已存在」失败
+        // 安全删除（坑 ghost-dir-junction-pierce）：git status 拦不住 junction（gitignored 的
+        // node_modules 不进 status，junction 目标内容更非「未提交改动」），裸 rmSync/人工 rm -rf
+        // 会穿透 junction 删主仓 node_modules——先解链再删。
+        try { safeRemoveWorktreeDir(worktreePath); } catch (unlinkErr) {
+          throw new Error(`幽灵 worktree 安全清理失败（已阻断，主仓 node_modules 未受影响）：${unlinkErr.message}`)
+        }
+        // 同步清理 git worktree 注册（git 内部状态），否则后续 worktree add 会因「已注册」失败。
+        // 不再盲删同名分支（坑 worktree-user-branch-conflict，2026-08-24 用户反馈五期①：该分支
+        // 可能是用户有意创建的，无凭据区分遗留 vs 自建——统一交由下方分支决策菜单处置）。
         try { gitQuiet(this.cwd, ['worktree', 'prune'], { timeout: 30000 }); } catch {}
-        try { gitQuiet(this.cwd, ['branch', '-D', branch]); } catch {}
       } else {
         throw new Error(`worktree already exists: ${name}. Run cleanup first.`);
       }
     }
 
-    // 2. 检查分支是否已存在
-    if (gitQuiet(this.cwd, ['rev-parse', '--verify', `refs/heads/${branch}`])) {
-      throw new Error(`branch already exists: ${branch}. Run cleanup first.`);
+    // 2. 检查分支是否已存在（坑 worktree-user-branch-conflict，2026-08-24 用户反馈五期①：
+    // 「用户要求在指定分支上做」时既有同名分支让 execute 直接死锁，旧报错只说 Run cleanup
+    // first、修复建议无条件推荐删分支——用户自建分支被引导误删。现给决策菜单；--adopt-branch
+    // 显式收编：检出该分支为 worktree 工作分支，分支现状作 baseline，仅后续新改动计入交付。）
+    const branchExists = !!gitQuiet(this.cwd, ['rev-parse', '--verify', `refs/heads/${branch}`]);
+    let adoptedBranch = false;
+    if (branchExists && !adoptBranch) {
+      throw new Error(
+        `分支已存在：${branch}（worktree create 需新建同名分支，直接冲突）。按实际情况三选一：\n` +
+        `  ① 本变更的遗留分支（上次 execute 残留、内容已落地或作废）：确认后 git branch -D ${branch} 再重跑；\n` +
+        `  ② 该分支是你有意让本变更在其上做的（用户指定分支）：sillyspec run execute --change ${name} --adopt-branch\n` +
+        `     —— 收编为 worktree 工作分支，分支既有内容计入 baseline（仅后续新改动算交付 diff）；\n` +
+        `  ③ 换变更名重跑。`
+      );
     }
 
     // 3. 解析 base 分支
@@ -457,7 +532,17 @@ export class WorktreeManager {
 
     // 5. 创建 worktree（含版本检测 + sandbox fallback）
     try {
-      git(this.cwd, ['worktree', 'add', worktreePath, '-b', branch, baseHash], { timeout: 120000 });
+      if (branchExists && adoptBranch) {
+        // --adopt-branch 收编（坑 worktree-user-branch-conflict）：检出既有分支为工作分支（不 -b），
+        // 分支当前 HEAD 作 baseHash——分支存量内容归 baseline，仅子代理新改动计入交付 diff
+        // （与 dirty baseline overlay 同哲学）。baseBranch 仍记主仓侧锚（sync 诊断用）。
+        git(this.cwd, ['worktree', 'add', worktreePath, branch], { timeout: 120000 });
+        baseHash = git(this.cwd, ['rev-parse', branch]);
+        adoptedBranch = true;
+        console.log(`📌 已收编既有分支 ${branch} 为 worktree 工作分支（--adopt-branch）：baseline = 分支 HEAD ${String(baseHash).slice(0, 8)}，分支既有内容不计交付 diff`);
+      } else {
+        git(this.cwd, ['worktree', 'add', worktreePath, '-b', branch, baseHash], { timeout: 120000 });
+      }
     } catch (e) {
       const check = isGitWorktreeSupported(this.cwd);
       if (!check.supported) {
@@ -518,8 +603,9 @@ export class WorktreeManager {
 
     // 5.7 创建 baseline checkpoint（有 dirty baseline 时才创建）
     let baselineCommit = null;
+    if (adoptedBranch) baselineCommit = baseHash; // adopt：分支 HEAD 恒作交付 diff 锚（无 dirty overlay 也要锚定）
     if (baselineFiles.length > 0) {
-      baselineCommit = this._createBaselineCheckpoint(worktreePath, name);
+      baselineCommit = this._createBaselineCheckpoint(worktreePath, name, baselineFiles);
     }
 
     // 5.8 依赖供给（change 2026-06-28-worktree-deps-provision）
@@ -552,12 +638,13 @@ export class WorktreeManager {
       depsLockHash: deps.depsLockHash || null,
       depsCheckedAt: deps.depsCheckedAt || null,
       ...(deps.depsError ? { depsError: deps.depsError } : {}),
+      ...(adoptedBranch ? { adoptedBranch: true } : {}),
     };
 
     const metaPath = join(worktreePath, META_FILE);
     writeMetaAtomic(metaPath, meta);
 
-    return { branch, worktreePath, baseHash, mode: meta.mode, syncDiagnostic };
+    return { branch, worktreePath, baseHash, mode: meta.mode, syncDiagnostic, ...(adoptedBranch ? { adoptedBranch: true } : {}) };
   }
 
   /**
@@ -655,7 +742,7 @@ export class WorktreeManager {
 
     let baselineCommit = null;
     if (baselineFiles.length > 0) {
-      baselineCommit = this._createBaselineCheckpoint(this.cwd, name);
+      baselineCommit = this._createBaselineCheckpoint(this.cwd, name, baselineFiles);
     }
 
     const meta = {
@@ -800,6 +887,69 @@ export class WorktreeManager {
     return refs;
   }
 
+  /**
+   * 清理前打捞 spec 流程产物（坑 worktree-spec-artifact-misplace，2026-08-24 用户实证）。
+   *
+   * 子代理 cwd=worktree 时会把流程产物（verify-result.md / module-impact.md / 任务卡 / 模块文档）
+   * 写进 worktree 内的 .sillyspec——而 apply 的 filterDeliverableFiles 把 .sillyspec/changes/ 排除在
+   * 交付外（spec 文档不进代码 patch），cleanup 删除 worktree 这些产物即蒸发、主仓流程看不到。
+   * 删除前扫 worktree 内两棵子树做最后打捞：
+   *   changes/<name>/** → 主仓缺失则 copy 回（verify-result.md 等核心场景）；同名不同内容仅列
+   *                      清单 warn 不覆盖（主仓版本可能是更新的，覆盖会倒退）
+   *   docs/**           → 主仓缺失则 copy 回（模块文档卡片；同名差异不提示——tracked checkout 副本常态）
+   * 只扫本变更子树（其它 change 的副本文件不越权搬运）。异常只 warn 不阻断清理。
+   * @private
+   */
+  _salvageSpecArtifacts(name, worktreePath, details) {
+    try {
+      const mainSpec = join(this._resolveMainRepoRoot(), '.sillyspec');
+      const wtSpec = join(worktreePath, '.sillyspec');
+      if (!existsSync(wtSpec)) return;
+      if (resolve(wtSpec) === resolve(mainSpec)) return; // in-place：同一目录，无需打捞
+      const salvaged = [];
+      const conflicts = [];
+      const salvageTree = (subDir, reportConflict) => {
+        const srcRoot = join(wtSpec, subDir);
+        if (!existsSync(srcRoot)) return;
+        const walk = (dir) => {
+          for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const src = join(dir, entry.name);
+            if (entry.isDirectory()) { walk(src); continue; }
+            if (!entry.isFile()) continue;
+            const rel = relative(wtSpec, src);
+            const dst = join(mainSpec, rel);
+            try {
+              if (!existsSync(dst)) {
+                mkdirSync(dirname(dst), { recursive: true });
+                copyFileSync(src, dst);
+                salvaged.push(rel);
+              } else if (reportConflict && readFileSync(src, 'utf8') !== readFileSync(dst, 'utf8')) {
+                conflicts.push(rel);
+              }
+            } catch { /* 单文件失败不拖垮整体打捞 */ }
+          }
+        };
+        walk(srcRoot);
+      };
+      salvageTree(join('changes', name), true);
+      salvageTree('docs', false);
+      if (salvaged.length > 0) {
+        console.warn(`⚠️ worktree 清理前打捞：${salvaged.length} 个 spec 流程产物只存在于 worktree 副本，已复制回主仓（apply 不搬运 .sillyspec/changes，不捞即随清理蒸发）：`);
+        for (const f of salvaged.slice(0, 20)) console.warn(`   ${join(mainSpec, f)}`);
+        if (salvaged.length > 20) console.warn(`   …等共 ${salvaged.length} 个`);
+        details.push(`salvaged ${salvaged.length} spec artifacts to main repo`);
+      }
+      if (conflicts.length > 0) {
+        console.warn(`⚠️ worktree 与主仓存在同名但内容不同的流程产物（不覆盖，请人工确认是否需要合并）：`);
+        for (const f of conflicts.slice(0, 20)) console.warn(`   ${join(mainSpec, f)}`);
+        if (conflicts.length > 20) console.warn(`   …等共 ${conflicts.length} 个`);
+        details.push(`conflicting spec artifacts: ${conflicts.length}`);
+      }
+    } catch (e) {
+      console.warn(`⚠️ spec 产物打捞跳过（不阻断清理）: ${e?.message || e}`);
+    }
+  }
+
   cleanup(changeName, { force = false, maxRetries = 3 } = {}) {
     const name = validateChangeName(changeName);
     const meta = this.getMeta(name);
@@ -839,34 +989,17 @@ export class WorktreeManager {
 
     const branch = (meta && meta.branch) || BRANCH_PREFIX + name;
 
-    // Windows 保护：先解链接 worktree/node_modules（junction 指向主 checkout），
-    // 否则后续 git worktree remove / rmSync recursive 会跟随 junction 误删主 node_modules 内容。
+    // 打捞 spec 流程产物（坑 worktree-spec-artifact-misplace，2026-08-24 用户实证）：必须在任何
+    // 删除动作之前。in-place（worktree 即主工作区）与 native-worktree（外部隔离环境）跳过。
+    if (!isInPlace && mode !== 'native-worktree' && existsSync(worktreePath)) {
+      this._salvageSpecArtifacts(name, worktreePath, details);
+    }
+
+    // Windows 保护：先解链接 worktree 内全部 node_modules junction（根 + modules 子模块，
+    // 坑 ghost-dir-junction-pierce：子模块 junction 此前不覆盖——npm ci / rm -rf / git worktree
+    // remove 跟随任一 junction 都会穿透删主仓对应 node_modules）。
     if (!isInPlace && existsSync(worktreePath)) {
-      const wtNodeModules = join(worktreePath, 'node_modules');
-      if (existsSync(wtNodeModules)) {
-        // lstat 失败 fail-loud（D-001@v1 / review-2026-08-09 #4）：EPERM（杀毒/索引锁 junction）若静默跳过解链，
-        // 后续 git worktree remove / rmSync recursive 会跟随 junction 误删主仓 node_modules
-        let isLink;
-        try {
-          isLink = lstatSync(wtNodeModules).isSymbolicLink();
-        } catch (e) {
-          throw new Error(`worktree node_modules junction 检测失败（疑似 EPERM：杀毒/索引占用），阻断 cleanup 保护主仓 node_modules：${e.message}。请关闭占用进程或手动 rmdir "${wtNodeModules}" 后重试 sillyspec worktree cleanup`);
-        }
-        if (isLink) {
-          try {
-            if (process.platform === 'win32') {
-              // Windows rmdir 删 junction（reparse point）不跟随目标，保护主 checkout
-              // execFileSync 数组形式：路径含引号/特殊字符时不会经 shell 解析（安全收敛，与 git-helper 同范式）
-              execFileSync('cmd.exe', ['/c', 'rmdir', wtNodeModules]);
-            } else {
-              unlinkSync(wtNodeModules);
-            }
-            details.push('worktree node_modules junction/symlink removed (protect main checkout)');
-          } catch (e) {
-            throw new Error(`worktree node_modules junction 解链失败，阻断 cleanup 保护主仓 node_modules：${e.message}。请手动 rmdir "${wtNodeModules}" 后重试`);
-          }
-        }
-      }
+      unlinkNodeModulesLinks(worktreePath, meta, details)
     }
 
     // 1. git worktree remove（带 retry）—— in-place 跳过：无 git worktree 注册，且 worktreePath 即主工作区
@@ -907,6 +1040,11 @@ export class WorktreeManager {
 
     // 4. 删除分支（fail-closed：task review 引用可达性校验。force 也不绕过——force 语义 =
     //    丢弃内容，不含丢弃审计链；确要删用 git branch -D 手动执行）
+    //    native-worktree 豁免（坑 worktree-user-branch-conflict，2026-08-24）：该模式 meta.branch
+    //    记的是用户自己的检出分支（非 sillyspec 所建），force 也不删——只清 sillyspec 侧注册。
+    if (mode === 'native-worktree') {
+      details.push(`branch kept: native-worktree 模式的 branch（${branch}）是用户自己的检出分支，不删除`);
+    } else
     //    升级（坑 cleanup-branch-review-anchor-tag，2026-08-21 实证）：分支被 review.json 引用
     //    时不再只能手动保留——打 `sillyspec-audit/<branch>` 轻量 tag 锚定分支 tip（ref 前缀独立
     //    于 sillyspec/* 分支族，doctor 孤儿分支扫描不误伤），commit 经 tag 保持可达（gc 安全），
@@ -1007,31 +1145,11 @@ export class WorktreeManager {
     try {
       const meta = this.getMeta(name) || {};
       const isInPlace = meta.mode === 'in-place-fallback';
-      // 先解 junction（非 in-place）：lstatSync 判 link → Windows rmdir junction / Unix unlinkSync
+      // 先解 junction（非 in-place）：统一走共享解链（坑 ghost-dir-junction-pierce：覆盖根 +
+      // depsModules 子模块；lstat/rmdir 失败 fail-loud，D-001@v1 / review-2026-08-09 #4——
+      // 静默跳过解链会让 install 经 junction 误改主仓 node_modules）
       if (!isInPlace && existsSync(wtPath)) {
-        const wtNodeModules = join(wtPath, 'node_modules');
-        if (existsSync(wtNodeModules)) {
-          // lstat 失败 fail-loud（D-001@v1）+ 解链失败 fail-loud（D-002@v1 / review-2026-08-09 #4）：
-          // 原 best-effort「交 provisionDeps install」会经 junction 误改主仓 node_modules，正是 #4 坑
-          let isLink;
-          try {
-            isLink = lstatSync(wtNodeModules).isSymbolicLink();
-          } catch (e) {
-            throw new Error(`worktree node_modules junction 检测失败（疑似 EPERM：杀毒/索引占用），阻断 doctor reprovision 保护主仓 node_modules：${e.message}。请关闭占用进程或手动 rmdir "${wtNodeModules}" 后重试`);
-          }
-          if (isLink) {
-            try {
-              if (process.platform === 'win32') {
-                // execFileSync 数组形式：不经 shell，防 meta.worktreePath 注入（安全收敛）
-                execFileSync('cmd.exe', ['/c', 'rmdir', wtNodeModules]);
-              } else {
-                unlinkSync(wtNodeModules);
-              }
-            } catch (e) {
-              throw new Error(`worktree node_modules junction 解链失败，阻断 doctor reprovision（不调 provisionDeps 避免经 junction 误改主仓）：${e.message}。请手动 rmdir "${wtNodeModules}" 后重试`);
-            }
-          }
-        }
+        unlinkNodeModulesLinks(wtPath, meta)
       }
       // 触发分流（坑 doctor-reprovision-junction-missing，2026-08-22 实证：junction 未建的
       // missing/failed 场景被 force install 强制重装——install 静默失败面大且慢；lockfile 一致时
@@ -1043,11 +1161,18 @@ export class WorktreeManager {
         force: !opts.relinkFirst,
       }) || {};
       const metaPath = join(this.getWorktreePath(name), META_FILE);
-      // 成功重供时清掉旧 depsError（provisionDeps 成功结果不含该键，{...meta,...deps} 会残留旧值）
+      // 错误保真（坑 doctor-reprovision-error-erased，2026-08-23 实证：provisionDeps 的子模块
+      // 后验证/mismatch 摘要追加 depsError 但不降级 depsStatus——原「depsStatus!=='failed' 即删
+      // depsError」把失败证据从 meta 抹掉，msg 也不含 → doctor 报 re-provisioned 成功而子模块
+      // 实际无链接无提示）。三改：①本次供给全量干净（无 depsError 且非 failed）才清旧值；
+      // ②msg 拼上 depsError；③failed/有错误 → ok:false 落 unfixable（原无条件 ok:true 把失败
+      // 也进 fixed 数组，CLI 打 ✅ 误导「已修好」）。
+      const hasDepError = deps.depsStatus === 'failed' || !!deps.depsError;
       const merged = { ...meta, ...deps };
-      if (deps.depsStatus !== 'failed') delete merged.depsError;
+      if (!hasDepError) delete merged.depsError;
       writeMetaAtomic(metaPath, merged);
-      return { ok: true, msg: `re-provisioned ${name}: depsStatus=${deps.depsStatus}` };
+      const msg = `re-provisioned ${name}: depsStatus=${deps.depsStatus}` + (deps.depsError ? `；⚠️ ${deps.depsError}` : '');
+      return hasDepError ? { ok: false, msg } : { ok: true, msg };
     } catch (e) {
       return { ok: false, msg: `re-provision failed for ${name}: ${e.message}` };
     }
@@ -1079,16 +1204,19 @@ export class WorktreeManager {
     // 数据源不一致——并行会话的活跃变更（meta 已清/in-place/平台模式 meta 在别处）分支会被全局
     // doctor --fix 误删。删分支前交叉核对：分支名 ∈ 活跃变更 → 保留（fixable:false 提示人工确认）。
     // 先探 DB 文件存在再实例化 ProgressManager（坑7 读路径建库：_ensureDB 不存在会建库污染）。
-    // null = 进度库存在但读失败（无法判定活跃态，保守不自动删）；空 Set = 无库/无活跃变更
-    // （git-only 工作流零回归，孤儿分支照删）。
+    // null = 无法核对（读失败 或 无进度库——坑 worktree-user-branch-conflict 2026-08-24 收紧：
+    // 无库时无法区分孤儿与用户自建分支，从「照删」改保守保留，git-only 便利让位于不误删）；
+    // Set = 进度库可读（空集=无活跃变更，非活跃孤儿仍可删）。
     let activeChanges = null;
+    let dbMissing = false;
     try {
       const specBaseOfWt = dirname(dirname(this.worktreeBase)); // <specBase>（.runtime/worktrees 上两级）
       if (existsSync(join(specBaseOfWt, '.runtime', 'sillyspec.db'))) {
         const { ProgressManager } = await import('./progress.js');
         activeChanges = new Set(new ProgressManager({ specDir: specBaseOfWt }).listChanges(this.cwd));
       } else {
-        activeChanges = new Set();
+        activeChanges = null;
+        dbMissing = true;
       }
     } catch (e) {
       console.warn(`⚠️ doctor 进度库读取失败，孤儿分支的活跃态交叉核对不可用（保守不自动删）: ${e.message}`);
@@ -1199,6 +1327,17 @@ export class WorktreeManager {
               (r.ok ? fixed : unfixable).push(r.msg);
             }
           }
+          // editable install 越界检查（坑 worktree-editable-install-escape，2026-08-25 实证
+          // gen:types 坑）：worktree venv 的 editable install 指向 worktree 外（主仓）时，
+          // gen:types/后端命令/pytest 静默加载旧代码零报错——此前靠模块文档人工记忆，内建检查化。
+          // fixable:false（重装决策留给用户：uv sync / pip install -e . 需按项目方式选）。
+          try {
+            const escapes = detectEditableInstallEscape(wtPath);
+            if (escapes.length > 0) {
+              issues.push({ type: 'editable-install-escape', name, fixable: false,
+                detail: `worktree venv 含 ${escapes.length} 个 editable install 指向 worktree 外（${escapes.slice(0, 5).map(e => `${e.pkg}→${e.target}`).join(', ')}${escapes.length > 5 ? ' 等' : ''}）——gen:types/后端命令会静默加载 worktree 外旧代码。修复：在 worktree 内重装（uv sync / uv pip install -e .）后重跑生成命令` });
+            }
+          } catch { /* 探测失败不阻断 doctor */ }
           }
         }
 
@@ -1217,10 +1356,21 @@ export class WorktreeManager {
           if (files.length === 0 || (files.length === 1 && files[0] === META_FILE)) {
             issues.push({ type: 'ghost-dir', name, detail: `空目录/幽灵目录: ${dirPath}`, fixable: true });
             if (fix) {
-              try { rmSync(dirPath, { recursive: true, force: true }); fixed.push(`removed ghost dir: ${name}`); } catch { unfixable.push(`remove failed for: ${name}`); }
+              // 安全删除（坑 ghost-dir-junction-pierce）：统一先解 node_modules junction 再删
+              try { safeRemoveWorktreeDir(dirPath); fixed.push(`removed ghost dir: ${name}`); } catch (e) { unfixable.push(`remove failed for: ${name} (${e.message.slice(0, 120)})`); }
             }
           } else {
-            issues.push({ type: 'ghost-dir-with-files', name, detail: `目录存在但无 meta.json: ${dirPath} (含 ${files.length} 文件)`, fixable: false });
+            // junction 侦测（坑 ghost-dir-junction-pierce）：无 meta 的含文件目录不自动删（内容
+            // 不明，fixable:false 交人工裁决），但必须警示穿透风险 + 给安全手动指引——人工
+            // rm -rf（Git Bash coreutils 跟随 junction）会删主仓 node_modules。
+            const junctionHits = [];
+            for (const cand of [join(dirPath, 'node_modules'), ...files.filter(f => !f.startsWith('.')).slice(0, 20).map(f => join(dirPath, f, 'node_modules'))]) {
+              try { if (lstatSync(cand).isSymbolicLink()) junctionHits.push(relative(dirPath, cand) || '(root)') } catch {}
+            }
+            const junctionNote = junctionHits.length > 0
+              ? ` ⚠️ 含 node_modules junction（${junctionHits.join(', ')}）——手动删除前必须先解链（cmd /c rmdir "<目录>\\<相对路径>"），直接 rm -rf 会穿透删除主仓 node_modules；解链后删除目录或跑 sillyspec worktree doctor --fix`
+              : '';
+            issues.push({ type: 'ghost-dir-with-files', name, detail: `目录存在但无 meta.json: ${dirPath} (含 ${files.length} 文件)${junctionNote}`, fixable: false });
           }
         }
 
@@ -1267,9 +1417,20 @@ export class WorktreeManager {
               continue;
             }
             if (activeChanges === null) {
-              // 进度库读失败：无法判定活跃态，保守不自动删（宁可漏删不可误删并行会话分支）
+              // 无法核对活跃态（读失败 或 无进度库）：保守不自动删（宁可漏删不可误删——
+              // 坑 worktree-user-branch-conflict：无库时该分支可能是用户自建的，无凭据区分）
+              const why = dbMissing ? '无进度库，无法区分孤儿与用户自建分支' : '进度库不可读，无法交叉核对活跃态'
+              issues.push({ type: 'orphan-branch', name, fixable: false,
+                detail: `分支疑似残留（无对应 meta，且${why}）: ${branch}——保守不自动删，人工确认后 git branch -D ${branch}` });
+              continue;
+            }
+            // review 锚点复核（坑 worktree-user-branch-conflict）：分支上有 task review base/head
+            // 引用的 commit → 审计链在用，不自动删（与 cleanup 的分支删除审计保护同口径）
+            let reviewRefs = [];
+            try { reviewRefs = this._branchReviewReferences(branch); } catch { reviewRefs = [] }
+            if (reviewRefs.length > 0) {
               issues.push({ type: 'orphan-branch', name, fixable: false,
-                detail: `分支疑似残留（无对应 meta，且进度库不可读无法交叉核对活跃态）: ${branch}——保守不自动删，人工确认后 git branch -D ${branch}` });
+                detail: `分支无对应 meta 但被 ${reviewRefs.length} 个 task review.json 的 base/head 引用（审计锚点）——保留。确要删除：先归档/迁移审计引用，或手动 git branch -D ${branch}` });
               continue;
             }
             issues.push({ type: 'orphan-branch', name, detail: `分支残留（无对应 meta，且非活跃变更）: ${branch}`, fixable: true });
@@ -1323,6 +1484,41 @@ export class WorktreeManager {
     }
 
     const isDeliverable = f => f && !f.startsWith('.sillyspec/') && f !== 'meta.json';
+    const isDeliverablePath = isDeliverable;
+
+    // 合并可达性短路（坑 cleanup-merged-branch-byte-false-positive，2026-08-23 实证：分支已
+    // merge 进主仓后主仓后续提交又改了同一批文件——下方逐字节判定必然不等 → 误报「未落地」
+    // 拦 cleanup 要 --force，用户只能 git branch --merged 自证。历史可达性才是「交付已进主仓」
+    // 的权威口径：分支 tip 是主仓 HEAD 的祖先 ⟺ diffBase..tip 的全部交付已在主仓历史里，后续
+    // 演进不改写这一事实）。四条件全真才短路，任一拿不准（ref 已删/漂移/git 失败）落回原逐字节
+    // 逻辑 fail-open，cherry-pick 落地（tip 非祖先）同样走原路径——零回归。
+    try {
+      const branch = meta.branch;
+      if (branch) {
+        const tip = gitQuiet(this.cwd, ['rev-parse', '--verify', branch]);
+        const wtHead = gitQuiet(worktreePath, ['rev-parse', 'HEAD']);
+        // 条件②③：worktree HEAD 就是分支 tip（无漂移/未删），且工作区无未 commit/未 track 的
+        // 交付改动（那些不在祖先可达性内，须走逐字节路径逐个核对）
+        if (tip && wtHead && tip === wtHead) {
+          const wtStatus = gitQuiet(worktreePath, ['status', '--porcelain'], { timeout: 30000 });
+          if (wtStatus !== null) {
+            const deliverableDirty = wtStatus.split('\n').filter(Boolean)
+              .map(l => l.slice(3).split(' -> ').pop())
+              .some(isDeliverablePath);
+            if (!deliverableDirty) {
+              // 条件④：merge-base(branch, HEAD) === tip ⟺ tip 是 HEAD 祖先（不用 --is-ancestor：
+              // gitQuiet 把 exit 1「非祖先」与真失败都归 null 无法区分；merge-base 恒 exit 0，
+              // 输出等于 tip 即祖先，ref 失败返回 null 自然落回原逻辑）
+              const mb = gitQuiet(this.cwd, ['merge-base', branch, 'HEAD']);
+              if (mb === tip) {
+                return { hasChanges: false, changedFiles: [], reason: `branch fully merged into main HEAD (tip ${tip.slice(0, 8)} is ancestor; post-merge main edits are later history)` };
+              }
+            }
+          }
+        }
+      }
+    } catch { /* 可达性判定异常 → 落回原逐字节逻辑（fail-open） */ }
+
     try {
       // 1) 候选交付变更（worktree 工作区相对 diffBase）。--no-renames：rename 退化成 D+A，两侧文件都进集
       const trackedRaw = gitQuiet(worktreePath, ['diff', '--no-renames', '--name-only', diffBase], { timeout: 30000 });
@@ -1605,9 +1801,13 @@ export class WorktreeManager {
    * 用于区分 "前置 dirty baseline" 和 "子代理新增改动"
    * @param {string} worktreePath
    * @param {string} changeName
+   * @param {string[]} [baselineFiles] 主仓并行在途文件清单（_overlayBaseline 返回的 files，
+   *   已排除 .sillyspec）——写入提交信息正文（坑 baseline-checkpoint-opaque-carriage，
+   *   2026-08-24 用户反馈三期③：checkpoint 把主仓并行脏文件带进分支 diff，逐任务归因要靠
+   *   人肉区分；清单入 message 后 `git log` 一眼可辨、可机械排除）
    * @returns {string} commit hash
    */
-  _createBaselineCheckpoint(worktreePath, changeName) {
+  _createBaselineCheckpoint(worktreePath, changeName, baselineFiles = []) {
     // 使用临时 git identity，避免用户未配置 user.name/user.email 导致失败
     const env = {
       GIT_AUTHOR_NAME: 'sillyspec',
@@ -1622,13 +1822,21 @@ export class WorktreeManager {
       if (!status) {
         return gitQuiet(worktreePath, ['rev-parse', 'HEAD']);
       }
+      // 提交信息正文列夹带文件（封顶 30 行，超出记总数）——清单与 meta.baselineFiles 同源
+      const CAP = 30
+      const files = Array.isArray(baselineFiles) ? baselineFiles.filter(Boolean) : []
+      const body = files.length > 0
+        ? ['\n主仓并行在途文件（非本变更改动，逐任务归因时排除）：',
+           ...files.slice(0, CAP).map(f => `- ${f}`),
+           ...(files.length > CAP ? [`…等共 ${files.length} 个`] : [])].join('\n')
+        : ''
       // --no-verify：baseline 是锚点不是交付物，只是把主仓库 dirty 文件快照到 worktree
       // 分支上以便区分「前置 baseline」与「子代理新增改动」。它不该触发项目 pre-commit
       // hook（如 ruff format），否则主仓库 dirty 文件中任一不达标的会被 hook reformat
       // 致 commit 失败 → worktree 创建失败 → execute 无法启动。
       execFileSync(
         'git',
-        ['commit', '--no-verify', '-m', `sillyspec: baseline checkpoint for ${changeName}`],
+        ['commit', '--no-verify', '-m', `sillyspec: baseline checkpoint for ${changeName}${body}`],
         { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe','pipe','pipe'], env }
       );
       const hash = git(worktreePath, ['rev-parse', 'HEAD']);

package/templates/prompts/taskcard-rules.md

@@ -22,7 +22,8 @@ TaskCard 格式规则（必须严格遵守）：
 - 如果存在 decisions.md，无法覆盖的 D-xxx@vN 在 constraints 中标注
 - **保存前格式自检**（plan-postcheck 会硬校验，不通过到 Step 4 会批量报错，先在这里逐条自查）：
   - **硬校验字段**（缺失 plan-postcheck 直接报错阻断，必须齐全）：id、title、title_zh、allowed_paths、goal、implementation、acceptance、verify、constraints
+  - **占位符硬拦**（未替换视同缺字段，plan --done 直接报错阻断）：FR-XX（requirement_ids）、D-XXX（decision_ids）、src/example/file.ts（allowed_paths）、一句话说明这个 task（goal）、具体步骤 1（implementation）、可验证的验收条件 1（acceptance）、边界约束 1（constraints）——骨架带出来的占位值必须逐个替换成真实内容
   - **规范约定字段**（应填但不硬校验，缺失不阻断完成、只影响规范性）：author、created_at、priority、depends_on、blocks
   - allowed_paths 非空（至少一个真实源文件路径；回归类 task 无源码改动时填被验证的关键入口文件）
   - acceptance 与 verify 都在 frontmatter 内（漏写会被 plan-postcheck 报「缺少验收标准」/「缺少验证步骤」）
-- **生成方式**：用 `sillyspec taskcard <change-name> --task task-NN [--all]` 生成安全骨架（LF 行尾 + frontmatter 必闭合 + 九个硬校验字段齐全 + author/created_at 自动填），再往骨架里填语义内容——**勿用 Write tool 整文件手写**（CRLF / 漏闭合 `---` / 漏字段的根源，postcheck 报错大多由此来）；已存在的卡命令会跳过不覆盖，局部修改用 Edit 定点改
+- **生成方式**：由主 agent 一次性 `sillyspec taskcard <change-name> --all` 预生成全部安全骨架（LF 行尾 + frontmatter 必闭合 + 九个硬校验字段齐全 + author/created_at 自动填；幂等，已存在跳过）。**子代理不要并行跑 taskcard CLI**（2026-08-25 实证撞进度库 SQLite 锁），只往骨架里填语义内容（LF 行尾 + frontmatter 必闭合 + 九个硬校验字段齐全 + author/created_at 自动填），再往骨架里填语义内容——**勿用 Write tool 整文件手写**（CRLF / 漏闭合 `---` / 漏字段的根源，postcheck 报错大多由此来）；已存在的卡命令会跳过不覆盖，局部修改用 Edit 定点改