sillyspec 3.32.3 → 3.32.5

package/src/worktree-apply.js

@@ -1046,6 +1046,43 @@ export async function withMainRepoLock(projectRoot, changeName, purpose, fn, opt
   }
 }
 
+/**
+ * 跨仓主副本直写检测（FR-06，D-003@v1——坑 cross-wt-toolchain-split 2026-10-10 用户实证：
+ * agent 绕开 worktree 回主副本直写 master，5 个 fire commit 落主干、空 worktree 被静默清理，
+ * 全程零提示）。
+ *
+ * 判定：主副本 base 锚（meta.baselineCommit||baseHash，与 worktree 交付 diff 同锚）之后有
+ * commit 推进，且推进触及的文件与本变更该仓声明文件面（resolveApplyAllowSet 切片）以
+ * pathMatches 容差相交 → 返回 { commits, files }（交集文件，声明面命中口径与清单校验一致）。
+ * 纯检测不写盘：advisory，调用方（applyCrossRepoWorktrees）负责出 warning。
+ *
+ * fail-open（FR-07）：git 不可达 / baseHash 缺失 / allowSet 空 / 任何异常 → null（调用方静默
+ * 跳过——并行会话无关推进是合法态，误报成本高于漏报面已由 D-003 故障面接受）。
+ *
+ * @param {string} crossRoot 跨仓主副本仓根
+ * @param {string} baseHash base 锚（worktree meta 的 baselineCommit||baseHash）
+ * @param {Set<string>} allowSet 该仓声明文件面（相对跨仓仓根；空 = 声明面缺失不检测）
+ * @returns {{ commits: number, files: string[] }|null} null = 无推进/无交集/检测不可得
+ */
+export function detectCrossMainCopyBypass(crossRoot, baseHash, allowSet) {
+  try {
+    if (!crossRoot || !baseHash || !(allowSet instanceof Set) || allowSet.size === 0) return null;
+    const countRaw = gitQuiet(crossRoot, ['rev-list', '--count', `${baseHash}..HEAD`]);
+    if (countRaw === null) return null; // git 失败（非仓/锚悬空）→ fail-open
+    const commits = Number(String(countRaw).trim());
+    if (!Number.isFinite(commits) || commits <= 0) return null; // 无推进 → 合法态
+    const raw = gitQuiet(crossRoot, ['diff', '--name-only', baseHash, 'HEAD']);
+    if (raw === null) return null;
+    const touched = raw.split('\n').map(s => s.trim()).filter(Boolean);
+    if (touched.length === 0) return null;
+    const files = touched.filter(f => [...allowSet].some(ap => pathMatches(f, ap)));
+    if (files.length === 0) return null; // 推进但与声明面无交集 → 并行会话，不告警
+    return { commits, files };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * 跨仓 worktree 真实 apply（坑 cross-repo-no-worktree-isolation，2026-08-27）。
  *
@@ -1104,6 +1141,31 @@ function applyCrossRepoWorktrees(changeName, projectRoot, ctx, { checkOnly = fal
       continue;
     }
 
+    // 声明面解析（提前到空清理分支前——直写检测需要 allowSet 覆盖「空 worktree 被静默清理」
+    // 的 D-007 签名场景；清单校验段复用同一份，零行为差）。
+    // specBase 显式传（平台模式 changes/ 在 specRoot；本地模式与旧硬编码同值零回归）。
+    // review 声明收紧（D-003@v1，2026-09-14-change-ownership-guards task-03）：声明文件须与
+    // allow 面（design 清单 ∪ 各 task target_files/allowed_paths ∪ linked-change 声明 =
+    // resolveApplyAllowSet 现有并集）相交（pathMatches 容差）才计入；不相交的外来声明剔除出
+    // 放行面、进 violations 报告行（「review 声明了越权文件」嫌疑标注），admission 增量归零。
+    const allowMap = resolveApplyAllowSet(projectRoot, changeName, { specBase });
+    const allowSet = allowMap.get(repoKey) || new Set();
+    const reviewDeclared = collectReviewDeclaredFiles(projectRoot, changeName, { runtimeRoot: join(specBase, '.runtime') }).get(repoKey);
+
+    // 跨仓主副本直写检测（FR-06，D-003@v1 advisory——坑 cross-wt-toolchain-split 2026-10-10
+    // 实证：agent 绕开 worktree 回主副本直写 master，空 worktree 在此被静默清理零提示）：
+    // 主副本 base 锚之后有提交推进且推进文件与声明面相交 = 本变更签名，warning 列证。
+    // 交集空/无推进/声明面缺失不告警（并行会话无关推进合法）；检测异常 fail-open（FR-07）。
+    try {
+      const bypass = detectCrossMainCopyBypass(crossRoot, deliverableBase, allowSet);
+      if (bypass) {
+        out.warnings.push(
+          `跨仓 ${repoKey}：疑似绕过 worktree 直写主干——base ${String(deliverableBase).slice(0, 8)} 之后主副本有 ${bypass.commits} 个 commit，以下文件与本变更声明面相交：\n  ${bypass.files.join('\n  ')}\n` +
+          `（worktree 隔离被绕开：请核对该仓执行期决策留痕；若属误写应把提交摘到分支重走 apply。advisory 警告不阻断 apply。）`
+        );
+      }
+    } catch { /* 直写检测 fail-open，不阻断 apply */ }
+
     if (changedFiles.length === 0) {
       if (!checkOnly) {
         const cr = cleanupCrossWorktrees({ cwd: crossRoot, changeName, specBase, force: true });
@@ -1117,14 +1179,6 @@ function applyCrossRepoWorktrees(changeName, projectRoot, ctx, { checkOnly = fal
     }
 
     // 清单校验（per-repo 切片 + review 声明相交过滤，与主仓 Gate1/3b 同语义）。
-    // specBase 显式传（平台模式 changes/ 在 specRoot；本地模式与旧硬编码同值零回归）。
-    // review 声明收紧（D-003@v1，2026-09-14-change-ownership-guards task-03）：声明文件须与
-    // allow 面（design 清单 ∪ 各 task target_files/allowed_paths ∪ linked-change 声明 =
-    // resolveApplyAllowSet 现有并集）相交（pathMatches 容差）才计入；不相交的外来声明剔除出
-    // 放行面、进 violations 报告行（「review 声明了越权文件」嫌疑标注），admission 增量归零。
-    const allowMap = resolveApplyAllowSet(projectRoot, changeName, { specBase });
-    const allowSet = allowMap.get(repoKey) || new Set();
-    const reviewDeclared = collectReviewDeclaredFiles(projectRoot, changeName, { runtimeRoot: join(specBase, '.runtime') }).get(repoKey);
     const reviewForeign = [];
     if (reviewDeclared && allowSet.size > 0) {
       const face = [...allowSet];

package/src/worktree-cross.js

@@ -27,56 +27,117 @@
  */
 
 import { existsSync, readFileSync, readdirSync, mkdirSync } from 'fs';
-import { join } from 'path';
+import { join, dirname, resolve as resolvePath, isAbsolute, relative as relativePath } 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';
+import { parseRepoRegistry, parseRepoWorktreePlacements } from './stages/plan-postcheck.js';
+import {
+  crossWorktreePath as _placementCrossPath,
+  crossWorktreeDirName,
+  resolveCrossWorktreePath,
+  resolveCrossWorktreePathCandidates,
+  readCrossPlacementConfig,
+  resolvePlacementRoot,
+  readPlacementRegistry,
+  updatePlacementRegistry,
+  removePlacementRegistryEntry,
+  sweepPlacementRegistry,
+  isWslSplit,
+} from './cross-placement.js';
 
 const META_FILE = 'meta.json';
 const BRANCH_PREFIX = 'sillyspec/';
 
 /**
- * 跨仓 worktree 路径（唯一路径公式；multi-repo-context.js 的 meta 只读逻辑与此同步）。
+ * 跨仓 worktree 路径（唯一路径公式；实现已下沉 cross-placement 叶子模块——multi-repo-context.js
+ * 经该叶子模块共用，不再与 worktree-cross 经 run/shared 成环）。
+ * placementRoot 可选（坑 cross-wt-toolchain-split 落位配置）：给定时时 <placementRoot>/<change>--<repoKey>。
  * @param {string} specBase 主仓 spec 根（<主仓>/.sillyspec）
  * @param {string} changeName 变更名
  * @param {string} repoKey 跨仓 repo 键（local.yaml repos: 段的 key）
+ * @param {string|null} [placementRoot] 自定义落位根（null/缺省走默认公式——三参调用零回归）
  */
-export function crossWorktreePath(specBase, changeName, repoKey) {
-  return join(specBase, '.runtime', 'worktrees', `${changeName}--${repoKey}`);
+export function crossWorktreePath(specBase, changeName, repoKey, placementRoot = null) {
+  return _placementCrossPath(specBase, changeName, repoKey, placementRoot);
 }
 
 /**
  * 读跨仓 worktree meta（不存在/损坏返 null = legacy 直写模式）。
+ * 寻址经 resolveCrossWorktreePath（注册表优先、公式兜底）——worktree 挪到 crossPlacement
+ * 自定义落位后 meta 仍可达（坑 cross-wt-toolchain-split）。
  * @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;
+  // repoRoot 从 repos 注册表解析（无 repoKey 注册/解析失败 → null，候选列表少一级）
+  const mainRoot = dirname(specBase);
+  const repoRoot = parseRepoRegistry(readLocalYamlText(mainRoot)).get(repoKey) || null;
+  const resolvedRoot = repoRoot && !isAbsolute(repoRoot) ? resolvePath(mainRoot, repoRoot) : repoRoot;
+  // 寻址候选逐级探测：注册表 → 仓内新公式 → 主仓 specBase 旧公式（legacy 存量兜底）
+  for (const dir of resolveCrossWorktreePathCandidates(specBase, changeName, repoKey, resolvedRoot)) {
+    const metaPath = join(dir, META_FILE);
+    if (!existsSync(metaPath)) continue; // 未命中 → 下一候选
+    try {
+      const m = JSON.parse(readFileSync(metaPath, 'utf8'));
+      return m && m.isCross ? m : null; // 非跨仓/损坏 = 命中但无效
+    } catch {
+      return null;
+    }
   }
+  return null;
 }
 
 /**
- * 列出某变更已建的全部跨仓 worktree meta（扫描 worktrees 目录下 `<change>--*` 且 isCross 的 meta）。
+ * 列出某变更已建的全部跨仓 worktree meta（双源：worktrees 目录 `<change>--*` 扫描 ∪ 落位
+ * 注册表条目——坑 cross-wt-toolchain-split：worktree 挪到 crossPlacement 自定义目录后不在
+ * 默认存储目录下，纯目录扫描盲区）。注册表只提供位置：条目指向处须读到可解析且 isCross 的
+ * meta.json 才入列（与目录扫描同判据——不合成无 meta 条目，消费方 gates.js 解引用
+ * cm.depsStatus 零 TypeError 面）。按 repoKey 去重（注册表与目录扫描可能同指一处）。
  * @returns {Array<{repoKey: string, meta: object}>}
  */
 export function listCrossWorktreeMetas(specBase, changeName) {
   const base = join(specBase, '.runtime', 'worktrees');
-  if (!existsSync(base)) return [];
+  const candidates = []; // {dir}
+  const scanDir = (dir) => {
+    if (!existsSync(dir)) return;
+    try {
+      for (const name of readdirSync(dir)) {
+        if (!name.startsWith(`${changeName}--`)) continue;
+        candidates.push(join(dir, name));
+      }
+    } catch { /* 目录不可读跳过 */ }
+  };
+  // 源① 主仓 specBase 旧默认（legacy-main-specbase 存量）
+  scanDir(base);
+  // 源② 仓内新默认（<repoRoot>/.sillyspec/.runtime/worktrees——按 local.yaml repos 注册表枚举各仓）
+  const mainRoot = dirname(specBase);
+  const registryYaml = readLocalYamlText(mainRoot);
+  for (const repoRoot of parseRepoRegistry(registryYaml).values()) {
+    const root = isAbsolute(repoRoot) ? repoRoot : resolvePath(mainRoot, repoRoot);
+    scanDir(join(root, '.sillyspec', '.runtime', 'worktrees'));
+  }
+  // 源③ 注册表（注册表读取 fail-open 返回 {}——损坏降级纯目录扫描）
+  const registry = readPlacementRegistry(specBase);
+  const prefix = `${changeName}--`;
+  for (const [key, entry] of Object.entries(registry)) {
+    if (!key.startsWith(prefix)) continue;
+    if (entry && typeof entry.worktreePath === 'string' && entry.worktreePath) {
+      candidates.push(entry.worktreePath);
+    }
+  }
   const out = [];
-  for (const name of readdirSync(base)) {
-    if (!name.startsWith(`${changeName}--`)) continue;
-    const metaPath = join(base, name, META_FILE);
-    if (!existsSync(metaPath)) continue;
+  const seen = new Set();
+  for (const dir of candidates) {
+    const metaPath = join(dir, META_FILE);
+    if (!existsSync(metaPath)) continue; // 无 meta 不入列（含注册表悬挂键——sweep 前的过渡态）
     try {
       const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
-      if (meta && meta.isCross && meta.repoKey) out.push({ repoKey: meta.repoKey, meta });
+      if (meta && meta.isCross && meta.repoKey && !seen.has(meta.repoKey)) {
+        seen.add(meta.repoKey);
+        out.push({ repoKey: meta.repoKey, meta });
+      }
     } catch { /* 损坏 meta 跳过（cleanup 阶段仍按目录处理） */ }
   }
   return out;
@@ -105,17 +166,55 @@ function aggregateCrossRepoKeys(specBase, changeName) {
   return aggregateDeclaredRepos(planContent).filter(k => k !== 'main');
 }
 
+/**
+ * 读主仓 local.yaml 文本（路径口径与 run/shared.js readLocalYamlRaw 一致：cwd/.sillyspec/local.yaml）。
+ * @returns {string}
+ */
+function readLocalYamlText(cwd) {
+  const p = join(cwd, '.sillyspec', 'local.yaml');
+  if (!existsSync(p)) return '';
+  try { return readFileSync(p, 'utf8') } catch { return '' }
+}
+
+/** worktreePath 是否落在主仓 specBase 旧默认（legacy-main-specbase 形态——该形态不写注册表，公式可寻址） */
+function isLegacyMainSpecbasePlacement(worktreePath, specBase) {
+  try {
+    return resolvePath(dirname(worktreePath)) === resolvePath(join(specBase, '.runtime', 'worktrees'));
+  } catch { return false }
+}
+
+/**
+ * 仓内落位的 untracked 保障（坑 cross-wt-repo-local-placement）：.git/info/exclude 幂等追加
+ * 条目——本仓生效、不进版本库（不碰用户 .gitignore 工作区文件、无 pull 冲突面）。创建 worktree
+ * 前调用，worktree 目录一出现即被 git 忽略。追加失败（只读仓等）仅 warn 不阻断——最坏回落
+ * 「worktree 成 untracked 噪音」，apply 侧清单校验本就过滤。
+ * @param {string} repoRoot 跨仓仓根
+ * @param {string} entry exclude 条目（如 '.sillyspec/'）
+ */
+function ensureRepoLocalExclude(repoRoot, entry) {
+  try {
+    const excludePath = join(repoRoot, '.git', 'info', 'exclude');
+    let content = '';
+    if (existsSync(excludePath)) {
+      try { content = readFileSync(excludePath, 'utf8') } catch { content = '' }
+    }
+    const entryRe = new RegExp(`^${entry.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'm');
+    if (entryRe.test(content)) return; // 幂等：已有条目不动
+    const sep = content && !content.endsWith('\n') ? '\n' : '';
+    const stamp = `${sep}# sillyspec cross-repo worktree placement (auto)\n${entry}\n`;
+    mkdirSync(join(repoRoot, '.git', 'info'), { recursive: true });
+    writeAtomicSync(excludePath, content + stamp);
+  } catch (e) {
+    console.warn(`⚠️ 跨仓仓 .git/info/exclude 追加失败（${e.message}）——worktree 目录可能成 untracked 噪音，apply 清单校验仍会过滤，建议手工补 ignore。`);
+  }
+}
+
 /**
  * 读主仓 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);
+  return parseRepoRegistry(readLocalYamlText(cwd));
 }
 
 /**
@@ -132,6 +231,11 @@ export function ensureCrossWorktrees({ cwd, changeName, specBase }) {
   const base = specBase || join(cwd, '.sillyspec');
   const keys = aggregateCrossRepoKeys(base, changeName);
   const registry = readRepoRegistry(cwd);
+  // 落位配置双源（坑 cross-wt-toolchain-split 配置简化，2026-10-10 用户反馈）：推荐 repos 条目
+  // 内联（repos.<key>: {path, worktree}——注册与落位一处声明）；worktree.crossPlacement 段兼容
+  // 保留作 legacy 读面。优先级：repos.<key>.worktree > worktree.crossPlacement.<key> > 默认公式。
+  const inlinePlacements = parseRepoWorktreePlacements(readLocalYamlText(cwd));
+  const placementCfg = readCrossPlacementConfig(cwd);
   const created = [];
   const reused = [];
   const skippedLegacy = [];
@@ -156,9 +260,36 @@ export function ensureCrossWorktrees({ cwd, changeName, specBase }) {
       try { gitQuiet(repoRoot, ['worktree', 'prune'], { timeout: 30000 }) } catch {}
     }
 
-    const worktreePath = crossWorktreePath(base, changeName, key);
+    // 落位解析（FR-01/FR-02）：显式（repos.<key>.worktree 内联 > crossPlacement.<key> legacy）>
+    // 新默认=仓内 <repoRoot>/.sillyspec/.runtime/worktrees（坑 cross-wt-repo-local-placement：
+    // 天然同盘同文件系统，WSL 主仓+Windows 盘跨仓的工具链分裂自动消解——用户 2026-10-10 提议，
+    // 对齐主仓 worktree 的同构形态）。旧默认（主仓 specBase 下）降 legacy 兜底（resolve/扫描
+    // 仍认，存量 worktree 全链可达）。
+    // 显式配置指向仓根内维持拒绝（手配仓内=误配——untracked 噪音面）；新默认仓内合法，untracked
+    // 面由 ensureRepoLocalExclude 的 .git/info/exclude 保障（不动用户 .gitignore、不进版本库）。
+    const rawPlacement = inlinePlacements.get(key) || placementCfg.get(key) || null;
+    let placementRoot = null;
+    let placementMode = 'repo-local';
+    if (rawPlacement) {
+      placementRoot = resolvePlacementRoot(rawPlacement, cwd);
+      placementMode = inlinePlacements.has(key) ? 'explicit-inline' : 'explicit-legacy';
+      const rel = relativePath(resolvePath(repoRoot), placementRoot);
+      if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) {
+        throw new Error(
+          `跨仓 repo "${key}" 的落位配置（${placementRoot}）落在该仓仓根（${repoRoot}）之内——` +
+          `显式落位应选该仓之外的目录（仓内落位请删掉该配置走默认）。重跑 execute 前修正配置。`
+        );
+      }
+    }
+    const worktreePath = crossWorktreePath(base, changeName, key, placementRoot || join(repoRoot, '.sillyspec', '.runtime', 'worktrees'));
     const branch = BRANCH_PREFIX + changeName;
 
+    // 仓内落位的 untracked 保障：.git/info/exclude 幂等追加 .sillyspec/（本仓生效、不进版本库、
+    // 不碰用户 .gitignore）。创建 worktree 前落盘——worktree 目录一出现即被忽略。
+    if (!rawPlacement) {
+      ensureRepoLocalExclude(repoRoot, '.sillyspec/');
+    }
+
     // base 快照：跨仓仓当前 HEAD（与主仓 create 的默认 base 语义一致）
     let baseHash;
     try {
@@ -175,13 +306,27 @@ export function ensureCrossWorktrees({ cwd, changeName, specBase }) {
         `  ③ 换变更名重跑。`
       );
     }
-    mkdirSync(join(base, '.runtime', 'worktrees'), { recursive: true });
+    if (rawPlacement) {
+      mkdirSync(placementRoot, { recursive: true });
+    } else {
+      mkdirSync(join(repoRoot, '.sillyspec', '.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}`);
     }
 
+    // WSL 跨文件系统分裂警告（FR-03，advisory 不阻断——坑 cross-wt-toolchain-split：主仓在
+    // WSL /root、跨仓在 /mnt/<盘>/ Windows 盘时，worktree 默认落 WSL 原生 fs，该仓 Windows
+    // 侧工具链（mvn/JDK）够不着，隔离形同虚设——fire-equipment 2026-10-10 实证被迫绕开
+    // worktree 直写主干。配置同侧落位后本警告自然消音）。
+    if (isWslSplit(repoRoot, worktreePath)) {
+      console.warn(`⚠️ 跨仓 ${key}: 工具链分裂风险——仓根在 WSL automount Windows 盘（${repoRoot}）而 worktree 落在 WSL 原生文件系统（${worktreePath}）。`);
+      console.warn(`   该仓若依赖 Windows 侧构建工具链（mvn/JDK/IDE），将无法访问 worktree——2026-10-10 实证此形态下 agent 被迫绕开 worktree 直写主副本。`);
+      console.warn(`   建议：local.yaml 配 worktree.crossPlacement.${key} 到该仓可达的目录（如同盘符路径），重跑 execute 前先 sillyspec worktree cleanup ${changeName} --force。`);
+    }
+
     const meta = {
       name_zh: 'worktree 元数据',
       changeName,
@@ -195,6 +340,7 @@ export function ensureCrossWorktrees({ cwd, changeName, specBase }) {
       createdAt: new Date().toISOString(),
       worktreePath,
       mode: 'worktree',
+      placementMode,
     };
     writeAtomicSync(join(worktreePath, META_FILE), JSON.stringify(meta, null, 2) + '\n');
 
@@ -209,6 +355,12 @@ export function ensureCrossWorktrees({ cwd, changeName, specBase }) {
     console.log(`ℹ️ 跨仓 ${key}: 跳过 dirty baseline checkpoint（跨仓主副本在途改动不进本变更分支——含并行会话外来文件时防污染；锚点 = 跨仓仓 HEAD ${String(baseHash).slice(0, 8)}）`);
     writeAtomicSync(join(worktreePath, META_FILE), JSON.stringify(meta, null, 2) + '\n');
 
+    // 落位注册表（FR-02）：仓内新默认与显式落位都记录位置（新默认位置依赖 repoRoot，读取方
+    // 无 repoRoot 上下文时公式兜底不可用——注册表是主寻址）；落主仓 specBase 的旧默认不写。
+    if (placementRoot || !isLegacyMainSpecbasePlacement(worktreePath, base)) {
+      updatePlacementRegistry(base, changeName, key, { worktreePath, placementRoot: placementRoot || join(repoRoot, '.sillyspec', '.runtime', 'worktrees') });
+    }
+
     // deps 供给：specBase 传 null —— sniff worktree 自身（主仓 local.yaml 的 project.type/install
     // 描述的是主仓，跨仓仓类型常不同，如实测 maven 主仓 + nodejs 前端仓，沿用会把 mvn 命令
     // 打到前端仓上）。失败不阻断（与主仓 create 同语义，doctor --fix 可修）
@@ -229,7 +381,7 @@ export function ensureCrossWorktrees({ cwd, changeName, specBase }) {
       writeAtomicSync(join(worktreePath, META_FILE), JSON.stringify(meta, null, 2) + '\n');
     }
 
-    created.push({ repoKey: key, worktreePath });
+    created.push({ repoKey: key, worktreePath, meta });
   }
   return { created, reused, skippedLegacy };
 }
@@ -255,6 +407,7 @@ export function cleanupCrossWorktrees({ cwd, changeName, specBase, force = false
     const wtPath = meta.worktreePath || crossWorktreePath(base, changeName, repoKey);
     if (!existsSync(wtPath)) {
       try { if (repoRoot) gitQuiet(repoRoot, ['worktree', 'prune'], { timeout: 30000 }) } catch {}
+      removePlacementRegistryEntry(base, changeName, repoKey); // 挪位清理后注册表键回收（FR-02）
       results.push({ repoKey, result: 'skipped', details: ['目录不存在（已清理）'], residual });
       continue;
     }
@@ -282,7 +435,15 @@ export function cleanupCrossWorktrees({ cwd, changeName, specBase, force = false
       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}）`);
+    if (residual.length === 0) {
+      removePlacementRegistryEntry(base, changeName, repoKey); // cleaned 后注册表键回收（FR-02）
+    }
     results.push({ repoKey, result: residual.length > 0 ? 'partial' : 'cleaned', details, residual });
   }
+  // 差集 sweep（评审 P2 吸收）：cleanup 迭代源=listCrossWorktreeMetas 只列有 meta 条目，
+  // 「worktree remove 连目录带 meta 同亡、仅注册表键存」的悬挂键够不着——末尾对本变更名下
+  // 全部键按「worktreePath 处无 meta.json」差集清（活键不删）。
+  const swept = sweepPlacementRegistry(base, changeName);
+  if (swept.length > 0) results.push({ repoKey: '(registry-sweep)', result: 'cleaned', details: [`悬挂注册表键已清: ${swept.join('、')}`], residual: [] });
   return { results };
 }

package/src/worktree-deps.js

@@ -38,21 +38,24 @@ const DEFAULT_TIMEOUT_MS = 300 * 1000;
  */
 const ECOSYSTEMS = [
   {
+    // JVM 系（maven/gradle）install=null（坑 maven-provision-runs-tests，2026-10-10 用户实证）：
+    // 依赖在用户级仓库（~/.m2、~/.gradle），worktree 内无本地产物可供给——根供给诚实落 n/a
+    // （deps 门控放行集含 n/a）。旧默认 'mvn -o test' 把跑测试当供给：冷缓存 + 离线 + 工具链
+    // 不在 PATH 必败 → depsStatus=failed 卡死 execute --done（agent 被迫手改 meta）。构建/测试
+    // 归 task 级验证（mvn compile / gradle build 在任务验收面显式执行）；显式 commands.install
+    // 配置时仍按白名单执行（inferInstallCommand 优先级不变）。
     type: 'maven',
     manifests: ['pom.xml'],
     marker: null,
     detect: (d) => existsSync(join(d, 'pom.xml')),
-    install: () => 'mvn -o test',
+    install: null,
   },
   {
     type: 'gradle',
     manifests: ['build.gradle.kts', 'build.gradle', 'settings.gradle', 'gradle.lockfile'],
     marker: null,
     detect: (d) => existsSync(join(d, 'build.gradle')) || existsSync(join(d, 'build.gradle.kts')),
-    // win32 cmd.exe 跑不了 ./gradlew（体检 BUG-08 同型）：优先 gradlew.bat，否则全局 gradle
-    install: (d) => (process.platform === 'win32'
-      ? (existsSync(join(d, 'gradlew.bat')) ? 'gradlew.bat test' : 'gradle test')
-      : './gradlew test'),
+    install: null,
   },
   {
     type: 'nodejs',
@@ -210,7 +213,10 @@ export function detectProjectType(worktreePath, specBase) {
 export function inferInstallCommand(projectType, worktreePath, userInstall) {
   if (userInstall) return userInstall;
   const eco = ECOSYSTEMS.find(e => e.type === projectType);
-  return eco ? eco.install(worktreePath) : null;
+  // install:null 表项（maven/gradle——依赖在用户级仓库无 worktree 内供给面）与表外类型同归
+  // null → 根供给 n/a（坑 maven-provision-runs-tests）
+  if (!eco || typeof eco.install !== 'function') return null;
+  return eco.install(worktreePath);
 }
 
 /** 在 worktreePath 创建 node_modules 链接到 mainNodeModules；失败回退 */
@@ -640,10 +646,45 @@ export function provisionDeps(worktreePath, mainCwd, opts = {}) {
     const lines = String(yamlText || '').replace(/\r\n?/g, '\n').split('\n');
     const start = lines.findIndex(l => /^repos:\s*(?:#.*)?$/.test(l));
     if (start === -1) return roots;
+    const cleanVal = (v) => String(v || '').replace(/\s+#.*$/, '').trim().replace(/^['"]|['"]$/g, '');
     for (let i = start + 1; i < lines.length; i++) {
-      if (lines[i].length > 0 && !/\s/.test(lines[i][0]) && lines[i].trim() !== '' && !lines[i].startsWith('#')) break;
-      const m = lines[i].match(/^\s+([A-Za-z0-9_.\-]+):\s*(\S+)/);
-      if (m && !m[2].startsWith('#')) roots.push(m[2].replace(/^['"]|['"]$/g, ''));
+      const line = lines[i];
+      if (line.length > 0 && !/\s/.test(line[0]) && line.trim() !== '' && !line.startsWith('#')) break;
+      const m = line.match(/^\s+([A-Za-z0-9_.\-]+):\s*(.*)$/);
+      if (!m) continue;
+      const value = (m[2] || '').trim();
+      if (value !== '' && !value.startsWith('#')) {
+        if (value.startsWith('{') && value.endsWith('}')) {
+          // inline 对象条目（repos.<key>: {path: .., worktree: ..}）——只收 path 子键
+          for (const part of value.slice(1, -1).split(',')) {
+            const idx = part.indexOf(':');
+            if (idx !== -1 && part.slice(0, idx).trim() === 'path') {
+              const p = cleanVal(part.slice(idx + 1));
+              if (p) roots.push(p);
+              break;
+            }
+          }
+        } else {
+          roots.push(cleanVal(value));
+        }
+        continue;
+      }
+      // 块式对象条目（value 空）：消费子键块，只收 path 子键值（worktree 落位根不是仓根，
+      // 混入会放宽越界豁免面——坑 repo-inline-worktree-placement 收口）
+      const indent = line.length - line.trimStart().length;
+      let j = i + 1;
+      for (; j < lines.length; j++) {
+        const l = lines[j];
+        if (l.trim() === '' || l.trim().startsWith('#')) continue;
+        const subIndent = l.length - l.trimStart().length;
+        if (subIndent <= indent) break;
+        const sub = l.match(/^\s+([A-Za-z0-9_.\-]+):\s*(.*)$/);
+        if (sub && sub[1] === 'path') {
+          const p = cleanVal(sub[2]);
+          if (p && !p.startsWith('#')) roots.push(p);
+        }
+      }
+      i = j - 1;
     }
     return roots;
   })();

package/src/worktree.js

@@ -1326,9 +1326,17 @@ export class WorktreeManager {
    * 写进 worktree 内的 .sillyspec——而 apply 的 filterDeliverableFiles 把 .sillyspec/changes/ 排除在
    * 交付外（spec 文档不进代码 patch），cleanup 删除 worktree 这些产物即蒸发、主仓流程看不到。
    * 删除前扫 worktree 内两棵子树做最后打捞：
-   *   changes/<name>/** → 主仓缺失则 copy 回（verify-result.md 等核心场景）；同名不同内容仅列
-   *                      清单 warn 不覆盖（主仓版本可能是更新的，覆盖会倒退）
-   *   docs/**           → 主仓缺失则 copy 回（模块文档卡片；同名差异不提示——tracked checkout 副本常态）
+   *   changes/<name>/** → 三态判定（坑 archive-resurrect，2026-10-10 下游实证
+   *                      2026-10-09-attachment-inline-reference 残留 13 文件：归档把 changes/<name>/
+   *                      整体 rename 进 changes/archive/ 后，原路径缺失被误判 worktree 独有，旧快照
+   *                      整批复制回原路径复活已归档目录）：
+   *                      · 原路径同名存在 → 内容不同仅列清单 warn 不覆盖（主仓版本可能是更新的）
+   *                      · 原路径缺、changes/archive/<name>/ 有副本 → 判归档搬运，跳过不复制
+   *                        （不复活原路径、不覆盖 archive 权威副本）
+   *                      · 原路径与 archive 均缺 → 真 worktree 独有照捞：归档态捞进
+   *                        changes/archive/<name>/（原路径已注销禁止重建），未归档态捞回原路径
+   *   docs/**           → 主仓缺失则 copy 回（模块文档卡片；同名差异不提示——tracked checkout 副本常态；
+   *                      docs 不参与归档搬运，无三态）
    * 只扫本变更子树（其它 change 的副本文件不越权搬运）。异常只 warn 不阻断清理。
    * @private
    */
@@ -1340,7 +1348,11 @@ export class WorktreeManager {
       if (resolve(wtSpec) === resolve(mainSpec)) return; // in-place：同一目录，无需打捞
       const salvaged = [];
       const conflicts = [];
-      const salvageTree = (subDir, reportConflict) => {
+      const archivedSkipped = [];
+      const salvagedIntoArchive = [];
+      const archivedBase = join('changes', 'archive', name);
+      const archivedBaseExists = existsSync(join(mainSpec, archivedBase));
+      const salvageTree = (subDir, reportConflict, trackArchive) => {
         const srcRoot = join(wtSpec, subDir);
         if (!existsSync(srcRoot)) return;
         const walk = (dir) => {
@@ -1349,28 +1361,50 @@ export class WorktreeManager {
             if (entry.isDirectory()) { walk(src); continue; }
             if (!entry.isFile()) continue;
             const rel = relative(wtSpec, src);
+            const rest = relative(srcRoot, src);
             const dst = join(mainSpec, rel);
+            const archivedDst = trackArchive ? join(mainSpec, archivedBase, rest) : null;
             try {
-              if (!existsSync(dst)) {
+              if (existsSync(dst)) {
+                if (reportConflict && readFileSync(src, 'utf8') !== readFileSync(dst, 'utf8')) {
+                  conflicts.push(rel);
+                }
+              } else if (archivedDst && existsSync(archivedDst)) {
+                archivedSkipped.push(rest);
+              } else if (archivedDst && archivedBaseExists) {
+                mkdirSync(dirname(archivedDst), { recursive: true });
+                copyFileSync(src, archivedDst);
+                salvagedIntoArchive.push(rest);
+              } else {
                 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);
+      salvageTree(join('changes', name), true, true);
+      salvageTree('docs', false, 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 (salvagedIntoArchive.length > 0) {
+        console.warn(`⚠️ worktree 清理前打捞：${salvagedIntoArchive.length} 个真独有产物（原路径与归档副本均缺）已捞进归档副本（变更已归档，原路径不重建）：`);
+        for (const f of salvagedIntoArchive.slice(0, 20)) console.warn(`   ${join(mainSpec, archivedBase, f)}`);
+        if (salvagedIntoArchive.length > 20) console.warn(`   …等共 ${salvagedIntoArchive.length} 个`);
+        details.push(`salvaged ${salvagedIntoArchive.length} spec artifacts into archive copy`);
+      }
+      if (archivedSkipped.length > 0) {
+        console.warn(`⏭️ worktree 清理前打捞：${archivedSkipped.length} 个流程产物判定为归档搬运（主仓 changes/${name}/ 原路径不存在、changes/archive/${name}/ 已有副本），跳过不复制——防复活已归档目录：`);
+        for (const f of archivedSkipped.slice(0, 20)) console.warn(`   ${join(mainSpec, archivedBase, f)}`);
+        if (archivedSkipped.length > 20) console.warn(`   …等共 ${archivedSkipped.length} 个`);
+        details.push(`skipped ${archivedSkipped.length} archived-moved spec artifacts (resurrect guard: changes/${name}/ not rebuilt)`);
+      }
       if (conflicts.length > 0) {
         console.warn(`⚠️ worktree 与主仓存在同名但内容不同的流程产物（不覆盖，请人工确认是否需要合并）：`);
         for (const f of conflicts.slice(0, 20)) console.warn(`   ${join(mainSpec, f)}`);

package/assets/command-cards/run-quick.md

@@ -1,20 +0,0 @@
----
-name: sillyspec:run-quick
-description: 已退役重定向 — quick 通道已拒绝新会话（v3.31.0 起），小修补请用 /sillyspec:flow
----
-# 通道已退役
-
-quick 通道已于 v3.31.0 直接退役：`sillyspec run quick` 对新会话一律拒绝（exit 1 并指路 flow start）。本卡只保留触发词重定向，勿执行任何 quick 新会话命令。
-
-范围明确的小修补请走**轻量变更**（/sillyspec:flow）：
-
-```bash
-sillyspec flow start --change <变更名> --input "<动机与背景>
-
-成功标准：
-- <可验证标准>"
-# → 直接干活（改代码写测试，治理工件 CLI 机器起草）
-sillyspec flow done --change <变更名>
-```
-
-升级前遗留的在途 quick 会话仍可收尾：`sillyspec run quick --change <会话ID>` 续跑 / `--done` 收口 / `--cancel` 取消（以 CLI 拒绝文案里的指引为准）。