sillyspec 3.28.8 → 3.28.10

package/src/worktree.js

@@ -12,10 +12,14 @@ import { execFileSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, readlinkSync, unlinkSync, copyFileSync } from 'fs';
 import { join, resolve, dirname, relative, isAbsolute, basename } from 'path';
 import { createHash } from 'crypto';
-import { provisionDeps, checkDepsFreshness, detectEditableInstallEscape } from './worktree-deps.js';
+import { provisionDeps, checkDepsFreshness, detectEditableInstallEscape, sweepForeignNodeModulesJunctions } from './worktree-deps.js';
+import { resolveRuntimeRoot } from './run/shared.js';
 import { writeAtomicSync } from './fs-atomic.js';
 import { openDatabase } from './db-engine.js';
-import { git, gitQuiet } from './git-helper.js';
+import { git, gitQuiet, unquoteGitPath } from './git-helper.js';
+// foreign-declared 零环独立模块（仅依赖 change-list/git-helper/stages/plan-postcheck，
+// 链上无回边）——contract-matrix/verify-probes/task-review 等处已有同款 import 先例
+import { splitOwnVsForeignDiffFiles } from './foreign-declared.js';
 
 // meta.json 会被 hook 进程与其它 CLI 进程并发读取（worktree-guard / getMeta / create 幽灵判定），
 // 必须原子写：半截 JSON 会让 getMeta 返回 null → 触发幽灵 worktree 强删（可能丢 gitignored 改动）。
@@ -43,6 +47,85 @@ function _chunkPathsPrivate(paths, maxChars = 8000) {
   return batches
 }
 
+// ── supplyFiles 生成物供给（坑③ / FR-03 / D-003@v1）──
+// .gitignore 生成物（如 src/build-id.ts）不在 git 树也不进 untracked overlay
+// （ls-files --others --exclude-standard 尊重 .gitignore），worktree 缺失致构建炸
+// Failed to load url——create step 5.9 按 local.yaml worktree.supplyFiles 从主仓复制供给。
+const SUPPLY_FILES_MAX = 200;     // R-04 展开上限帽：超出警告并截断（防 dist/** 类误配展开风暴）
+const SUPPLY_WALK_MAX_DEPTH = 6;  // glob 枚举递归深度帽（跳过 node_modules/.git 后的务实兜底）
+
+/**
+ * supplyFiles glob → 锚定全路径的 RegExp（自实现，零新依赖——D-003@v1）。
+ * 分隔符统一 /；正则元字符先转义，再还原通配语义：** → .*（跨层）、* → [^/]*（单层）。
+ * @param {string} pattern 相对仓根的 glob（如 src/build-*.ts、dist/** 、gen 目录多层 id.ts）
+ * @returns {RegExp} 锚定（^…$）的全路径匹配
+ */
+function supplyGlobToRegExp(pattern) {
+  const norm = String(pattern).replace(/\\/g, '/');
+  let re = '^';
+  for (let i = 0; i < norm.length; i++) {
+    const ch = norm[i];
+    if (ch === '*' && norm[i + 1] === '*') { re += '.*'; i++; }
+    else if (ch === '*') re += '[^/]*';
+    else re += ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(re + '$');
+}
+
+/**
+ * 读主仓 .sillyspec/local.yaml 的 worktree.supplyFiles（string[]）。
+ * 沿 hooks/worktree-guard.js parseSimpleYaml 同款轻量手写解析（本文件不引新 reader）：
+ * 只取这一个白名单键路径（worktree: 段 → supplyFiles: 子键 → 缩进块列表 / inline flow 数组），
+ * 其余段一概不碰（无原型污染面）。文件缺失/解析异常/形态不符 → []（供给步空转，fail-open）。
+ * @param {string} mainCwd 主仓根
+ * @returns {string[]} 供给清单（配置原文，未展开）
+ */
+function readSupplyFilesConfig(mainCwd) {
+  let content;
+  try {
+    content = readFileSync(join(mainCwd, '.sillyspec', 'local.yaml'), 'utf8');
+  } catch {
+    return [];
+  }
+  const items = [];
+  const stripQuotes = (v) => (
+    v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) ? v.slice(1, -1) : v
+  );
+  let inWorktree = false;
+  let inList = false;
+  for (const raw of content.split('\n')) {
+    const noComment = raw.replace(/\s+#.*$/, ''); // 尾注释剥离（与 worktree-guard 同口径）
+    const trimmed = noComment.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const indent = noComment.length - noComment.trimStart().length;
+    if (indent === 0) {
+      inWorktree = /^worktree:\s*$/.test(trimmed); // worktree-hook: 等其他段不误入
+      inList = false;
+      continue;
+    }
+    if (!inWorktree) continue;
+    if (indent === 2) {
+      const m = trimmed.match(/^supplyFiles:\s*(.*)$/);
+      if (!m) { inList = false; continue; }
+      inList = true;
+      const rest = m[1].trim();
+      if (rest.startsWith('[') && rest.endsWith(']')) {
+        // inline flow 数组（supplyFiles: [a, b]）——块列表之外的另一种常见写法，一并兼容
+        for (const part of rest.slice(1, -1).split(',')) {
+          const v = stripQuotes(part.trim());
+          if (v) items.push(v);
+        }
+      }
+      continue;
+    }
+    if (inList && trimmed.startsWith('- ')) {
+      const v = stripQuotes(trimmed.slice(2).trim());
+      if (v) items.push(v);
+    }
+  }
+  return items;
+}
+
 /**
  * 解除 worktree 内全部 node_modules junction/symlink（根 + meta.depsModules 各子模块）。
  *
@@ -478,6 +561,44 @@ export class WorktreeManager {
     return resolve(this.worktreeBase, changeName);
   }
 
+  /**
+   * ql-20260915-003 修复①（坑 junction-foreign-ownership，2026-09-15 用户实证：主仓
+   * frontend/node_modules 内 junction 指向历史 worktree 的 .pnpm——跨会话 node_modules
+   * 污染）：清扫主仓 node_modules（根 + local.yaml modules 子模块）内指向 worktrees 区的
+   * 外来 junction/symlink。正确链接方向只有 wt/node_modules → main；main 侧指向 worktrees
+   * 区的反向链接一律是 install 兜底/包管理器穿透写坏的污染，发现即清 + warn。
+   *
+   * 挂点：create 依赖供给前（5.7b，防新供给经污染链接写坏）与 cleanup（把本 worktree 可能
+   * 遗留的反向链接一并清）。清扫失败 fail-open 不阻断主流程（治理动作非卡点）。
+   *
+   * @param {string} label 调用场景（warn/details 文案用）
+   * @param {string[]|null} [details] 可选，cleanup details 兼容
+   * @returns {{ foreign: Array, removed: Array, failed: Array }} sweep 结果（异常时空集）
+   */
+  _sweepMainForeignJunctionLinks(label, details = null) {
+    try {
+      const mainRoot = this._resolveMainRepoRoot();
+      const sweep = sweepForeignNodeModulesJunctions(mainRoot, {
+        worktreesRoot: this.worktreeBase,
+        specBase: join(mainRoot, '.sillyspec'),
+      });
+      if (sweep.removed.length > 0) {
+        console.warn(`⚠️ 检测到主仓 node_modules 内指向历史 worktree 的外来 junction，已移除 ${sweep.removed.length} 个（坑 junction-foreign-ownership，${label}）`);
+        for (const r of sweep.removed) console.warn(`   ${r.link} → ${r.target}`);
+        if (details) details.push(`foreign junctions swept (${label}): ${sweep.removed.length}`);
+      }
+      if (sweep.failed.length > 0) {
+        console.warn(`⚠️ 主仓 node_modules 外来 junction 清理未全成（${sweep.failed.length} 个失败，可重跑 sillyspec worktree doctor 或手工 rmdir）: ${sweep.failed.map(f => f.link).join('、')}`);
+        if (details) details.push(`foreign junction sweep partial fail (${label}): ${sweep.failed.map(f => f.link).join('; ')}`);
+      }
+      return sweep;
+    } catch (e) {
+      // fail-open：清扫自身异常不阻断 create/cleanup 主流程
+      console.warn(`⚠️ 主仓 node_modules 外来 junction 清扫跳过（${e && e.message ? e.message : e}）`);
+      return { foreign: [], removed: [], failed: [] };
+    }
+  }
+
   /**
    * 读取 worktree 元数据
    * @param {string} changeName
@@ -683,7 +804,8 @@ export class WorktreeManager {
     printSyncReport(syncDiagnostic, baseHash, name);
 
     // 5.6 Dirty baseline overlay：将主工作区未提交变更同步到 worktree
-    const baselineResult = this._overlayBaseline(this.cwd, worktreePath);
+    // （传变更名启用并行会话声明隔离——他者在途文件不进本变更 baseline，D-001@v1）
+    const baselineResult = this._overlayBaseline(this.cwd, worktreePath, name);
     const baselineFiles = baselineResult.files;
     const baselineHash = baselineResult.baselineHash;
 
@@ -696,6 +818,10 @@ export class WorktreeManager {
 
     // 5.8 依赖供给（change 2026-06-28-worktree-deps-provision）
     // baseline overlay 后让 worktree 立即可构建/测试；失败不阻断 create，只记 meta。
+    // 5.7b ql-20260915-003 修复①（坑 junction-foreign-ownership）：依赖供给前清扫主仓
+    // node_modules 内指向历史 worktree 的外来 junction（反向链接污染，install 兜底穿透
+    // 写坏的源头）——发现即清 + warn，防新供给再经污染链接写坏主仓依赖。
+    this._sweepMainForeignJunctionLinks('worktree create');
     let deps = {};
     try {
       deps = provisionDeps(worktreePath, this.cwd, { specBase: join(this.cwd, '.sillyspec') }) || {};
@@ -703,6 +829,18 @@ export class WorktreeManager {
       deps = { depsStatus: 'failed', depsError: `provisionDeps crashed: ${e.message}` };
     }
 
+    // 5.9 生成物供给（坑③ / FR-03 / D-003@v1）：.gitignore 生成物不在 git 树也不进 untracked
+    // overlay（ls-files --exclude-standard 遵循 .gitignore），worktree 缺失致构建炸
+    // Failed to load url——按 local.yaml worktree.supplyFiles 从主仓复制供给，实供清单记
+    // meta.supplyFiles。未配置时供给步空转零行为变化；供给物天然不进 assess/apply 面。
+    let suppliedFiles = [];
+    try {
+      suppliedFiles = this._supplyGeneratedFiles(worktreePath);
+    } catch (e) {
+      // fail-open：供给步整体异常只警告，绝不阻断 create（R-04 约束）
+      console.warn(`⚠️ worktree supplyFiles 供给步异常（fail-open 不阻断 create）：${e.message}`);
+    }
+
     // 6. 写入 meta.json
     const meta = {
       name_zh: 'worktree 元数据',
@@ -724,6 +862,8 @@ export class WorktreeManager {
       depsLockHash: deps.depsLockHash || null,
       depsCheckedAt: deps.depsCheckedAt || null,
       ...(deps.depsError ? { depsError: deps.depsError } : {}),
+      // 5.9 实供清单（纯记录面，doctor/审计可读；空供给省略字段——存量 meta 缺省兼容）
+      ...(suppliedFiles.length > 0 ? { supplyFiles: suppliedFiles } : {}),
       ...(adoptedBranch ? { adoptedBranch: true } : {}),
     };
 
@@ -822,7 +962,7 @@ export class WorktreeManager {
       baseHash = git(this.cwd, ['rev-parse', 'HEAD']);
     }
 
-    const baselineResult = this._overlayBaseline(this.cwd, this.cwd);
+    const baselineResult = this._overlayBaseline(this.cwd, this.cwd, name);
     const baselineFiles = baselineResult.files;
     const baselineHash = baselineResult.baselineHash;
 
@@ -861,6 +1001,117 @@ export class WorktreeManager {
     return { branch: meta.branch, worktreePath, baseHash, mode: meta.mode };
   }
 
+  /**
+   * 生成物供给步（create step 5.9，坑③ / FR-03 / D-003@v1）。
+   *
+   * 读主仓 local.yaml 的 worktree.supplyFiles（string[]，精确路径 + glob * 单层 / ** 多层，
+   * 相对仓根），主仓侧展开枚举后逐文件复制进 worktree（mkdir 父目录 + copyFileSync）。
+   * 约束：
+   * - 未配置 / 零匹配：完全静默空转（零行为变化）；glob 零命中按缺失警告（不阻断）。
+   * - 展开上限帽 SUPPLY_FILES_MAX=200：超出警告并截断（R-04，防 dist/** 误配展开风暴）。
+   * - 单文件复制异常：warn 后继续，绝不阻断 create（fail-open，不回滚已复制文件）。
+   * - 目标已存在且内容不同：警告后覆盖（baseline overlay / 已检出版本可能已在场）。
+   * - 枚举跳过 node_modules/.git，递归深度帽 SUPPLY_WALK_MAX_DEPTH=6；匹配源只列文件
+   *   （statSync 跟随 junction/symlink，与供给语义一致）。
+   * - 供给物是 gitignore 物，天然不进 assess/apply 面（ls-files --exclude-standard），无需过滤。
+   *
+   * @private
+   * @param {string} worktreePath worktree 根目录（源恒为主仓 this.cwd）
+   * @returns {string[]} 实供清单（POSIX 相对路径，写入 meta.supplyFiles）
+   */
+  _supplyGeneratedFiles(worktreePath) {
+    const patterns = readSupplyFilesConfig(this.cwd);
+    if (!Array.isArray(patterns) || patterns.length === 0) return [];
+    const mainCwd = this.cwd;
+    const matches = []; // 展开命中（去重后，跨配置项合并）
+    const missing = []; // 精确路径缺失 / glob 零命中 / 越界形态
+    const seen = new Set();
+    for (const raw of patterns) {
+      if (typeof raw !== 'string' || !raw.trim()) continue;
+      const pattern = raw.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+      // 越界形态（绝对路径 / 盘符 / .. 段）不供给——供给面必须落在主仓根内
+      if (!pattern || pattern.startsWith('/') || /^[a-zA-Z]:/.test(pattern) || pattern.split('/').includes('..')) {
+        missing.push(pattern || JSON.stringify(raw));
+        continue;
+      }
+      if (!pattern.includes('*')) {
+        // 精确路径：直接查主仓存在性（只列文件）
+        let isFile = false;
+        try { isFile = statSync(join(mainCwd, pattern)).isFile(); } catch {}
+        if (isFile) {
+          if (!seen.has(pattern)) { seen.add(pattern); matches.push(pattern); }
+        } else {
+          missing.push(pattern);
+        }
+        continue;
+      }
+      // glob：静态前缀（首个含 * 段之前）作枚举根，正则锚定全路径匹配。
+      // 深度帽：** 限静态根下 SUPPLY_WALK_MAX_DEPTH 层；纯 * 模式路径段数固定，超段即停。
+      const segs = pattern.split('/');
+      let baseLen = 0;
+      while (baseLen < segs.length && !segs[baseLen].includes('*')) baseLen++;
+      const baseRel = segs.slice(0, baseLen).join('/');
+      const re = supplyGlobToRegExp(pattern);
+      const depthCap = pattern.includes('**') ? baseLen + SUPPLY_WALK_MAX_DEPTH : segs.length;
+      const found = [];
+      const walk = (absDir, relDir, segCount) => {
+        if (segCount >= depthCap) return;
+        let entries;
+        try { entries = readdirSync(absDir, { withFileTypes: true }); } catch { return; }
+        for (const e of entries) {
+          if (e.name === 'node_modules' || e.name === '.git') continue;
+          const rel = relDir ? `${relDir}/${e.name}` : e.name;
+          if (e.isDirectory()) {
+            walk(join(absDir, e.name), rel, segCount + 1);
+            continue;
+          }
+          let isFile = false;
+          try { isFile = statSync(join(absDir, e.name)).isFile(); } catch {}
+          if (isFile && re.test(rel)) found.push(rel);
+        }
+      };
+      walk(join(mainCwd, baseRel), baseRel, baseLen);
+      if (found.length === 0) {
+        missing.push(pattern); // glob 零命中同缺失口径（GWT-2）
+        continue;
+      }
+      for (const rel of found) {
+        if (!seen.has(rel)) { seen.add(rel); matches.push(rel); }
+      }
+    }
+    if (missing.length > 0) {
+      console.warn(`⚠️ worktree supplyFiles 主仓侧未命中 ${missing.length} 项（不阻断 create，按需核对清单）：${missing.join('、')}`);
+    }
+    // R-04 展开上限帽：排序保截断稳定可复现
+    matches.sort();
+    const capped = matches.slice(0, SUPPLY_FILES_MAX);
+    if (matches.length > SUPPLY_FILES_MAX) {
+      console.warn(`⚠️ worktree supplyFiles 展开命中 ${matches.length} 文件超上限 ${SUPPLY_FILES_MAX}，已截断只供给前 ${SUPPLY_FILES_MAX}（检查 glob 是否误配，如 dist/** 全量展开）`);
+    }
+    const supplied = [];
+    for (const rel of capped) {
+      const srcAbs = join(mainCwd, rel);
+      const dstAbs = join(worktreePath, rel);
+      try {
+        if (existsSync(dstAbs)) {
+          // 目标已存在且内容不同 → 警告后覆盖（内容比对失败不拦复制）
+          try {
+            if (!readFileSync(dstAbs).equals(readFileSync(srcAbs))) {
+              console.warn(`⚠️ worktree supplyFiles 覆盖 worktree 内已存在且内容不同的文件：${rel}`);
+            }
+          } catch {}
+        }
+        mkdirSync(dirname(dstAbs), { recursive: true });
+        copyFileSync(srcAbs, dstAbs);
+        supplied.push(rel);
+      } catch (e) {
+        // fail-open：单文件复制异常 warn 继续，不回滚已复制文件（R-04 约束）
+        console.warn(`⚠️ worktree supplyFiles 复制失败（跳过继续）：${rel} — ${e.message}`);
+      }
+    }
+    return supplied;
+  }
+
   /**
    * 构建 isolation 信息对象，用于写入 sillyspec.db（_writeIsolationToDB，isolation_status 列）
    * @param {string} changeName
@@ -1046,16 +1297,76 @@ export class WorktreeManager {
     }
   }
 
+  /**
+   * ql-20260915-003 修复②（坑 cleanup-meta-fallback，2026-09-15 用户实证：cleanup 报
+   * 「mode: null 跳过清理」但 worktree 目录实际创建过——meta 在 apply 后丢失 + cwd/specRoot
+   * 漂移让 getWorktreePath 解析到别处时，meta/worktreePath/metaDir 三缺被误判「什么都不
+   * 存在」早退）：meta 缺失时的 worktree 残留兜底探测。两路探针（异常一律 fail-open 视为
+   * 未命中）：
+   *   (a) `git worktree list --porcelain` 中分支 refs/heads/sillyspec/<name> 的注册路径——
+   *       git 注册是权威口径，不受本进程 worktreeBase 解析漂移影响；目录在不在都算命中
+   *       （注册残留本身就该 prune，目录在则连目录一起清）
+   *   (b) resolveRuntimeRoot 口径（cwd/.sillyspec 为 localSpecBase）下 worktrees/<name>
+   *       目录存在性——平台 runtimeRoot / cwd 漂移时的第二解析口径
+   * 全不命中 → hit:null + candidates（三路探针描述，供 CLI 诊断式跳过输出）。
+   * @param {string} name changeName（已过 validateChangeName）
+   * @returns {{ hit: { path: string, via: string }|null, candidates: string[] }}
+   */
+  _probeWorktreeRemnants(name) {
+    const stdPath = this.getWorktreePath(name);
+    const candidates = [`meta/目录探针（getWorktreePath 口径）: ${stdPath} 不存在`];
+    try {
+      const out = gitQuiet(this.cwd, ['worktree', 'list', '--porcelain'], { timeout: 30000 });
+      const wantBranch = `branch refs/heads/${BRANCH_PREFIX}${name}`;
+      let curPath = null;
+      let regHit = null;
+      for (const line of String(out || '').split('\n')) {
+        if (line.startsWith('worktree ')) curPath = line.slice('worktree '.length).trim();
+        else if (curPath && line.trim() === wantBranch) { regHit = curPath; break; }
+      }
+      if (regHit) {
+        candidates.push(`git 分支探针: 分支 ${BRANCH_PREFIX}${name} 注册于 ${regHit} —— 命中`);
+        return { hit: { path: regHit, via: `git worktree list 分支 ${BRANCH_PREFIX}${name} 注册路径` }, candidates };
+      }
+      candidates.push(`git 分支探针: git worktree list 无分支 ${BRANCH_PREFIX}${name} 注册`);
+    } catch {
+      candidates.push(`git 分支探针: git worktree list 失败（fail-open 视为未命中）`);
+    }
+    try {
+      const alt = join(resolveRuntimeRoot(null, join(this.cwd, '.sillyspec')), 'worktrees', name);
+      if (existsSync(alt)) {
+        candidates.push(`runtimeRoot 口径目录探针: ${alt} 存在 —— 命中`);
+        return { hit: { path: alt, via: `resolveRuntimeRoot 口径目录 ${alt}` }, candidates };
+      }
+      candidates.push(`runtimeRoot 口径目录探针: ${alt} 不存在`);
+    } catch {
+      candidates.push('runtimeRoot 口径目录探针: 解析失败（fail-open 视为未命中）');
+    }
+    return { hit: null, candidates };
+  }
+
   cleanup(changeName, { force = false, maxRetries = 3 } = {}) {
     const name = validateChangeName(changeName);
     const meta = this.getMeta(name);
-    const worktreePath = this.getWorktreePath(name);
+    let worktreePath = this.getWorktreePath(name);
     const metaDir = join(this.worktreeBase, name);
     const details = [];
 
-    // 幂等：什么都不存在 → 直接跳过
+    // 幂等：什么都不存在 → 直接跳过。
+    // ql-20260915-003 修复②（坑 cleanup-meta-fallback）：meta 缺失时不轻信「三缺 = 什么都不
+    // 存在」——先跑 _probeWorktreeRemnants 兜底（git 注册路径 + resolveRuntimeRoot 口径目录），
+    // 任一命中 → 不走早退，按命中路径继续清理（mode 推断 'worktree'，details 记兜底依据）；
+    // 全不命中才跳过，跳过结果带 probePaths 探针清单（CLI 诊断式输出 + doctor 指引）。
     if (!meta && !existsSync(worktreePath) && !existsSync(metaDir)) {
-      return { result: 'skipped', mode: null, details };
+      const probes = this._probeWorktreeRemnants(name);
+      if (probes.hit) {
+        worktreePath = probes.hit.path;
+        const note = `meta 缺失，目录/分支探测兜底（命中：${probes.hit.via}）`;
+        details.push(note);
+        console.warn(`⚠️ ${note}`);
+      } else {
+        return { result: 'skipped', mode: null, details, probePaths: probes.candidates };
+      }
     }
 
     const mode = meta?.mode || 'worktree';
@@ -1076,7 +1387,11 @@ export class WorktreeManager {
     if (!force) {
       const check = this.hasUnappliedChanges(name);
       if (check.hasChanges) {
-        console.error(`🚫 worktree cleanup 拒绝：${check.changedFiles.length} 个交付变更未落地主工作区 HEAD，清理会丢失代码。`);
+        // ql-20260915-003 修复② 配套：no-meta fail-closed 拦截时 changedFiles 为空，裸报
+        // 「0 个交付变更」让人误解——0 文件时改报无法判定的原因（保守保留语义不变）。
+        console.error(check.changedFiles.length > 0
+          ? `🚫 worktree cleanup 拒绝：${check.changedFiles.length} 个交付变更未落地主工作区 HEAD，清理会丢失代码。`
+          : `🚫 worktree cleanup 拒绝：无法判定交付是否已全部落地（${check.reason || 'meta 缺失，保守保留'}），保守不清理。`);
         for (const f of check.changedFiles) console.error(`   ${f}`);
         console.error('   请先落地（sillyspec worktree apply <name>）或 commit 到分支，或显式 --force 强制清理。');
         return { result: 'blocked', mode, details: [...details, 'blocked: uncommitted deliverable changes'], residual: [] };
@@ -1098,6 +1413,11 @@ export class WorktreeManager {
       unlinkNodeModulesLinks(worktreePath, meta, details)
     }
 
+    // ql-20260915-003 修复①（坑 junction-foreign-ownership）：cleanup 时同款清扫主仓
+    // node_modules——把本 worktree（及其他历史 worktree）可能遗留的反向链接一并清，
+    // 否则污染 junction 永久滞留主仓，直到下次人工 --force 重装依赖才发现。
+    this._sweepMainForeignJunctionLinks('worktree cleanup', details);
+
     // 1. git worktree remove（带 retry）—— in-place 跳过：无 git worktree 注册，且 worktreePath 即主工作区
     let gitRemoveOk = false;
     if (!isInPlace && existsSync(worktreePath)) {
@@ -1787,11 +2107,18 @@ export class WorktreeManager {
    * baseline，apply 回 main 即随本变更交付，需人工隔离。spec 文档不参与 worktree 内
    * 构建/测试（execute 的 spec 读写经 specDriftAnchor 锚回主仓），排除零功能损失；
    * 排除清单显式打印保持可见（哪些跨变更文件被隔离、去哪了）。
+   *
+   * 并行会话声明隔离（坑 execute-baseline-overlay-carries-broken-parallel-wip，D-001@v1）：
+   * changeName 非空时，他者**显式声明**（他 quick 会话 guard.allowedFiles / 他变更 design
+   * §6，own 优先）的在途文件三道剔除——staged/unstaged patch 道 :(exclude) pathspec 收窄
+   * （worktree 保持基线 HEAD 版本）、untracked 道不复制；隔离清单（文件←归属者）显式打印
+   * 一行。oracle 异常 fail-open 退回现状全量 overlay，绝不让 create 抛错。
    * @param {string} mainCwd - 主工作区路径
    * @param {string} worktreePath - worktree 路径
+   * @param {string} [changeName] - 本变更名；缺省/空串不切分（存量两参直调路径零回归）
    * @returns {Array<string>} overlay 的文件列表
    */
-  _overlayBaseline(mainCwd, worktreePath) {
+  _overlayBaseline(mainCwd, worktreePath, changeName = null) {
     const files = [];
     const errors = [];
     // git pathspec 排除（execFileSync 数组传参不经 shell，字面安全）：.sillyspec/ 整目录
@@ -1802,18 +2129,53 @@ export class WorktreeManager {
         if (norm === '.sillyspec' || norm.startsWith('.sillyspec/')) excluded.push(f)
       }
     }
+    // quotepath 归一：diff --name-only / ls-files 输出的非 ASCII 路径带双引号包裹，
+    // 与声明集比对、生成 pathspec 排除串前先按 unquoteGitPath 口径剥引号再反斜杠→正斜杠
+    const normalizeGitPath = (raw) => {
+      let p = raw;
+      if (p.length >= 2 && p.startsWith('"') && p.endsWith('"')) p = unquoteGitPath(p.slice(1, -1));
+      return p.replace(/\\/g, '/');
+    }
+    const isSpecPath = (n) => n === '.sillyspec' || n.startsWith('.sillyspec/');
+    // 他者声明文件的每道切分（staged/unstaged/untracked 各调一次，非逐文件）：
+    // 对该道全量输出的非 .sillyspec 集跑 own/foreign oracle，foreign → pathspec 排除串 +
+    // Map（路径→owners[]）+ 隔离明细；oracle 抛错 fail-open 退回该道全量（不阻断 create）
+    const foreignIsolated = []; // 「文件←归属者」明细（三道汇总，尾部去重打印）
+    const splitForeignLane = (rawAll) => {
+      const excludeSpecs = [];
+      const foreignSet = new Map();
+      if (!changeName) return { excludeSpecs, foreignSet };
+      try {
+        const candidates = rawAll.split('\n').filter(Boolean).map(normalizeGitPath).filter(n => !isSpecPath(n));
+        if (candidates.length === 0) return { excludeSpecs, foreignSet };
+        const { foreign } = splitOwnVsForeignDiffFiles(mainCwd, changeName, candidates);
+        for (const e of foreign) {
+          foreignSet.set(e.file, e.owners);
+          // 剥引号后的实际路径入 pathspec（git() 数组传参字面安全，与 :(exclude).sillyspec 同机制）
+          excludeSpecs.push(':(exclude)' + e.file);
+          foreignIsolated.push(`${e.file}←${e.owners.join(',')}`);
+        }
+      } catch (e) {
+        console.warn(`⚠️ baseline overlay 并行会话声明切分失败（${e.message}），本道退回全量 overlay`);
+      }
+      return { excludeSpecs, foreignSet };
+    }
 
     try {
       const excludedSpecFiles = [];
-      // staged 变更（pathspec 排除 .sillyspec/——跨变更 spec 文档不进 baseline）
-      const staged = gitQuiet(mainCwd, ['diff', '--cached', '--name-only', '--', '.', EXCLUDE_PATHSPEC], { timeout: 30000 }) || ''
+      // staged 变更（pathspec 排除 .sillyspec/——跨变更 spec 文档不进 baseline；
+      // 他者声明文件切分后一并排除，--name-only 与 --binary 两组 diff 命令同步收窄，
+      // files 清单只收 own——staged 输出即已剔除 foreign 的剩余部分）
       const stagedAll = gitQuiet(mainCwd, ['diff', '--cached', '--name-only'], { timeout: 30000 }) || ''
       collectExcluded(stagedAll, excludedSpecFiles)
+      const stagedForeign = splitForeignLane(stagedAll)
+      const stagedPathspec = ['--', '.', EXCLUDE_PATHSPEC, ...stagedForeign.excludeSpecs]
+      const staged = gitQuiet(mainCwd, ['diff', '--cached', '--name-only', ...stagedPathspec], { timeout: 30000 }) || ''
       if (staged) {
         try {
           // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏
           // QUAL-01 收口：git-helper 新增 encoding:'buffer' 支持（二进制输出专用，跳过 trim）
-          const patchBuf = git(mainCwd, ['diff', '--cached', '--binary', '--', '.', EXCLUDE_PATHSPEC], { encoding: 'buffer', timeout: 30000 });
+          const patchBuf = git(mainCwd, ['diff', '--cached', '--binary', ...stagedPathspec], { encoding: 'buffer', timeout: 30000 });
           if (patchBuf && patchBuf.length > 0) {
             const patchFile = join(worktreePath, '.sillyspec-baseline-staged.patch');
             try {
@@ -1831,14 +2193,16 @@ export class WorktreeManager {
         files.push(...staged.split('\n').filter(Boolean));
       }
 
-      // unstaged 变更（同上 pathspec 排除）
-      const unstaged = gitQuiet(mainCwd, ['diff', '--name-only', '--', '.', EXCLUDE_PATHSPEC], { timeout: 30000 }) || ''
+      // unstaged 变更（同上 pathspec 排除 + 他者声明剔除；--binary 不带 --cached）
       const unstagedAll = gitQuiet(mainCwd, ['diff', '--name-only'], { timeout: 30000 }) || ''
       collectExcluded(unstagedAll, excludedSpecFiles)
+      const unstagedForeign = splitForeignLane(unstagedAll)
+      const unstagedPathspec = ['--', '.', EXCLUDE_PATHSPEC, ...unstagedForeign.excludeSpecs]
+      const unstaged = gitQuiet(mainCwd, ['diff', '--name-only', ...unstagedPathspec], { timeout: 30000 }) || ''
       if (unstaged) {
         try {
           // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏（QUAL-01 收口，同上）
-          const patchBuf = git(mainCwd, ['diff', '--binary', '--', '.', EXCLUDE_PATHSPEC], { encoding: 'buffer', timeout: 30000 });
+          const patchBuf = git(mainCwd, ['diff', '--binary', ...unstagedPathspec], { encoding: 'buffer', timeout: 30000 });
           if (patchBuf && patchBuf.length > 0) {
             const patchFile = join(worktreePath, '.sillyspec-baseline-unstaged.patch');
             try {
@@ -1859,6 +2223,8 @@ export class WorktreeManager {
       const untracked = gitQuiet(mainCwd, ['ls-files', '--others', '--exclude-standard'], { timeout: 30000 }) || '';
       const skippedDirs = [];
       const skippedArtifacts = [];
+      // untracked 道 foreign 切分（一次全量非 .sillyspec 集，循环内仅 Map 查询）
+      const untrackedForeign = splitForeignLane(untracked)
       if (untracked) {
         for (const f of untracked.split('\n').filter(Boolean)) {
           const norm = f.replace(/\\/g, '/')
@@ -1867,6 +2233,9 @@ export class WorktreeManager {
           // baseline checkpoint——289MB tar.gz 入分支（FF 破坏 + 二进制永久入 git）的实际代价兜底
           const artifactWhy = isCheckpointSkippableArtifact(join(mainCwd, f));
           if (artifactWhy) { skippedArtifacts.push(`${f}（${artifactWhy}）`); continue }
+          // 他者会话声明的在途文件不复制（与 skipped-dir/artifact 同型跳过；明细已在切分时
+          // 计入隔离清单）——quotepath 引号路径先剥引号归一再比对
+          if (untrackedForeign.foreignSet.has(normalizeGitPath(f))) continue;
           const r = copyUntrackedEntry(join(mainCwd, f), join(worktreePath, f));
           if (r.status === 'copied') files.push(f);
           else if (r.status === 'skipped-dir') skippedDirs.push(f);
@@ -1887,6 +2256,13 @@ export class WorktreeManager {
         const preview = excludedUnique.slice(0, 8).join(', ') + (excludedUnique.length > 8 ? ` …（共 ${excludedUnique.length} 个）` : '')
         console.log(`🧹 baseline overlay 已隔离 ${excludedUnique.length} 个 .sillyspec/ 未提交文件（跨变更 spec 文档不进本变更 baseline，留在主仓各自归属）：${preview}`)
       }
+      // 并行会话声明隔离可见性：foreign 文件去重截断一行（对齐上方 .sillyspec/ 隔离打印
+      // 样式）——哪些在途文件被隔离、归属谁，create 时刻可查，不需事后考古
+      const foreignUnique = [...new Set(foreignIsolated)]
+      if (foreignUnique.length > 0) {
+        const preview = foreignUnique.slice(0, 8).join(', ') + (foreignUnique.length > 8 ? ` …（共 ${foreignUnique.length} 个）` : '')
+        console.log(`🧹 baseline overlay 已隔离 ${foreignUnique.length} 个并行会话声明的在途文件（worktree 取基线 HEAD 版本，不随本变更 apply）：${preview}`)
+      }
 
       if (files.length > 0) {
         console.log(`📁 baseline overlay: ${files.length} 个未提交文件已同步到 worktree`);

package/templates/agents-instruction.md

@@ -7,9 +7,9 @@
 1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
 2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md）或现有代码依据，无依据不改。
 3. **新功能 / 大改动走完整流程**：`brainstorm → plan → execute → verify → archive`。
-4. **小修复 / 小调整走 quick**：`sillyspec run quick`。
+4. **小修复 / 小调整走 quick**（= 无需要落盘的设计决策的改动，选道判据见第 6 条）：`sillyspec run quick`。
 5. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档。
-6. **判规模选档**：≤3 文件、范围明确走 `quick`；多阶段 / 架构级走完整流程。
+6. **判规模选档**：看本次改动有无需要落盘的设计决策——有（新能力 / 行为契约变更 / 跨模块取舍 / 多阶段推进）走完整流程，无（范围明确的局部修补）走 `quick`。文件数不是选道判据，只作出口绊线——改动大或跨模块时 quick 收尾门禁会自动加查（分级提示补文件注记 / 测试增量 / 模块文档认领）。
 7. **代码先行不补流程（倒推 B 模式）**：代码若已先写好，**不回头补 brainstorm/plan 装样子**——用 `quick --done` 收尾 + 补 quicklog 条目，把已落盘改动如实登记进进度库。
 8. **实证核验再 `--done`**：触及 `src`/`test` 的改动，CLI 会在 `quick --done` 时**亲自实测** `.sillyspec/local.yaml` 的 `commands.test` / `commands.lint`（门禁：实测失败阻断 --done 回 pending；纯 doc/配置与未配置命令自动跳过；倒推 B 模式按 --files 声明边界兜底判定）。agent 侧预跑**可选**——想省「--done 被拦→修复→重跑」一轮时才预跑；纯 doc/配置改动无需跑。以落盘文件与测试结果为准，不信口头"已完成"。
 9. **中途停下不靠额外命令存进度**——进度已由上一次 `--done` 自动落盘；恢复时用 `sillyspec progress show` 查看进度，再用 `sillyspec run <stage>` 续跑，不直接 commit 半成品。

package/templates/prompts/testcase-design.md

@@ -9,4 +9,5 @@
 3. **行为 vs 实现**：走公开 API 测行为；重构后功能不变，测试不应失败。
 4. **契约与回归**：覆盖本次改动会破坏的既有行为与相邻模块接口；改公共签名/文案/常量时同步修复受影响既有测试并跑全量，禁止删断言凑绿。
 5. **时间敏感分支**：超时/重试/并发分支别真等——超时参数做成可注入，测试传毫秒级极小值或注入可控时钟推进，再断言超时后的行为（走哪个分支/返回什么/资源是否回收）。
-6. **隔离确定性**：独立 fixture、可重复跑，不依赖共享状态/执行顺序。
+6. **隔离确定性**：独立 fixture、可重复跑，不依赖共享状态/执行顺序。
+7. **覆盖对账**：每条 TaskCard acceptance 至少对应一个测试用例，或显式标注 non-testable（文档/部署类——证据列写一句理由）；对应关系由 verify 探针 7 矩阵机械核对（判定 covered/partial 须给测试锚点）——写测试前先读卡的 acceptance 列表逐条对齐，勿只覆盖顺手的主路径。

package/templates/prompts/verify-probes.md

@@ -3,7 +3,7 @@
 > 🔧 **先跑 CLI 机械探针（一条命令）**：`sillyspec verify-probes --change <change-name> [--init]`
 > 输出已包含四个纯机械探针的结果（可直接进验证报告）：**探针 1** 未实现标记扫描（design 清单文件逐行 TODO/FIXME 命中 + 行号）、**探针 3** 测试文件递归查找（含 co-located tests/，逐 task 覆盖）、**探针 5** API 契约对账表（endpoints.json × 前端调用 diff）、**探针 6** 删除对账三态（git 事实 × design 声明）。`--init` 顺带生成 verify-result.md 九章节骨架（探针结果已预填，`<!--TODO-->` 占位替换即可）。
 >
-> 下列条目中，只有**半语义部分**需要你执行：探针 2（关键词提取）、探针 3.4 集成盲区标注、探针 3.5 断言有效性抽查、探针 4（决策追踪闭环判定）。CLI 已跑的部分勿重复手跑——对 CLI 输出的 warning 项做语义复核即可。
+> 下列条目中，只有**半语义部分**需要你执行：探针 2（关键词提取）、探针 3.4 集成盲区标注、探针 3.5 断言有效性抽查、探针 4（决策追踪闭环判定）、探针 7（验收×测试覆盖矩阵判定填槽）。CLI 已跑的部分勿重复手跑——对 CLI 输出的 warning 项做语义复核即可。
 
 **探针 2：设计关键词覆盖探针（你执行——关键词提取是语义）**
 1. 读取 design.md，从中提取所有能力关键词（如"登录"、"导出"、"批量"、"删除"、"搜索"等动作词）
@@ -31,3 +31,6 @@ CLI 的 missing backend endpoint 是 advisory（不硬阻断归档）——但 c
 
 **探针 6 补充（CLI 已出三态判定，你做终审）**
 以 git 事实为准（真实 > 声明）；CLI 的三态（合规/高风险/未声明）是机械判定，是否构成 FAIL blocker 由你诚实判定，务必如实记录——静默删除代码是 verify 的最大盲区。
+
+**探针 7 补充（CLI 已预填矩阵归属与提示，你填判定与证据）**
+验收×测试覆盖矩阵：CLI 机械半边已预填——逐 task 解析 TaskCard acceptance（frontmatter）、双源结构归属测试文件（allowed_paths 测试模式 ∪ execute review changedFiles 中 test/ 路径）、关键词命中提示（命中≠判定，仅提示）。你逐行填判定槽四枚举（covered / partial / uncovered / non-testable——non-testable 是文档/部署类显式逃生门）与证据：covered/partial 附测试锚点（`.test.` 文件或 file:line），non-testable 附一句理由；判定或证据未填 fail-closed，阻断 verify `--done`。与探针 3 口径差异：探针 3 查模块目录有没有测试文件（存在性面），探针 7 查每条 acceptance 由哪些测试承接（承接面）；两者并排冲突以 7 为准。