sillyspec 3.20.6 → 3.21.0

package/src/stages/plan-postcheck.js

@@ -11,6 +11,8 @@
  */
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import { join as pJoin } from 'path'
+import jsYaml from 'js-yaml'
+import { parseFileChangeList } from '../change-list.js'
 
 // ═══════════════════════════════════════════════════════════════
 // 解析工具（从 plan.js 迁移）
@@ -90,6 +92,47 @@ function hasTddOrVerify(content) {
   return /##\s*TDD/.test(content) || /##\s*验证/.test(content) || /##\s*Verify/.test(content)
 }
 
+/**
+ * 解析 task-NN.md 的跨任务契约字段 provides / expects_from
+ * 用 js-yaml 解析 frontmatter（嵌套结构，正则不可靠）。
+ * provides/expects_from 为可选字段；缺失或解析失败时返回空（不阻断）。
+ * @param {string} content - task 文件内容
+ * @returns {{ provides: Array<{contract, fields}>, expectsFrom: Record<string, Array<{contract, needs}>> }}
+ */
+export function parseTaskContracts(content) {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/)
+  if (!fmMatch) return { provides: [], expectsFrom: {} }
+  let fm
+  try {
+    fm = jsYaml.load(fmMatch[1]) || {}
+  } catch {
+    // frontmatter 非合法 YAML（老格式/手写不规范）—— 当作无契约字段，不阻断
+    return { provides: [], expectsFrom: {} }
+  }
+
+  const provides = Array.isArray(fm.provides)
+    ? fm.provides.map(p => ({
+        contract: String(p?.contract || ''),
+        fields: Array.isArray(p?.fields) ? p.fields.map(String) : [],
+      })).filter(p => p.contract)
+    : []
+
+  const expectsFrom = {}
+  if (fm.expects_from && typeof fm.expects_from === 'object' && !Array.isArray(fm.expects_from)) {
+    for (const [providerTask, contracts] of Object.entries(fm.expects_from)) {
+      if (!Array.isArray(contracts)) continue
+      expectsFrom[providerTask] = contracts
+        .map(c => ({
+          contract: String(c?.contract || ''),
+          needs: Array.isArray(c?.needs) ? c.needs.map(String) : [],
+        }))
+        .filter(c => c.contract)
+    }
+  }
+
+  return { provides, expectsFrom }
+}
+
 // ═══════════════════════════════════════════════════════════════
 // 核心逻辑
 // ═══════════════════════════════════════════════════════════════
@@ -222,6 +265,171 @@ export function validateBlueprintConsistency(changeDir) {
   return { ok: errors.length === 0, errors, warnings }
 }
 
+/**
+ * 跨任务契约校验器：对账 consumer.expects_from ↔ provider.provides
+ *
+ * 修复场景：consumer task 声明期望 provider 产出某 DTO 的某字段，
+ * 但 provider 的 provides 未承诺（或字段缺失）→ plan 阶段阻断，
+ * 避免到 execute/verify 才暴露（典型表现：前端 fallback 错误字段 → 403/500）。
+ *
+ * provides / expects_from 均为可选字段：未声明时不校验（向后兼容）。
+ * @param {string} changeDir - 变更目录
+ * @returns {{ ok: boolean, errors: string[], warnings: string[] }}
+ */
+export function validateCrossTaskContracts(changeDir) {
+  const errors = []
+  const warnings = []
+
+  const tasksDir = pJoin(changeDir, 'tasks')
+  if (!existsSync(tasksDir)) {
+    return { ok: true, errors, warnings }
+  }
+
+  const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))
+  if (taskFiles.length === 0) {
+    return { ok: true, errors, warnings }
+  }
+
+  // 第一遍：收集每个 task 的 provides（taskId → Map(contract → Set(fields))）
+  const providesByTask = new Map()
+  for (const file of taskFiles) {
+    const content = readFileSync(pJoin(tasksDir, file), 'utf8')
+    const taskId = parseTaskId(content, file)
+    if (!taskId) continue
+    const { provides } = parseTaskContracts(content)
+    const contractMap = new Map()
+    for (const p of provides) {
+      contractMap.set(p.contract, new Set(p.fields))
+    }
+    providesByTask.set(taskId, contractMap)
+  }
+
+  // 第二遍：校验每个 consumer 的 expects_from 是否被 provider.provides 覆盖
+  for (const file of taskFiles) {
+    const content = readFileSync(pJoin(tasksDir, file), 'utf8')
+    const consumerId = parseTaskId(content, file)
+    if (!consumerId) continue
+    const { expectsFrom } = parseTaskContracts(content)
+
+    for (const [providerTask, contracts] of Object.entries(expectsFrom)) {
+      if (!providesByTask.has(providerTask)) {
+        for (const c of contracts) {
+          errors.push(`${consumerId}: expects_from 引用了不存在的 ${providerTask}（contract "${c.contract}", needs [${c.needs.join(', ')}]）`)
+        }
+        continue
+      }
+
+      const providerContracts = providesByTask.get(providerTask)
+      for (const c of contracts) {
+        const providerFields = providerContracts.get(c.contract)
+        if (providerFields === undefined) {
+          errors.push(`${consumerId}: expects_from ${providerTask} contract "${c.contract}" needs [${c.needs.join(', ')}] — ${providerTask} 的 provides 未声明此契约`)
+          continue
+        }
+        const missing = c.needs.filter(f => !providerFields.has(f))
+        if (missing.length > 0) {
+          errors.push(`${consumerId}: expects_from ${providerTask} contract "${c.contract}" needs [${missing.join(', ')}] — ${providerTask}.provides 仅含 [${[...providerFields].join(', ')}]`)
+        }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+// ── 路径匹配工具（与 change-list.js 的 normalizeEntry 同源语义）─────────
+// allowed_paths 真实写法常带行内注释（`src/worktree.js (新增)`），匹配前必须归一化。
+function normalizePath(raw) {
+  if (!raw) return ''
+  return raw
+    .replace(/`/g, '')
+    .replace(/\s*（[^）]*）\s*$/, '')
+    .replace(/\s*\([^)]*\)\s*$/, '')
+    .replace(/\\/g, '/')
+    .replace(/\/+$/, '')
+    .trim()
+}
+
+function globMatch(str, pattern) {
+  if (!pattern.includes('*')) return false
+  const re = '^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*') + '$'
+  try { return new RegExp(re).test(str) } catch { return false }
+}
+
+/**
+ * 双向容差匹配：design 清单文件 vs task allowed_paths
+ * 命中条件（任一）：完全相等 / 目录前缀包含（双向）/ glob 通配（双向）
+ */
+function pathMatches(designFile, allowedPath) {
+  const a = normalizePath(designFile)
+  const b = normalizePath(allowedPath)
+  if (!a || !b) return false
+  if (a === b) return true
+  if (a.startsWith(b + '/') || b.startsWith(a + '/')) return true
+  if (globMatch(a, b) || globMatch(b, a)) return true
+  return false
+}
+
+/**
+ * design.md 文件变更清单 → tasks allowed_paths 覆盖对账
+ *
+ * 修复场景：design.md 声明要改某源码文件（如 access-guide UI），但没有任何 task 的
+ * allowed_paths 覆盖它 → execute 子代理被 allowed_paths 锁死不能碰它 → UI 没改
+ * （「页面还是错的」），而 verify 一路对照 task 卡片循环验证照样 PASS。
+ *
+ * 在 plan-postcheck（execute 前）确定性拦截：design 清单中每个源码文件必须被
+ * 至少一个 task 的 allowed_paths 覆盖（前缀 / glob 容差匹配）。
+ *
+ * fail-open 边界（不阻断）：design.md 不存在、无清单章节、解析为空、无 tasks/、
+ * 无 allowed_paths —— 保持与 none/light 级别及老变更向后兼容。
+ *
+ * @param {string} changeDir - 变更目录
+ * @returns {{ ok: boolean, errors: string[], warnings: string[], designFiles: string[], uncovered: string[] }}
+ */
+export function validateDesignFileCoverage(changeDir) {
+  const errors = []
+  const warnings = []
+
+  const designPath = pJoin(changeDir, 'design.md')
+  if (!existsSync(designPath)) {
+    return { ok: true, errors, warnings, designFiles: [], uncovered: [] }
+  }
+
+  const designFiles = [...parseFileChangeList(designPath)]
+  if (designFiles.length === 0) {
+    warnings.push('design.md 未找到「文件变更清单」或清单为空，跳过文件覆盖对账')
+    return { ok: true, errors, warnings, designFiles: [], uncovered: [] }
+  }
+
+  const tasksDir = pJoin(changeDir, 'tasks')
+  if (!existsSync(tasksDir)) {
+    return { ok: true, errors, warnings, designFiles, uncovered: [] }
+  }
+
+  const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))
+  const allAllowed = []
+  for (const file of taskFiles) {
+    const content = readFileSync(pJoin(tasksDir, file), 'utf8')
+    allAllowed.push(...parseAllowedPaths(content))
+  }
+  if (allAllowed.length === 0) {
+    return { ok: true, errors, warnings, designFiles, uncovered: [] }
+  }
+
+  const uncovered = designFiles.filter(df => !allAllowed.some(ap => pathMatches(df, ap)))
+  if (uncovered.length > 0) {
+    errors.push(
+      `design.md 文件变更清单中 ${uncovered.length} 个文件未被任何 task 的 allowed_paths 覆盖：\n` +
+      uncovered.map(f => `     • ${f}`).join('\n') +
+      `\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。` +
+      `\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，` +
+      `或在 design.md「不修改文件」章节说明不改原因。`
+    )
+  }
+
+  return { ok: errors.length === 0, errors, warnings, designFiles, uncovered }
+}
+
 /**
  * Plan 可行性校验器（本地代码证明 execute 前置条件）
  * 检查 TaskCard 的完整性和可行性
@@ -426,6 +634,32 @@ export async function executePlanPostcheck(context) {
     for (const w of feasibility.warnings) console.warn(`   - ${w}`)
   }
 
+  // ── 1c. 跨任务契约校验 ──
+  // 对账 consumer.expects_from ↔ provider.provides，拦截「consumer 期望字段
+  // 但 provider 未承诺」的契约断裂（避免到 execute/verify 才暴露成 403/500）
+  const crossTask = validateCrossTaskContracts(changeDir)
+  if (crossTask.errors.length > 0) {
+    console.error('\n❌ 跨任务契约校验失败（consumer 期望的字段未被 provider 承诺）：')
+    for (const err of crossTask.errors) console.error(`   - ${err}`)
+    console.error('\n   修复方式：要么在 provider task 的 provides.fields 补上缺失字段，')
+    console.error('   要么修正 consumer task 的 expects_from.needs（确认依赖是否真实）。')
+    throw new Error('planPostcheck: cross-task contract check failed')
+  }
+
+  // ── 1d. design 文件覆盖对账 ──
+  // design.md 清单中的每个源码文件必须被某 task 的 allowed_paths 覆盖，
+  // 否则 execute 子代理无权改它 → 漏改（典型表现：「页面还是错的」）。
+  const coverage = validateDesignFileCoverage(changeDir)
+  for (const w of coverage.warnings) console.warn(`\n  ⚠️  ${w}`)
+  if (coverage.errors.length > 0) {
+    console.error('\n❌ design.md 文件覆盖对账失败（清单中的文件未被任何 task 覆盖）：')
+    for (const err of coverage.errors) console.error(`   - ${err}`)
+    throw new Error('planPostcheck: design file coverage check failed')
+  }
+  if (coverage.designFiles.length > 0 && coverage.uncovered.length === 0) {
+    console.log(`  ✅ design.md ${coverage.designFiles.length} 个文件全部被 task allowed_paths 覆盖`)
+  }
+
   // ── 2. Wave 重排 ──
   const tasksDir = pJoin(changeDir, 'tasks')
   if (existsSync(tasksDir)) {

package/src/stages/plan.js

@@ -358,6 +358,8 @@ full 计划的约束：
 - [ ] plan.md 与 design.md 的文件变更清单一致
 - [ ] 如果涉及构造函数/接口/DTO/client 方法变更，是否搜索了所有调用点并纳入任务范围？
 - [ ] 调用点搜索命令的输出是否记录在 plan.md 或 task-NN.md 中？
+- [ ] 跨任务契约自检：若 task-A 的产出（接口/DTO/响应）被 task-B 消费，consumer 是否在 TaskCard expects_from 里声明所需字段、provider 是否在 provides 里承诺这些字段、两边字段是否一致？（plan-postcheck 会硬校验，此处先自查）
+- [ ] 文件覆盖自检：design.md「文件变更清单」中的每个源码文件，是否都被至少一个 task 的 allowed_paths 覆盖？（plan-postcheck 会硬校验，漏覆盖 = execute 必然漏改，此处先自查）
 - [ ] 如果有 Mermaid 图，依赖关系确实非平凡（非线性/非全并行）
 - [ ] 没有泛泛风险分析（如"需要充分测试"）
 
@@ -407,6 +409,13 @@ requirement_ids: [FR-XX]
 decision_ids: [D-XXX@vN]
 allowed_paths:
   - frontend/src/lib/errors.ts
+provides:                              # 可选。仅当本 task 给其他 task 提供接口/DTO/响应时填
+  - contract: <DTO或响应类型名>          # 如 DaemonRuntimeRead
+    fields: [field_a, field_b]
+expects_from:                          # 可选。仅当本 task 消费其他 task 的契约时填
+  <provider-task-id>:                  # 如 task-05（占位符，不要照抄）
+    - contract: <DTO或响应类型名>
+      needs: [field_a]                 # 必须从该 provider 拿到的字段
 goal: >
   一句话说明这个 task 要做什么、为什么。
 implementation:
@@ -433,6 +442,9 @@ TaskCard 格式规则（必须严格遵守）：
 - verify: 列表，实际可执行的命令
 - constraints: 列表，明确边界（含 brownfield 兼容、异常处理）
 - 不需要：修改文件章节、覆盖来源章节、接口定义章节、TDD 步骤章节、参考章节
+- provides / expects_from 是可选字段：仅当跨 task 契约（一个 task 的接口/DTO/响应被另一个 task 消费）时才填，单 task 或无对外接口场景留空即可
+- 填写后 plan-postcheck 会做硬对账：consumer 的每个 expects_from[provider].needs 字段必须在对应 provider 的 provides.fields 里，否则 plan 阶段阻断（不进入 execute）
+- 不要把内部实现字段塞进 provides；只暴露给其他 task 的对外契约形状
 - 如果存在 decisions.md，无法覆盖的 D-xxx@vN 在 constraints 中标注
 - 写完后用 Write tool 保存到文件
 \`\`\``
@@ -471,6 +483,7 @@ ${subagentPrompts}
 - **一致性自查**：
   - allowed_paths 有无冲突
   - depends_on 与 plan.md Wave 分组是否一致
+  - provides/expects_from 契约自洽：每个 expects_from[provider].needs 字段都在该 provider task 的 provides.fields 里（plan-postcheck 会硬校验，这里提前自查）
   - 如发现矛盾，列出问题清单，不要自动修复`
 
   return {

package/src/sync.js

@@ -12,6 +12,16 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from '
 import { join } from 'path';
 import { resolvePlatformSpecDir } from './progress.js';
 
+// sync 是 best-effort（网络失败只 warn）：平台指针失效时不抛，跳过平台、回退本地。
+function safePlatformSpecDir(cwd) {
+  try {
+    return resolvePlatformSpecDir(cwd);
+  } catch (e) {
+    console.warn(`[sync] 平台指针不可用，跳过平台同步：${String(e.message).split('\n')[0]}`);
+    return undefined;
+  }
+}
+
 const LOCAL_YAML = '.sillyspec/local.yaml';
 const CHANGES_DIR = '.sillyspec/changes';
 const REQUEST_TIMEOUT_MS = 10_000;
@@ -201,7 +211,7 @@ export class SyncManager {
     let progressData;
     try {
       const { ProgressManager } = await import('./progress.js');
-      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(this.cwd) });
+      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
       progressData = await pm.read(this.cwd, changeName);
     } catch (err) {
       console.warn(`[sync] 读取 progress 失败 (${changeName}): ${err.message}`);
@@ -226,7 +236,7 @@ export class SyncManager {
     // 更新 platform_last_sync
     try {
       const { ProgressManager } = await import('./progress.js');
-      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(this.cwd) });
+      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
       await pm._updatePlatformLastSync(this.cwd, changeName);
     } catch (err) {
       console.warn(`[sync] 更新 platform_last_sync 失败: ${err.message}`);
@@ -327,7 +337,7 @@ export class SyncManager {
     // 更新本地 approvals 表
     try {
       const { ProgressManager } = await import('./progress.js');
-      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(this.cwd) });
+      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
       await pm._updateApprovalStatus(this.cwd, changeName, result.status, result.reason);
     } catch (err) {
       console.warn(`[sync] 更新本地审批状态失败: ${err.message}`);

package/src/worktree.js

@@ -73,6 +73,17 @@ function parseJSON(raw) {
   try { return JSON.parse(raw); } catch { return null; }
 }
 
+/**
+ * 跨平台同步等待（cleanup 重试退避用）
+ * 不依赖外部 sleep 命令——Windows cmd.exe 无 sleep；当 Git for Windows 未把 usr/bin 加入
+ * PATH 时，execSync('sleep 0.5') 会抛错并从 catch 块冒泡，直接中断整个 cleanup()。
+ * 改用 busy-wait 规避，保证 retry 之间真有间隔且不依赖环境。
+ */
+function sleepMs(ms) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) { /* spin */ }
+}
+
 function computeBaselineHash(cwd) {
   // 排除 .sillyspec/ 元数据目录，避免 brainstorm/plan 阶段修改的蓝图文件污染 baseline
   const exclude = '-- . ":(exclude).sillyspec/"';
@@ -198,7 +209,7 @@ export class WorktreeManager {
     if (isolation.inSubmodule) {
       throw new Error(
         '当前目录在 git submodule 内，SillySpec worktree 不支持在 submodule 中创建。' +
-        '\n请在主仓库中执行，或使用 --no-worktree 跳过隔离。'
+        '\n请在主仓库根目录执行 execute。'
       );
     }
     if (isolation.inWorktree) {
@@ -237,6 +248,10 @@ export class WorktreeManager {
       if (!this.getMeta(name)) {
         console.log(`⚠️  检测到幽灵 worktree 目录（无 meta.json），自动清理...`);
         try { rmSync(worktreePath, { recursive: true, force: true }); } catch {}
+        // 同步清理 git worktree 注册 + 残留分支，否则目录虽删但 git 内部状态未清，
+        // 后续 git worktree add 会因「worktree 已注册」或「分支已存在」失败
+        try { gitQuiet(this.cwd, 'worktree prune'); } catch {}
+        try { gitQuiet(this.cwd, `branch -D ${branch}`); } catch {}
       } else {
         throw new Error(`worktree already exists: ${name}. Run cleanup first.`);
       }
@@ -269,7 +284,7 @@ export class WorktreeManager {
     } catch (e) {
       const check = isGitWorktreeSupported(this.cwd);
       if (!check.supported) {
-        throw new Error(`git worktree add 失败: ${e.stderr || e.message}\n\n${check.reason ? `原因: ${check.reason}` : ''}\n建议: 使用 --no-worktree 标志跳过隔离，或升级 git 到 >= 2.15`);
+        throw new Error(`git worktree add 失败: ${e.stderr || e.message}\n\n${check.reason ? `原因: ${check.reason}` : ''}\n建议: 升级 git 到 >= 2.15；或运行 \`sillyspec worktree doctor --fix\` 检查 worktree 状态。`);
       }
       // sandbox/permission fallback: 降级为 in-place + baseline protection
       console.log(`⚠️  git worktree add 失败（可能是沙箱权限限制），降级为 in-place 模式 + baseline protection`);
@@ -546,7 +561,10 @@ export class WorktreeManager {
    * 三重清理：git worktree 注册 + worktree 目录 + meta 目录。
    * @param {string} changeName
    * @param {{ force?: boolean, maxRetries?: number }} opts
-   * @returns {{ result: 'cleaned'|'force-cleaned'|'skipped'|'kept', mode: string|null, details: string[] }}
+   * @returns {{ result: 'cleaned'|'force-cleaned'|'skipped'|'kept'|'partial', mode: string|null, details: string[], residual: string[] }}
+   *   result 取值：cleaned=git remove 成功；force-cleaned=git remove 失败但 fallback 清理完成；
+   *   partial=有残留（目录/meta/git 注册未清）；skipped=无需清理；kept=native-worktree 保留。
+   *   residual：未清干净的路径/引用列表（空数组表示干净）。
    */
   cleanup(changeName, { force = false, maxRetries = 3 } = {}) {
     const name = validateChangeName(changeName);
@@ -561,22 +579,20 @@ export class WorktreeManager {
     }
 
     const mode = meta?.mode || 'worktree';
+    // in-place 模式：worktreePath === 主工作区，绝对禁止删除目录本身，但 meta 目录仍应清理
+    // （否则永久残留）。native-worktree：外部隔离环境，整体跳过。
+    const isInPlace = mode === 'in-place-fallback';
 
-    // 安全检查：只有 SillySpec 创建的 worktree 才允许删除
-    if (!force) {
-      if (mode === 'native-worktree') {
-        return { result: 'kept', mode, details: ['native-worktree: 外部隔离环境，跳过清理'] };
-      }
-      if (mode === 'in-place-fallback') {
-        return { result: 'skipped', mode, details: ['in-place-fallback: 无隔离目录，跳过清理'] };
-      }
+    // 安全检查：native-worktree 是外部隔离环境，非 force 不碰
+    if (!force && mode === 'native-worktree') {
+      return { result: 'kept', mode, details: ['native-worktree: 外部隔离环境，跳过清理'], residual: [] };
     }
 
     const branch = (meta && meta.branch) || BRANCH_PREFIX + name;
 
-    // 1. git worktree remove（带 retry）
+    // 1. git worktree remove（带 retry）—— in-place 跳过：无 git worktree 注册，且 worktreePath 即主工作区
     let gitRemoveOk = false;
-    if (existsSync(worktreePath)) {
+    if (!isInPlace && existsSync(worktreePath)) {
       for (let attempt = 1; attempt <= maxRetries; attempt++) {
         try {
           git(this.cwd, `worktree remove ${worktreePath} --force`);
@@ -586,15 +602,15 @@ export class WorktreeManager {
         } catch (e) {
           details.push(`git worktree remove attempt ${attempt}/${maxRetries} failed: ${e.message}`);
           if (attempt < maxRetries) {
-            // 短暂等待后重试
-            execSync('sleep 0.5', { stdio: 'pipe' });
+            // 短暂等待后重试（跨平台 busy-wait，见 sleepMs）
+            sleepMs(500);
           }
         }
       }
     }
 
-    // 2. fallback: 确保 worktree 目录已删除
-    if (existsSync(worktreePath)) {
+    // 2. fallback: 确保 worktree 目录已删除（in-place 跳过——worktreePath 是主工作区）
+    if (!isInPlace && existsSync(worktreePath)) {
       try {
         rmSync(worktreePath, { recursive: true, force: true });
         details.push('worktree directory force-removed (fallback)');
@@ -618,7 +634,7 @@ export class WorktreeManager {
       // 分支可能已被删除，幂等跳过
     }
 
-    // 5. 清除 meta 目录
+    // 5. 清除 meta 目录（in-place 模式也执行——这是 in-place meta 残留的修复点）
     if (existsSync(metaDir)) {
       try {
         rmSync(metaDir, { recursive: true, force: true });
@@ -628,18 +644,27 @@ export class WorktreeManager {
       }
     }
 
-    // 6. 最终验证：确认三重清理完成
+    // 6. 最终验证：确认清理完成（in-place 模式 worktreePath=主工作区，不纳入残留检查）
     const residual = [];
-    if (existsSync(worktreePath)) residual.push(`worktree dir: ${worktreePath}`);
+    if (!isInPlace && existsSync(worktreePath)) residual.push(`worktree dir: ${worktreePath}`);
     if (existsSync(metaDir)) residual.push(`meta dir: ${metaDir}`);
-    if (gitQuiet(this.cwd, `worktree list`)?.includes(worktreePath)) {
+    if (!isInPlace && gitQuiet(this.cwd, `worktree list`)?.includes(worktreePath)) {
       residual.push('git worktree list still references this worktree');
     }
     if (residual.length > 0) {
       details.push(`⚠️ 残留: ${residual.join('; ')}`);
     }
 
-    return { result: gitRemoveOk ? 'cleaned' : 'force-cleaned', mode, details };
+    // result：有残留→partial；in-place（无隔离目录可删，只清了 meta）→cleaned；否则按 git remove 成败
+    let result;
+    if (residual.length > 0) {
+      result = 'partial';
+    } else if (isInPlace) {
+      result = 'cleaned';
+    } else {
+      result = gitRemoveOk ? 'cleaned' : 'force-cleaned';
+    }
+    return { result, mode, details, residual };
   }
 
   /**
@@ -680,8 +705,10 @@ export class WorktreeManager {
       for (const entry of entries) {
         const lines = entry.split('\n');
         const wtPath = lines.find(l => l.startsWith('worktree '))?.replace('worktree ', '');
+        // git 2.20+ porcelain 在目录缺失时输出 `missing` 行；作为 existsSync 的权威交叉验证
+        const missing = lines.some(l => l === 'missing');
         if (wtPath && wtPath !== this.cwd) { // 排除主工作区
-          gitWorktreeList.push({ path: wtPath, raw: entry });
+          gitWorktreeList.push({ path: wtPath, missing, raw: entry });
         }
       }
     } catch {
@@ -693,12 +720,25 @@ export class WorktreeManager {
     const metaNames = new Set(metaEntries.map(m => m.changeName));
 
     // 3. 检查 git worktree list 中的孤儿条目
+    // ⚠️ 只在 git 自己标记 missing 时自动 prune。目录不可见但 git 未标记 missing 的
+    // 情况（平台模式/容器路径不一致、符号链接、Windows 路径格式、旧 git 无 missing 标记）
+    // 只告警不自动 prune —— existsSync 在这些场景会误判，自动 prune 会杀死实际在用的
+    // worktree（sillyspec-worktree-platform-mode-bug）。git 内部状态是 worktree 生命周期的
+    // 权威来源，用它做 prune 前提可杜绝误杀。
     for (const wt of gitWorktreeList) {
       if (!existsSync(wt.path)) {
         const name = this._pathToChangeName(wt.path);
-        issues.push({ type: 'orphan-git-entry', name: name || wt.path, detail: `git worktree 引用存在但目录不存在: ${wt.path}`, fixable: true });
-        if (fix) {
-          try { gitQuiet(this.cwd, 'worktree prune'); fixed.push(`pruned orphan: ${wt.path}`); } catch { unfixable.push(`prune failed for: ${wt.path}`); }
+        if (wt.missing === true) {
+          // git 明确标记目录缺失（git 2.20+）→ 真 orphan，prune 安全
+          issues.push({ type: 'orphan-git-entry', name: name || wt.path, detail: `git worktree 标记 missing: ${wt.path}`, fixable: true });
+          if (fix) {
+            try { gitQuiet(this.cwd, 'worktree prune'); fixed.push(`pruned orphan: ${wt.path}`); } catch { unfixable.push(`prune failed for: ${wt.path}`); }
+          }
+        } else {
+          // 目录不可见但 git 未标记 missing → 可能 existsSync 误判，保守不自动 prune
+          issues.push({ type: 'orphan-git-entry', name: name || wt.path,
+            detail: `git worktree 引用 ${wt.path} 目录不可见但 git 未标记 missing——可能路径/权限导致误判，未自动 prune（避免误杀在用的 worktree）。确认废弃后手动: git worktree prune`,
+            fixable: false });
         }
       }
     }
@@ -761,9 +801,10 @@ export class WorktreeManager {
         if (meta && meta.createdAt) {
           const ageMs = Date.now() - new Date(meta.createdAt).getTime();
           const ageHours = ageMs / (1000 * 60 * 60);
+          const staleFixable = meta.mode !== 'native-worktree';
           if (ageHours > staleHours) {
-            issues.push({ type: 'stale', name, detail: `worktree 已存在 ${Math.round(ageHours)} 小时（超过 ${staleHours}h 阈值）`, fixable: true });
-            if (fix && meta.mode !== 'native-worktree') {
+            issues.push({ type: 'stale', name, detail: `worktree 已存在 ${Math.round(ageHours)} 小时（超过 ${staleHours}h 阈值）${staleFixable ? '' : '（native-worktree 外部环境，不可自动清理）'}`, fixable: staleFixable });
+            if (fix && staleFixable) {
               try {
                 const result = this.cleanup(name);
                 if (result.result === 'cleaned' || result.result === 'force-cleaned') {

package/docs/brainstorm-plan-contract.md

@@ -1,64 +0,0 @@
----
-author: qinyi
-created_at: 2026-06-19 00:45:00
----
-
-# Brainstorm → Plan Contract
-
-## 核心契约
-
-`design.md` 是 plan 阶段的**主要设计输入**。plan 不应该在空的或缺少关键决策的 design.md 上生成任务。
-
-## design.md 结构要求
-
-### 必须包含（error — 阻断 plan）
-
-| # | 章节 | 匹配关键词 |
-|---|------|-----------|
-| 1 | 目标/背景/问题描述 | 目标、goal、objective、背景、background、问题、problem、purpose、目的 |
-| 2 | 范围/总体方案/设计 | 范围、scope、总体方案、方案、approach、solution、设计、design |
-| 3 | 决策/方案选择 | 决策、decision、选择、choice、方案选择、D-xxx@vN（decisions.md 引用） |
-
-### 建议包含（warning — 不阻断 plan）
-
-| # | 章节 | 匹配关键词 |
-|---|------|-----------|
-| 4 | 非目标/Non-goals | 非目标、non-goals、不做、out of scope |
-| 5 | 约束/风险/Trade-off | 约束、constraint、风险、risk、trade-off |
-| 6 | 文件变更清单 | 文件变更、变更清单、changed files |
-
-## 校验规则
-
-plan 启动时（第一个步骤执行前）调用 `validateDesignForPlan(designContent)`：
-
-| 结果 | 行为 |
-|------|------|
-| 全部通过 | 正常进入 plan |
-| 有 warning | 继续执行，展示警告 |
-| 有 error | fail-fast，提示修复 design.md |
-
-## 第一版设计原则
-
-- **轻量 markdown 契约**：检查标题和关键词，不强 schema
-- **关键词宽泛**：中英文都支持
-- **decisions.md 引用也算决策**：`D-xxx@vN` 或 `decisions.md` 引用即满足决策检查
-- **不做 brainstorm postcheck 阻断**：brainstorm 完成时不校验此契约（brainstorm 可以产出不完整的 design.md），只在 plan 启动时校验
-
-## 错误处理
-
-| 场景 | 行为 |
-|------|------|
-| design.md 不存在 | 不校验（向后兼容，plan 可以独立运行） |
-| design.md 空 | fail-fast |
-| 缺目标/背景 | fail-fast |
-| 缺范围/方案 | fail-fast |
-| 缺决策 | fail-fast |
-| 缺非目标/约束/文件清单 | warning，继续执行 |
-
-## 完整契约链
-
-```
-brainstorm → design.md → [Plan Contract 校验] → plan → plan.md → [Execute Contract 校验] → execute
-```
-
-每个阶段启动前都校验上游产物，形成双重保险。