sillyspec 3.27.1 → 3.27.5

package/src/worktree.js

@@ -9,7 +9,7 @@
  */
 
 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';
@@ -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 稳定，缓存安全。
@@ -416,7 +475,12 @@ export class WorktreeManager {
           );
         }
         console.log(`⚠️  检测到幽灵 worktree 目录（无 meta.json，无未提交改动），自动清理...`);
-        try { rmSync(worktreePath, { recursive: true, force: true }); } catch {}
+        // 安全删除（坑 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 内部状态未清，
         // 后续 git worktree add 会因「worktree 已注册」或「分支已存在」失败
         try { gitQuiet(this.cwd, ['worktree', 'prune'], { timeout: 30000 }); } catch {}
@@ -800,6 +864,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 +966,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 即主工作区
@@ -1007,31 +1117,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 +1133,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}` };
     }
@@ -1217,10 +1314,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 });
           }
         }
 
@@ -1323,6 +1431,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 });

package/templates/prompts/taskcard-rules.md

@@ -22,6 +22,7 @@ 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 报「缺少验收标准」/「缺少验证步骤」）