sillyspec 3.27.7 → 3.27.9

package/src/stages/plan.js

@@ -137,6 +137,12 @@ const stepGeneratePlan = {
 4. **写回任务清单**：把展开后的任务清单写回 tasks.md（checkbox 行 \`- [ ] task-XX: 一句话任务名\`，可附 \`[model:xxx]\`/\`(depends_on: task-01,02)\` 行内标注）。**写回规则（D-002@v1）**：保留 frontmatter/中文标题/所有非 task-XX 行（quick 挂载的 ql-xxx 勾选行、注记等逐行保留），仅重写 task-XX checkbox 行集合——防摧毁 quick 挂载条目
 5. 保存 plan.md（审查在下一步"审查计划"独立进行，不在本步自审——避免生成与自审同一次输出）；frontmatter 保留 plan_level 字段不删。**plan.md Wave 段下任务一律纯 ID 引用行**（\`- task-XX\`，不重抄任务名——任务名唯一真相在 tasks.md，重抄即双写漂移）
 
+> ⚠️ **Wave 段格式铁律（踩坑：旧先例 \`- [ ] task-XX: 描述\` 格式会导致 postcheck 告警）：**
+> ✅ 正确：\`- task-01\`（裸 ID 引用行，无 checkbox 无任务名）
+> ❌ 错误：\`- [ ] task-01: 添加用户创建接口\`（checkbox + 任务名——这是 tasks.md 格式，不是 plan.md Wave 段格式）
+> tasks.md 格式：\`- [ ] task-01: 一句话任务名\`（execute 从这里解析任务清单）
+> plan.md Wave 段格式：\`- task-01\`（纯 ID 引用，execute 据此分组）
+
 ---
 
 #### plan_level = none
@@ -446,6 +452,8 @@ related_tests:                           # 可选。当本 task 改动会导致
 - **task id 从 1 连续**：task-01、task-02、task-03… 不能跳号或重号（postcheck 校验 id 连续性，gap 会拦）
 这两条是跨 task 全局约束，子代理只写单卡看不到全局——你（主 agent）分派子代理前必须先在 plan.md 里确认 Wave 划分与编号正确。
 
+⚠️ **TaskCard 必备字段（缺一 postcheck 直接阻断）：** id、title（英文）、**title_zh（中文标题，必填）**、allowed_paths、goal、implementation、acceptance、verify、constraints。骨架已由 taskcard CLI 预生成（含 title_zh 占位），子代理只需 Edit 填值，不要删除任何必备字段。
+
 ## 任务清单
 ${taskList}
 

package/src/task-review.js

@@ -1107,11 +1107,18 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
     const reviewPath = join(reviewDir, 'review.json')
 
     // 幂等：review.json 已存在（无论合法/解析错/schema 错）一律跳过，绝不覆盖人工/子代理 verdict
+    // 双重守卫：readReview 判定 + existsSync 兜底（坑 task-review-draft-overwrite：已存在真实
+    // review 仍被草稿覆盖的变体——readReview 路径/权限异常时 existsSync 作为最后防线）
     const existing = readReview(reviewPath)
     if (existing.ok || existing.parseError || existing.schemaError) {
       skipped++
       continue
     }
+    if (existsSync(reviewPath)) {
+      // readReview 未捕获但文件存在（极端：权限/路径长度等）→ 宁跳不覆盖
+      skipped++
+      continue
+    }
 
     const content = readFileSync(join(tasksDir, tf), 'utf8')
     const allowedPaths = parseAllowedPaths(content)

package/src/worktree-apply.js

@@ -16,6 +16,7 @@ import { existsSync, unlinkSync, writeFileSync, mkdtempSync, rmSync, readdirSync
 import { join, resolve } from 'path';
 import { tmpdir } from 'os';
 import { WorktreeManager } from './worktree.js';
+import { getCrossWorktreeMeta, cleanupCrossWorktrees } from './worktree-cross.js';
 import { parseFileChangeList, parseFileChangeListDetailed, pathMatches } from './change-list.js';
 import { parseAllowedPaths, parseRepo } from './stages/plan-postcheck.js';
 import { git, gitQuiet } from './git-helper.js';
@@ -440,6 +441,182 @@ export async function withMainRepoLock(projectRoot, changeName, purpose, fn, opt
   }
 }
 
+/**
+ * 跨仓 worktree 真实 apply（坑 cross-repo-no-worktree-isolation，2026-08-27）。
+ *
+ * 对有 worktree meta 的跨仓仓（worktree-cross.js 创建）执行与主仓 A5 同构的 patch 回落：
+ *   deliverables（diff baselineCommit||baseHash + untracked，filterDeliverableFiles 排除基础设施）
+ *   → 清单校验（resolveApplyAllowSet 按 repo 切片 ∪ review 声明切片）
+ *   → 跨仓主工作副本 dirty 重叠拦截
+ *   → patch（tracked diff + untracked add/diff --cached/reset，Buffer 防二进制损坏）
+ *   → git apply --3way 回跨仓主工作副本；成功后 cleanup 该跨仓 worktree（分支保留作锚）。
+ *
+ * 与主仓 apply 的顺序契约：本函数在主仓 patch 动作**之前**调用——任一跨仓失败即整体报错返回，
+ * 主仓工作区不动（不留半套状态）。legacy 直写模式的跨仓仓无 meta，不走本函数（原 no-op 校验）。
+ *
+ * @param {string} changeName
+ * @param {string} projectRoot 主仓根
+ * @param {object} ctx MultiRepoContext
+ * @param {{ checkOnly?: boolean }} opts
+ * @returns {{ repos: string[], applied: Array<{repoKey, changedFiles}>, errors: string[], warnings: string[], crossCleanups: string[] }}
+ */
+function applyCrossRepoWorktrees(changeName, projectRoot, ctx, { checkOnly = false } = {}) {
+  const specBase = (ctx.platformOpts && ctx.platformOpts.specRoot) || join(projectRoot, '.sillyspec');
+  const out = { repos: [], applied: [], errors: [], warnings: [], crossCleanups: [] };
+  for (const [repoKey, entry] of ctx.repos) {
+    if (entry.isMain) continue;
+    const cm = getCrossWorktreeMeta(specBase, changeName, repoKey);
+    if (!cm || !cm.isCross || !cm.worktreePath || !existsSync(cm.worktreePath)) continue;
+    out.repos.push(repoKey);
+    const crossRoot = cm.crossRepoRoot || entry.projectRoot;
+    const deliverableBase = cm.baselineCommit || cm.baseHash;
+
+    // 交付集合（与主仓 step2 同口径：--name-status 捕 rename/delete + untracked，过滤基础设施文件）
+    let changedFiles = [];
+    const deletedFiles = [];
+    try {
+      const statusRaw = git(cm.worktreePath, ['diff', '--name-status', deliverableBase]);
+      const statusFiles = new Set();
+      if (statusRaw) {
+        for (const line of statusRaw.split('\n').filter(Boolean)) {
+          const parts = line.split('\t');
+          if (parts.length >= 2) statusFiles.add(parts[parts.length - 1]);
+          if (parts.length >= 3) statusFiles.add(parts[parts.length - 2]);
+          if (parts[0].startsWith('D')) deletedFiles.push(parts[parts.length - 1]);
+        }
+      }
+      const untrackedRaw = gitQuiet(cm.worktreePath, ['ls-files', '--others', '--exclude-standard']) || '';
+      changedFiles = filterDeliverableFiles([...new Set([...statusFiles, ...untrackedRaw.split('\n').filter(Boolean)])]);
+    } catch (e) {
+      out.errors.push(`跨仓 ${repoKey}：获取变更文件列表失败（${cm.worktreePath}）: ${e.message}`);
+      continue;
+    }
+
+    if (changedFiles.length === 0) {
+      if (!checkOnly) {
+        const cr = cleanupCrossWorktrees({ cwd: crossRoot, changeName, specBase, force: true });
+        for (const r of cr.results) {
+          if (r.result === 'cleaned') out.crossCleanups.push(`${repoKey}（无变更，worktree 已清理）`);
+          else out.warnings.push(`跨仓 ${repoKey} 无变更但清理 partial：${(r.details || []).join('; ')}`);
+        }
+      }
+      out.applied.push({ repoKey, changedFiles: [] });
+      continue;
+    }
+
+    // 清单校验（per-repo 切片 + review 声明切片并入，与主仓 Gate1/3b 同语义）
+    const allowMap = resolveApplyAllowSet(projectRoot, changeName);
+    let allowSet = allowMap.get(repoKey) || new Set();
+    const reviewDeclared = collectReviewDeclaredFiles(projectRoot, changeName).get(repoKey);
+    if (reviewDeclared) {
+      const merged = new Set([...allowSet]);
+      for (const f of reviewDeclared) {
+        if (![...merged].some(ap => pathMatches(f, ap))) merged.add(f);
+      }
+      allowSet = merged;
+    }
+    if (allowSet.size > 0) {
+      const violations = classifyAllowListViolations(changedFiles, allowSet);
+      if (violations.length > 0) {
+        out.errors.push(
+          `跨仓 ${repoKey}：文件清单校验失败——以下变更文件不在 design.md 清单、也不在该仓 task review.json changedFiles 声明中：\n  ${violations.join('\n  ')}`
+        );
+        if (!checkOnly) continue;
+      }
+    }
+
+    if (checkOnly) {
+      out.applied.push({ repoKey, changedFiles });
+      continue;
+    }
+
+    // 跨仓主工作副本 dirty 重叠拦截（与主仓 step4.5 同语义：重叠 = git apply 无法安全应用）
+    try {
+      const dirtyFiles = [...new Set(
+        ((gitQuiet(crossRoot, ['diff', '--name-only', 'HEAD']) || '').split('\n').filter(Boolean))
+          .concat((gitQuiet(crossRoot, ['ls-files', '--others', '--exclude-standard']) || '').split('\n').filter(Boolean))
+      )].filter(f => !f.startsWith('.sillyspec/') && f !== 'meta.json');
+      const overlap = dirtyFiles.filter(f => changedFiles.includes(f));
+      if (overlap.length > 0) {
+        out.errors.push(
+          `跨仓 ${repoKey}（${crossRoot}）主工作副本以下未提交文件与本次 apply 重叠，无法安全应用：\n  ${overlap.join('\n  ')}\n` +
+          `请先在跨仓仓提交或 stash 这些改动后重试 apply。`
+        );
+        continue;
+      }
+    } catch (e) {
+      out.errors.push(`跨仓 ${repoKey}：dirty 重叠检测失败（${crossRoot}）: ${e.message}`);
+      continue;
+    }
+
+    // patch 生成 + apply --3way（tracked/untracked 分流与 Buffer 聚合，与主仓 step7 同款）
+    const patchFiles = allowSet.size > 0
+      ? resolvePatchFiles(changedFiles, allowSet, true)
+      : changedFiles;
+    const tmpDir = mkdtempSync(join(tmpdir(), 'sillyspec-cross-'));
+    const patchPath = join(tmpDir, 'apply.patch');
+    try {
+      const inTree = new Set(
+        (gitQuiet(cm.worktreePath, ['ls-tree', '-r', '--name-only', deliverableBase]) || '').split('\n').filter(Boolean)
+      );
+      const inIndexRaw = patchFiles.length > 0
+        ? (gitQuiet(cm.worktreePath, ['ls-files', '--', ...patchFiles]) || '')
+        : '';
+      const inIndex = new Set(inIndexRaw.split('\n').filter(Boolean));
+      const trackedFiles = patchFiles.filter(f => inTree.has(f) || inIndex.has(f));
+      const untrackedPatchFiles = patchFiles.filter(f => !trackedFiles.includes(f));
+      const patchParts = [];
+      if (trackedFiles.length > 0) {
+        patchParts.push(git(cm.worktreePath, ['diff', '--binary', deliverableBase, '--', ...trackedFiles], { encoding: 'buffer', timeout: 60000 }));
+      }
+      if (untrackedPatchFiles.length > 0) {
+        git(cm.worktreePath, ['add', '--', ...untrackedPatchFiles]);
+        try {
+          patchParts.push(git(cm.worktreePath, ['diff', '--binary', '--cached', '--', ...untrackedPatchFiles], { encoding: 'buffer', timeout: 60000 }));
+        } finally {
+          gitQuiet(cm.worktreePath, ['reset', 'HEAD', '--', ...untrackedPatchFiles]);
+        }
+      }
+      const patchContent = Buffer.concat(patchParts);
+      if (patchContent.length === 0) {
+        out.applied.push({ repoKey, changedFiles: [] });
+        continue;
+      }
+      writeFileSync(patchPath, patchContent);
+      try {
+        git(crossRoot, ['apply', '--3way', patchPath], { timeout: 30000 });
+      } catch (e) {
+        // 冲突回滚：tracked 文件还原 HEAD 版，--3way 新建的部分文件删除（与主仓 rollbackApply 同语义）
+        const rawStderr = e.message || '';
+        for (const f of patchFiles) {
+          try {
+            if (gitQuiet(crossRoot, ['cat-file', '-e', `HEAD:${f}`]) !== null) {
+              gitQuiet(crossRoot, ['checkout', 'HEAD', '--', f]);
+            } else {
+              try { rmSync(join(crossRoot, f), { force: true }) } catch { /* 新文件删除失败留残，rescue 提示 */ }
+            }
+          } catch { /* 回滚尽力而为 */ }
+        }
+        out.errors.push(
+          `跨仓 ${repoKey}：apply --3way 失败（已回滚跨仓主工作副本到 apply 前状态）：${rawStderr}\n` +
+          `可选：进 ${crossRoot} 手工合并 worktree 分支 ${cm.branch}（git merge ${cm.branch}），完成后手动清理跨仓 worktree。`
+        );
+        continue;
+      }
+      out.applied.push({ repoKey, changedFiles: patchFiles });
+      // 成功 → 清理该跨仓 worktree（分支保留作 review 锚点）
+      const cr = cleanupCrossWorktrees({ cwd: crossRoot, changeName, specBase, force: true });
+      for (const r of cr.results) {
+        if (r.result === 'cleaned') out.crossCleanups.push(repoKey);
+        else out.warnings.push(`跨仓 ${repoKey} apply 成功但清理 partial：${(r.details || []).join('; ')}${(r.residual || []).length ? '；残留: ' + r.residual.join('; ') : ''}`);
+      }
+    } finally {
+      try { rmSync(tmpDir, { recursive: true, force: true }) } catch { /* 临时目录清理尽力而为 */ }
+    }
+  }
+  return out;
+}
+
 export function applyWorktree(changeName, { cwd, checkOnly = false, merge = false, base = 'merge-base', ctx = null, skipOverlap = false, stashDirty = false } = {}) {
   const projectRoot = cwd || process.cwd();
   const wm = new WorktreeManager({ cwd: projectRoot });
@@ -458,11 +635,26 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     skippedOverlapFiles: [],
   };
 
-  // --- 0. 跨仓 task no-op 校验（task-05 / D-009） ---
-  // 跨仓 task 的 commit 已落跨仓仓主干，apply = no-op（无 patch）。仅校验 review.head 是跨仓仓真实
-  // commit + 不 cleanup（wm.cleanup 只作用主仓 worktree）。校验失败 → 推 errors 阻断 apply（R-05）。
-  // 单仓 ctx 缺省 / 无跨仓 entry → validateCrossRepoNoOp 直接返回空（零回归）。
+  // --- 0. 跨仓处理（task-05 / D-009 + 坑 cross-repo-no-worktree-isolation） ---
+  // 0a. worktree 模式的跨仓仓：真实 apply（patch 回跨仓主工作副本 + 成功后 cleanup worktree）。
+  //     在主仓任何动作之前跑——任一跨仓失败即整体返回，主仓工作区不动（不留半套状态）。
+  // 0b. legacy 直写模式的跨仓仓：no-op 校验（review.head 是跨仓真实 commit + 不 cleanup）。
+  // 单仓 ctx 缺省 / 无跨仓 entry → 两步都空转（零回归）。
   if (ctx) {
+    const crossApplied = applyCrossRepoWorktrees(changeName, projectRoot, ctx, { checkOnly });
+    if (crossApplied.repos.length > 0) {
+      result.crossRepoApplied = crossApplied.applied;
+      for (const w of crossApplied.warnings) result.warnings = (result.warnings || []).concat([w]);
+      if (crossApplied.crossCleanups.length > 0) {
+        result.warnings = (result.warnings || []).concat([
+          `跨仓 worktree 已 apply 并清理：${crossApplied.crossCleanups.join(', ')}（分支保留作 review 锚点）`
+        ]);
+      }
+      if (crossApplied.errors.length > 0) {
+        result.errors.push(...crossApplied.errors);
+        return result; // 跨仓未落地 = 该仓 task 实际未完成，主仓 apply 不可继续
+      }
+    }
     const cross = validateCrossRepoNoOp(ctx, projectRoot, changeName);
     for (const e of cross.errors) result.errors.push(e);
     if (cross.warnings.length > 0) result.warnings = (result.warnings || []).concat(cross.warnings);

package/src/worktree-cross.js

@@ -0,0 +1,294 @@
+/**
+ * worktree-cross.js — 跨仓仓 worktree 隔离（坑 cross-repo-no-worktree-isolation，2026-08-27 用户实证）。
+ *
+ * 背景：跨仓 task 的原设计（multi-repo W1 D-005/D-006/D-009）是子代理直写跨仓仓主工作副本、
+ * commit 直落该仓主干，apply 对跨仓 no-op。实战暴露三类事故面：
+ *   1. 并行混流：跨仓主工作副本常有用户/其他变更的在途改动，子代理产物与之混在同一工作区，
+ *      无法区分归属、无法整体回滚（实证：sub-grid-security 主工作副本 task-05 产物与
+ *      .gitignore/.webpackrc.js/yarn.lock 并行改动混流，无法核对）；
+ *   2. 无 base 锚：跨仓仓无 meta/baseHash，base 只能靠 task 卡 base_commit 锡点；
+ *   3. 误伤面大：子代理在主工作副本可误改/误删用户未提交文件，无护栏。
+ *
+ * 本模块把跨仓仓纳入与主仓同构的 worktree 隔离（D-009 就地翻新，向后兼容）：
+ *   - worktree 落位 <主仓 specBase>/.runtime/worktrees/<change>--<repoKey>：主仓侧该目录已被
+ *     .gitignore 覆盖（主仓 create 已强制检查），不要求跨仓仓自配 .gitignore；git worktree
+ *     的注册信息在跨仓 .git/worktrees/，目录本身可在仓外任意路径；
+ *   - meta.json 与主仓同 schema + repoKey/crossRepoRoot/isCross 标识（唯一写入方 = 本模块，
+ *     multi-repo-context.js 只读且路径公式与此处 crossWorktreePath 保持同步）；
+ *   - base 锚 meta.baseHash（跨仓仓 HEAD 快照）；dirty baseline overlay 沿用主仓同款
+ *     （跨仓主工作副本的在途改动进 baseline，不算交付 diff，apply 不覆盖它们）；
+ *   - deps 供给 provisionDeps(worktree, 跨仓根, {specBase:null})——sniff worktree 自身项目
+ *     类型（package.json→nodejs 链主工作副本 node_modules；不沿用主仓 local.yaml 的
+ *     project.type，主仓与跨仓类型常不同，如实测 maven 主仓 + nodejs 前端仓）；
+ *   - cleanup：解链 node_modules junction → git worktree remove --force → 保留分支
+ *     sillyspec/<change> 作 review 锚点（对齐主仓 cleanup 的分支保护哲学）。
+ *
+ * 兼容：无跨仓 worktree meta 的旧变更（legacy 直写主干模式）各链路继续走原路径，零回归。
+ */
+
+import { existsSync, readFileSync, readdirSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { git, gitQuiet } from './git-helper.js';
+import { writeAtomicSync } from './fs-atomic.js';
+import { WorktreeManager, unlinkNodeModulesLinks, safeRemoveWorktreeDir } from './worktree.js';
+import { provisionDeps } from './worktree-deps.js';
+import { aggregateDeclaredRepos } from './run/shared.js';
+import { parseRepoRegistry } from './stages/plan-postcheck.js';
+
+const META_FILE = 'meta.json';
+const BRANCH_PREFIX = 'sillyspec/';
+
+/**
+ * 跨仓 worktree 路径（唯一路径公式；multi-repo-context.js 的 meta 只读逻辑与此同步）。
+ * @param {string} specBase 主仓 spec 根（<主仓>/.sillyspec）
+ * @param {string} changeName 变更名
+ * @param {string} repoKey 跨仓 repo 键（local.yaml repos: 段的 key）
+ */
+export function crossWorktreePath(specBase, changeName, repoKey) {
+  return join(specBase, '.runtime', 'worktrees', `${changeName}--${repoKey}`);
+}
+
+/**
+ * 读跨仓 worktree meta（不存在/损坏返 null = legacy 直写模式）。
+ * @returns {object|null}
+ */
+export function getCrossWorktreeMeta(specBase, changeName, repoKey) {
+  const metaPath = join(crossWorktreePath(specBase, changeName, repoKey), META_FILE);
+  if (!existsSync(metaPath)) return null;
+  try {
+    return JSON.parse(readFileSync(metaPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 列出某变更已建的全部跨仓 worktree meta（扫描 worktrees 目录下 `<change>--*` 且 isCross 的 meta）。
+ * @returns {Array<{repoKey: string, meta: object}>}
+ */
+export function listCrossWorktreeMetas(specBase, changeName) {
+  const base = join(specBase, '.runtime', 'worktrees');
+  if (!existsSync(base)) return [];
+  const out = [];
+  for (const name of readdirSync(base)) {
+    if (!name.startsWith(`${changeName}--`)) continue;
+    const metaPath = join(base, name, META_FILE);
+    if (!existsSync(metaPath)) continue;
+    try {
+      const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+      if (meta && meta.isCross && meta.repoKey) out.push({ repoKey: meta.repoKey, meta });
+    } catch { /* 损坏 meta 跳过（cleanup 阶段仍按目录处理） */ }
+  }
+  return out;
+}
+
+/**
+ * 聚合声明跨仓 key（plan.md 内联卡片 + tasks/ 独立卡片双源，与 shared.js getOrCreateMultiRepoContext 同口径）。
+ * @param {string} specBase
+ * @param {string} changeName
+ * @returns {string[]} 除 'main' 外的跨仓 key（未注册/配置错由 MultiRepoContext fail-closed，此处只聚合）
+ */
+function aggregateCrossRepoKeys(specBase, changeName) {
+  const planFile = join(specBase, 'changes', changeName, 'plan.md');
+  let planContent = '';
+  if (existsSync(planFile)) {
+    try { planContent = readFileSync(planFile, 'utf8') } catch { planContent = '' }
+  }
+  // tasks/ 独立卡片兜底（与 run/shared.js collectTaskCardReposFallback 同口径，该函数未导出）
+  const tasksDir = join(specBase, 'changes', changeName, 'tasks');
+  if (existsSync(tasksDir)) {
+    for (const f of readdirSync(tasksDir)) {
+      if (!/^task-\d+\.md$/i.test(f)) continue;
+      try { planContent += '\n' + readFileSync(join(tasksDir, f), 'utf8') + '\n' } catch { /* 兜底源不阻断 */ }
+    }
+  }
+  return aggregateDeclaredRepos(planContent).filter(k => k !== 'main');
+}
+
+/**
+ * 读主仓 local.yaml 的 repos: 段（路径口径与 run/shared.js readLocalYamlRaw 一致：cwd/.sillyspec/local.yaml）。
+ * @returns {Map<string,string>}
+ */
+function readRepoRegistry(cwd) {
+  const p = join(cwd, '.sillyspec', 'local.yaml');
+  let text = '';
+  if (existsSync(p)) {
+    try { text = readFileSync(p, 'utf8') } catch { text = '' }
+  }
+  return parseRepoRegistry(text);
+}
+
+/**
+ * execute 启动时为每个声明的跨仓仓建 worktree（幂等：meta 在即复用）。
+ *
+ * 失败语义 fail-closed（对齐主仓 create：隔离建不起来就不该开工）：任何仓创建失败 → 抛错，
+ * 由调用方（run/stage.js execute 启动）exit(1) 并给修复指引。已建成功的仓保留（重跑幂等复用）。
+ *
+ * @param {{ cwd: string, changeName: string, specBase?: string }} opts
+ * @returns {{ created: Array<{repoKey,worktreePath}>, reused: Array<{repoKey,worktreePath}>, skippedLegacy: string[] }}
+ * @throws {Error} 跨仓仓未注册 / git 不可达 / worktree add 失败 / 分支冲突
+ */
+export function ensureCrossWorktrees({ cwd, changeName, specBase }) {
+  const base = specBase || join(cwd, '.sillyspec');
+  const keys = aggregateCrossRepoKeys(base, changeName);
+  const registry = readRepoRegistry(cwd);
+  const created = [];
+  const reused = [];
+  const skippedLegacy = [];
+
+  for (const key of keys) {
+    const repoRoot = registry.get(key);
+    if (!repoRoot) {
+      // 与 MultiRepoContext 约束②同语义：声明的 repo 必须已注册，配置错不降级
+      throw new Error(
+        `跨仓 repo "${key}" 未在 local.yaml repos: 段注册。` +
+        `一键注册：sillyspec local register-repo ${key} <${key} 仓根路径>（勿手编 YAML），补注册后重跑 execute。`
+      );
+    }
+    const existing = getCrossWorktreeMeta(base, changeName, key);
+    if (existing && existing.worktreePath && existsSync(existing.worktreePath)) {
+      reused.push({ repoKey: key, worktreePath: existing.worktreePath });
+      continue;
+    }
+    // meta 在但目录没了（外部误删）：走重建（下方 git worktree add 会因注册残留失败，
+    // 先 prune 掉悬空注册再建——目录不在则 prune 无损）
+    if (existing) {
+      try { gitQuiet(repoRoot, ['worktree', 'prune'], { timeout: 30000 }) } catch {}
+    }
+
+    const worktreePath = crossWorktreePath(base, changeName, key);
+    const branch = BRANCH_PREFIX + changeName;
+
+    // base 快照：跨仓仓当前 HEAD（与主仓 create 的默认 base 语义一致）
+    let baseHash;
+    try {
+      baseHash = git(repoRoot, ['rev-parse', 'HEAD']);
+    } catch (e) {
+      throw new Error(`跨仓 repo "${key}"（${repoRoot}）git 不可达（rev-parse HEAD 失败：${e.message}）。请检查 local.yaml repos: 段路径。`);
+    }
+    const branchExists = !!gitQuiet(repoRoot, ['rev-parse', '--verify', `refs/heads/${branch}`]);
+    if (branchExists) {
+      throw new Error(
+        `跨仓仓 ${key} 已有分支 ${branch}（疑似上次 execute 残留）。三选一：\n` +
+        `  ① 确认残留作废：git -C ${repoRoot} branch -D ${branch} 后重跑；\n` +
+        `  ② 分支内容已 apply 落地或不再需要：sillyspec worktree cleanup ${changeName} --force（跨仓 worktree 一并清理后重跑）；\n` +
+        `  ③ 换变更名重跑。`
+      );
+    }
+    mkdirSync(join(base, '.runtime', 'worktrees'), { recursive: true });
+    try {
+      git(repoRoot, ['worktree', 'add', worktreePath, '-b', branch, baseHash], { timeout: 120000 });
+    } catch (e) {
+      throw new Error(`跨仓仓 ${key} worktree 创建失败（${worktreePath}）：${e.stderr || e.message}`);
+    }
+
+    const meta = {
+      name_zh: 'worktree 元数据',
+      changeName,
+      repoKey: key,
+      crossRepoRoot: repoRoot,
+      isCross: true,
+      branch,
+      baseBranch: gitQuiet(repoRoot, ['symbolic-ref', '--short', 'HEAD']) || 'HEAD',
+      baseHash,
+      actualBaseHash: gitQuiet(worktreePath, ['rev-parse', 'HEAD']) || baseHash,
+      createdAt: new Date().toISOString(),
+      worktreePath,
+      mode: 'worktree',
+    };
+    writeAtomicSync(join(worktreePath, META_FILE), JSON.stringify(meta, null, 2) + '\n');
+
+    // dirty baseline overlay：跨仓主工作副本在途改动 → worktree baseline（借主仓同款实现，
+    // 只用其参数化逻辑，不用实例路径状态）
+    try {
+      const wmHelper = new WorktreeManager({ cwd: repoRoot });
+      const baselineResult = wmHelper._overlayBaseline(repoRoot, worktreePath);
+      meta.baselineFiles = baselineResult.files;
+      meta.baselineHash = baselineResult.baselineHash;
+      if (baselineResult.files.length > 0) {
+        meta.baselineCommit = wmHelper._createBaselineCheckpoint(worktreePath, `${changeName}--${key}`, baselineResult.files);
+      }
+      if (baselineResult.errors && baselineResult.errors.length > 0) {
+        console.warn(`⚠️ 跨仓 ${key} baseline overlay 部分失败（${baselineResult.errors.join('; ')}）——在途改动未全量进 baseline，apply 前请人工核对跨仓主工作副本`);
+      }
+      writeAtomicSync(join(worktreePath, META_FILE), JSON.stringify(meta, null, 2) + '\n');
+    } catch (e) {
+      console.warn(`⚠️ 跨仓 ${key} baseline overlay 失败（${e.message}）——跨仓主工作副本如有在途改动，worktree 不含它们`);
+    }
+
+    // deps 供给：specBase 传 null —— sniff worktree 自身（主仓 local.yaml 的 project.type/install
+    // 描述的是主仓，跨仓仓类型常不同，如实测 maven 主仓 + nodejs 前端仓，沿用会把 mvn 命令
+    // 打到前端仓上）。失败不阻断（与主仓 create 同语义，doctor --fix 可修）
+    try {
+      const deps = provisionDeps(worktreePath, repoRoot, { specBase: null }) || {};
+      Object.assign(meta, {
+        depsStatus: deps.depsStatus,
+        depsMethod: deps.depsMethod || null,
+        depsSource: deps.depsSource || null,
+        depsLockHash: deps.depsLockHash || null,
+        depsCheckedAt: deps.depsCheckedAt || null,
+        ...(deps.depsError ? { depsError: deps.depsError } : {}),
+      });
+      writeAtomicSync(join(worktreePath, META_FILE), JSON.stringify(meta, null, 2) + '\n');
+    } catch (e) {
+      meta.depsStatus = 'failed';
+      meta.depsError = `provisionDeps crashed: ${e.message}`;
+      writeAtomicSync(join(worktreePath, META_FILE), JSON.stringify(meta, null, 2) + '\n');
+    }
+
+    created.push({ repoKey: key, worktreePath });
+  }
+  return { created, reused, skippedLegacy };
+}
+
+/**
+ * 清理某变更的全部跨仓 worktree（幂等）。
+ *
+ * 顺序对齐主仓 cleanup 的 Windows 防护：先解 node_modules junction（裸删会穿透删跨仓主工作
+ * 副本的 node_modules），再 git worktree remove --force，最后**保留分支** sillyspec/<change>
+ * 作 review 锚点（分支删除在主仓侧有 review 锚点 + 双保护，跨仓侧 v1 保守不删，残 branch
+ * 可人工清理）。目录残留（remove 失败）走 safeRemoveWorktreeDir 兜底 + residual 上报。
+ *
+ * @param {{ cwd: string, changeName: string, specBase?: string, force?: boolean }} opts
+ * @returns {{ results: Array<{repoKey, result: 'cleaned'|'skipped'|'partial', details: string[], residual: string[]}> }}
+ */
+export function cleanupCrossWorktrees({ cwd, changeName, specBase, force = false }) {
+  const base = specBase || join(cwd, '.sillyspec');
+  const results = [];
+  for (const { repoKey, meta } of listCrossWorktreeMetas(base, changeName)) {
+    const details = [];
+    const residual = [];
+    const repoRoot = meta.crossRepoRoot;
+    const wtPath = meta.worktreePath || crossWorktreePath(base, changeName, repoKey);
+    if (!existsSync(wtPath)) {
+      try { if (repoRoot) gitQuiet(repoRoot, ['worktree', 'prune'], { timeout: 30000 }) } catch {}
+      results.push({ repoKey, result: 'skipped', details: ['目录不存在（已清理）'], residual });
+      continue;
+    }
+    if (!force) {
+      // fail-closed：worktree 内还有未落地交付（相对 baseHash 有 diff）时拒绝清理（对齐主仓
+      // hasUnappliedChanges 哲学；跨仓侧以「分支上有交付 diff 且未 apply」近似）
+      try {
+        const diff = gitQuiet(wtPath, ['diff', '--name-only', meta.baseHash]) || '';
+        const untracked = gitQuiet(wtPath, ['ls-files', '--others', '--exclude-standard']) || '';
+        if (diff.trim() || untracked.trim()) {
+          results.push({ repoKey, result: 'partial', details: [`blocked: 跨仓 worktree 有未 apply 的交付改动（git diff ${String(meta.baseHash).slice(0, 8)} 非空）——先 apply 或显式 --force`], residual: [wtPath] });
+          continue;
+        }
+      } catch (e) {
+        details.push(`未落地检测失败（${e.message}），按 force 处理`);
+      }
+    }
+    try { unlinkNodeModulesLinks(wtPath, meta, details) } catch (e) { details.push(`junction 解链失败: ${e.message}`) }
+    try {
+      git(repoRoot, ['worktree', 'remove', '--force', wtPath], { timeout: 60000 });
+    } catch {
+      // remove 失败（脏文件/锁）：解链后安全删目录 + prune 注册
+      try { safeRemoveWorktreeDir(wtPath, meta) } catch (e) { residual.push(`目录残留 ${wtPath}: ${e.message}`) }
+      try { gitQuiet(repoRoot, ['worktree', 'prune'], { timeout: 30000 }) } catch { residual.push(`git worktree prune 失败（${repoRoot}）`) }
+    }
+    details.push(`分支 ${meta.branch} 保留作 review 锚点（确认无需回溯后可 git -C ${repoRoot} branch -D ${meta.branch}）`);
+    results.push({ repoKey, result: residual.length > 0 ? 'partial' : 'cleaned', details, residual });
+  }
+  return { results };
+}