sillyspec 3.20.5 → 3.20.7

package/src/quick-recommend.js

@@ -0,0 +1,115 @@
+/**
+ * quick-recommend.js — quick 阶段多变更关联推荐打分
+ *
+ * 多变更场景下，quick 启动前用「脏文件 + 任务描述」双信号，
+ * 推测当前 quick 改动最可能归属哪些活跃变更，供交互式多选默认勾选。
+ *
+ * 纯函数 + 只读文件系统，无副作用，便于单测。
+ */
+import { join } from 'path'
+import { existsSync, readFileSync } from 'fs'
+import { parseFileChangeList } from './change-list.js'
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * 单个 token 是否命中上下文（参考 knowledge-match.js 的 keywordMatchesContext 思路）。
+ * - 过短（<2 字符）视为噪音
+ * - 非 ASCII（中文等）用子串匹配
+ * - ASCII 用词边界匹配，避免 "DB" 误命中 "dashboard"
+ */
+function tokenInContext(token, contextLower) {
+  const t = token.toLowerCase().trim()
+  if (t.length < 2) return false
+  if (/[^\x00-\x7f]/.test(t)) {
+    // 中文（等非 ASCII）：用 2-gram 重叠匹配。
+    // 避免整串子串匹配漏召回（如 token「修解析器」与 context「修复解析器」整串不等，
+    // 但共享 2-gram「解析」）。2-gram 足以抑制单字噪音，又能覆盖词形变化。
+    for (let i = 0; i <= t.length - 2; i++) {
+      if (contextLower.includes(t.slice(i, i + 2))) return true
+    }
+    return false
+  }
+  return new RegExp(`(^|[^a-z0-9])${escapeRegex(t)}([^a-z0-9]|$)`).test(contextLower)
+}
+
+/**
+ * 把任务描述切成用于匹配的 token（按空白/标点切分，过滤空串）。
+ * 保留中英文混排，不做分词——推荐只求召回，精确度靠用户最终勾选把关。
+ */
+function tokenizeDescription(desc) {
+  if (!desc) return []
+  return desc
+    .split(/[\s,，。、;；:：()（）\[\]{}"'`/\\|]+/)
+    .map(t => t.trim())
+    .filter(Boolean)
+}
+
+/** 读取变更 proposal.md 的全文（小写），用于任务描述信号匹配；缺失返回空串。 */
+function readProposalContext(specDir, changeName) {
+  const p = join(specDir, 'changes', changeName, 'proposal.md')
+  if (!existsSync(p)) return ''
+  try {
+    return readFileSync(p, 'utf8').toLowerCase()
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * 判断单个脏文件是否命中 design.md 声明的文件清单。
+ * 支持精确匹配 + 目录前缀匹配（design 可能写目录、脏文件是目录下文件，或反之）。
+ */
+function fileHitsList(dirtyFile, fileList) {
+  if (fileList.has(dirtyFile)) return true
+  for (const declared of fileList) {
+    if (declared === dirtyFile) continue
+    if (dirtyFile.startsWith(declared + '/') || declared.startsWith(dirtyFile + '/')) return true
+  }
+  return false
+}
+
+/**
+ * 推荐关联变更。
+ * @param {{ activeChanges: string[], specDir: string, baselineFiles?: string[], quickFiles?: string[], taskDescription?: string }} opts
+ * @returns {{ name: string, score: number, reasons: string[] }[]} 按 score 降序、同名升序
+ */
+export function recommendChanges({
+  activeChanges,
+  specDir,
+  baselineFiles = [],
+  quickFiles = [],
+  taskDescription = '',
+}) {
+  if (!activeChanges || activeChanges.length === 0) return []
+
+  const dirtyFiles = [...new Set([...baselineFiles, ...quickFiles])]
+    .filter(f => f && !f.startsWith('.sillyspec/'))
+  const descTokens = [...new Set(tokenizeDescription(taskDescription))]
+
+  const results = activeChanges.map(name => {
+    const reasons = []
+
+    // 信号 1：脏文件命中 design.md 文件变更清单
+    const fileList = parseFileChangeList(join(specDir, 'changes', name, 'design.md'))
+    if (fileList.size > 0 && dirtyFiles.length > 0) {
+      for (const f of dirtyFiles) {
+        if (fileHitsList(f, fileList)) reasons.push(`脏文件命中: ${f}`)
+      }
+    }
+
+    // 信号 2：任务描述 token 命中 proposal.md
+    const proposalCtx = readProposalContext(specDir, name)
+    if (proposalCtx && descTokens.length > 0) {
+      for (const t of descTokens) {
+        if (tokenInContext(t, proposalCtx)) reasons.push(`任务描述命中: ${t}`)
+      }
+    }
+
+    return { name, score: reasons.length, reasons }
+  })
+
+  return results.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+}

package/src/run.js

@@ -10,6 +10,7 @@ import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
 import { ProgressManager } from './progress.js'
 import { SCAN_STATUS, POINTER_STATUS, isPointerCorrupted } from './constants.js'
+import { checkbox } from '@inquirer/prompts'
 
 /**
  * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
@@ -703,6 +704,20 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   if (changeName && promptText.includes('<change-name>')) {
     promptText = promptText.replace(/<change-name>/g, changeName)
   }
+  // 替换 <linked-changes> 占位符（quick 阶段：从 .runtime/quick-guard.json 读关联变更）
+  if (promptText.includes('<linked-changes>')) {
+    const specBaseLc = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    let linkedChanges = []
+    try {
+      const guardFile = join(specBaseLc, '.runtime', 'quick-guard.json')
+      if (existsSync(guardFile)) {
+        const guard = JSON.parse(readFileSync(guardFile, 'utf8'))
+        linkedChanges = Array.isArray(guard.linkedChanges) ? guard.linkedChanges : []
+      }
+    } catch {}
+    const display = linkedChanges.length > 0 ? linkedChanges.join(', ') : '（无）'
+    promptText = promptText.replace(/<linked-changes>/g, display)
+  }
   // 平台模式：注入路径覆盖指令
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) {
     const projectName = dbProjectName || basename(cwd)
@@ -1276,30 +1291,39 @@ export async function runCommand(args, cwd, specDir = null) {
   // runCommand 后续所有 .sillyspec/ 操作必须用 specBase
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
 
-  // 平台模式：清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
+  // 平台模式：首次接入时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
   // ⚠️ 同 init.js：必须保护真实资产（changes/、projects/、sillyspec.db）。
+  // 只在「首次」执行一次——用 cwd 下的 .sillyspec-platform-cleaned 标记文件记录已处理，
+  // 后续每次 run 直接跳过，避免重复检查 + 红叉噪声（此清理不阻塞流程、不动真实资产）。
   if (platformOpts.specRoot) {
     const legacyDir = join(cwd, '.sillyspec')
-    if (existsSync(legacyDir)) {
-      let hasChanges = false;
-      try {
-        const cd = join(legacyDir, 'changes');
-        if (existsSync(cd)) hasChanges = readdirSync(cd).length > 0;
-      } catch {}
-      let hasProjects = false;
-      try {
-        const pd = join(legacyDir, 'projects');
-        if (existsSync(pd)) hasProjects = readdirSync(pd).length > 0;
-      } catch {}
-      const hasDb = existsSync(join(legacyDir, 'sillyspec.db'));
-
-      if (hasChanges || hasProjects || hasDb) {
-        console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产。仅清理运行时残留，保留 worktrees 与进度状态。');
-        const { cleanupRuntimeResidue } = await import('./init.js')
-        cleanupRuntimeResidue(legacyDir);
-      } else {
-        try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+    const cleanedMarker = join(cwd, '.sillyspec-platform-cleaned')
+    if (!existsSync(cleanedMarker)) {
+      if (existsSync(legacyDir)) {
+        let hasChanges = false;
+        try {
+          const cd = join(legacyDir, 'changes');
+          if (existsSync(cd)) hasChanges = readdirSync(cd).length > 0;
+        } catch {}
+        let hasProjects = false;
+        try {
+          const pd = join(legacyDir, 'projects');
+          if (existsSync(pd)) hasProjects = readdirSync(pd).length > 0;
+        } catch {}
+        const hasDb = existsSync(join(legacyDir, 'sillyspec.db'));
+
+        if (hasChanges || hasProjects || hasDb) {
+          // 真实资产存在：只清运行时残留（白名单保留 worktrees/进度），不整删
+          const { cleanupRuntimeResidue } = await import('./init.js')
+          cleanupRuntimeResidue(legacyDir);
+          console.log('ℹ️  [sillyspec] 源码目录 .sillyspec/ 含真实资产，已跳过整删，仅清理运行时残留（仅本次首次，后续不再提示）。');
+        } else {
+          try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+          if (!existsSync(legacyDir)) console.log('🧹 已清理旧版本残留的源码 .sillyspec/ 目录');
+        }
       }
+      // 标记本 cwd 已做平台残留清理决策，后续 run 跳过（即使之后 .sillyspec/ 被重建也不误清）
+      try { writeFileSync(cleanedMarker, new Date().toISOString() + '\n') } catch {}
     }
   }
 
@@ -1317,11 +1341,38 @@ export async function runCommand(args, cwd, specDir = null) {
     inputText = flags[inputIdx + 1]
   }
 
-  // 解析 --change <name>
+  // 解析 --linked-changes <a,b|none>（quick 专用：显式声明关联变更，CI/脚本友好）
+  // 与 --change 解耦：--linked-changes 语义清晰（关联变更），不与「指定变更名」混淆。
+  // null = 未指定（走持久化/交互/兼容回退）；[] = 显式 none（不关联）；[...] = 显式列表
+  let explicitLinked = null
+  const linkedIdx = flags.indexOf('--linked-changes')
+  if (linkedIdx !== -1 && flags[linkedIdx + 1]) {
+    const v = flags[linkedIdx + 1].trim()
+    explicitLinked = v.toLowerCase() === 'none' ? [] : v.split(',').map(s => s.trim()).filter(Boolean)
+  }
+
+  // 解析 --change <name>（quick 阶段向后兼容：逗号分隔作为「关联变更」；
+  // 历史写法，语义与「指定变更名」冲突，新用法建议改用 --linked-changes）
   let changeName = null
+  let linkedChanges = []
   const changeIdx = flags.indexOf('--change')
   if (changeIdx !== -1 && flags[changeIdx + 1]) {
     changeName = flags[changeIdx + 1]
+    if (stageName === 'quick') {
+      linkedChanges = changeName.split(',').map(s => s.trim()).filter(Boolean)
+      changeName = null
+    }
+  }
+  // --linked-changes 优先于 --change（显式 > 隐式兼容）
+  if (explicitLinked !== null) {
+    linkedChanges = explicitLinked
+  }
+  // quick 的 progress 键固定走 'default'：归属语义已由 linkedChanges 承担（→ quick-guard.json
+  // → <linked-changes> 占位符注入 prompt）。progress 不能走 pm.read(cwd, null) 的自动检测——
+  // 多活跃 change 项目里 quick 步骤进度会随活跃 change 增减在各 change/default 间漂移，
+  // 表现为 --done 时「回退」到更早步骤。固定 default 后无论是否带 --change 都稳定。
+  if (stageName === 'quick') {
+    changeName = 'default'
   }
 
   // 解析 --files a.js,b.js（quick 专用：显式声明 allowedFiles）
@@ -1340,7 +1391,7 @@ export async function runCommand(args, cwd, specDir = null) {
     '--done', '--skip', '--status', '--reset', '--confirm', '--skip-approval',
     '--wait', '--continue', '--non-interactive', '--interactive',
     '--reason', '--options', '--answer', '--confirm-mode',
-    '--output', '--input', '--change',
+    '--output', '--input', '--change', '--linked-changes',
     '--spec-dir', '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
     '--files', '--allow-new', '--force-baseline', '--force-rescan',
     '--json', '--dir', '--help',
@@ -1363,6 +1414,31 @@ export async function runCommand(args, cwd, specDir = null) {
   // scan 元数据追踪（存储在 stageData.scanMeta 中，completeStep 通过 progress 访问）
 
   const pm = new ProgressManager({ specDir: specRoot })
+
+  // quick 阶段：确定关联变更
+  // 优先级：--linked-changes / --change 显式 > 已持久化 quick-guard.json（--done 复用）> 交互式 > 非交互 fallback
+  // 关键：--done 收尾时复用首次 run 持久化的 linkedChanges，不在管道/CI 下重复弹交互 prompt。
+  // explicitLinked === null 且未传 --change 时才进入此分支（显式 --linked-changes none 不应触发交互）。
+  if (stageName === 'quick' && explicitLinked === null && linkedChanges.length === 0) {
+    const guardFile = join(specRoot, '.runtime', 'quick-guard.json')
+    let persistedLinked = null
+    try {
+      if (existsSync(guardFile)) {
+        const g = JSON.parse(readFileSync(guardFile, 'utf8'))
+        if (Array.isArray(g.linkedChanges)) persistedLinked = g.linkedChanges
+      }
+    } catch {}
+    if (persistedLinked) {
+      linkedChanges = persistedLinked
+    } else {
+      linkedChanges = await resolveQuickLinkedChanges({
+        pm, cwd, specDir: specRoot, quickFiles,
+        taskDescription: inputText || '',
+        nonInteractive: isNonInteractive,
+      })
+    }
+  }
+
   let progress = await pm.read(cwd, changeName)
 
   if (!progress) {
@@ -1382,6 +1458,12 @@ export async function runCommand(args, cwd, specDir = null) {
     } else {
       // brainstorm 作为流程入口，自动生成变更名并初始化
       if (stageName === 'brainstorm') {
+        if (isDone) {
+          console.error('❌ --done 找不到变更进度数据。')
+          console.error('   请用 --change <变更名> 指定要完成的变更，')
+          console.error('   或先运行 sillyspec run brainstorm --change <变更名> 初始化。')
+          process.exit(1)
+        }
         const date = new Date().toISOString().slice(0, 10)
         const autoName = `${date}-new-change`
         console.log(`🔄 自动创建变更：${autoName}`)
@@ -1523,7 +1605,7 @@ export async function runCommand(args, cwd, specDir = null) {
   }
 
   // 默认：输出当前步骤
-  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isForceBaseline, isForceRescan })
+  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isForceBaseline, isForceRescan, linkedChanges })
 }
 
 /**
@@ -1538,6 +1620,73 @@ function resolveChangeNameAuto(cwd, specDir = null) {
   return null
 }
 
+/**
+ * quick 阶段多变更交互式选择关联变更。
+ * - 0 活跃变更 → []（仅记 QUICKLOG，不关联）
+ * - 1 活跃变更 → 默认关联它（保持现状友好，不弹交互）
+ * - ≥2 活跃变更 + 交互 → checkbox 多选（推荐项默认勾，空选 = 不关联）
+ * - ≥2 活跃变更 + 非交互 → []（不关联）+ 提示用 --change a,b
+ */
+async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles, taskDescription, nonInteractive }) {
+  let activeChanges = []
+  try {
+    activeChanges = await pm.listChanges(cwd)
+  } catch {
+    activeChanges = []
+  }
+  if (activeChanges.length === 0) return []
+  if (activeChanges.length === 1) return [activeChanges[0]]
+
+  if (nonInteractive || !process.stdin.isTTY) {
+    console.log('💡 非交互环境，已默认不关联变更；如需关联请用 --change a,b')
+    return []
+  }
+
+  // 脏文件（推荐信号之一）
+  let baselineFiles = []
+  try {
+    const { execSync } = await import('child_process')
+    const gs = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
+    baselineFiles = gs.trim().split('\n').filter(Boolean)
+      .map(l => l.slice(3).trim())
+      .filter(f => !f.startsWith('.sillyspec/'))
+  } catch {}
+
+  // 推荐打分（脏文件 + 任务描述双信号）
+  let recommendations = []
+  try {
+    const { recommendChanges } = await import('./quick-recommend.js')
+    recommendations = recommendChanges({ activeChanges, specDir, baselineFiles, quickFiles, taskDescription })
+  } catch {
+    recommendations = activeChanges.map(name => ({ name, score: 0, reasons: [] }))
+  }
+  const scoreMap = new Map(recommendations.map(r => [r.name, r.score]))
+  const reasonMap = new Map(recommendations.map(r => [r.name, r.reasons]))
+  const recommendedSet = new Set(recommendations.filter(r => r.score > 0).map(r => r.name))
+
+  // 按推荐分降序展示
+  const ordered = [...activeChanges].sort((a, b) =>
+    (scoreMap.get(b) || 0) - (scoreMap.get(a) || 0) || a.localeCompare(b))
+
+  const choices = ordered.map(name => {
+    const reasons = reasonMap.get(name) || []
+    const isRec = recommendedSet.has(name)
+    return {
+      name: `${isRec ? '⭐ ' : '   '}${name}`,
+      value: name,
+      description: reasons.length > 0 ? reasons.join('；') : '无推荐信号',
+      checked: isRec,
+    }
+  })
+
+  console.log('🔗 检测到多个活跃变更，选择本次 quick 关联哪些（可多选；不勾选任何项 = 仅记 QUICKLOG，不关联变更）')
+  if (recommendedSet.size > 0) {
+    console.log('   ⭐ = 基于脏文件/任务描述推荐，已默认勾选')
+  }
+  const selected = await checkbox({ message: '关联变更（空格切换，回车确认）', choices })
+  return selected
+}
+
 async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}, quickOpts = {}) {
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
   // 状态转换校验
@@ -1583,7 +1732,10 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
         console.log(`🔗 worktree 已创建: ${result.worktreePath} (分支: ${result.branch}, 模式: ${result.mode})`)
       } catch (e) {
         console.error(`❌ worktree 创建失败: ${e.message}`)
-        console.error(`   继续执行前请解决上述问题，或使用 --no-worktree 跳过。`)
+        console.error(`   修复建议：`)
+        console.error(`   1. 运行 sillyspec worktree doctor --fix 检查并修复 worktree 状态`)
+        console.error(`   2. 或手动清理残留：git worktree prune && git branch -D sillyspec/${effectiveChange}`)
+        console.error(`   3. 必要时删除残留目录 .sillyspec/.runtime/worktrees/${effectiveChange}/ 后重试`)
         process.exit(1)
       }
     }
@@ -1730,6 +1882,7 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
         allowedFiles,
         allowNew,
         forceBaseline,
+        linkedChanges: Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : [],
         startedAt: new Date().toISOString(),
       }
       // 写入 quick-guard.json 供 worktree-guard hook 读取
@@ -1904,6 +2057,13 @@ async function archiveChangeDirectory(pm, cwd, progress, specBase) {
     console.error(`❌ 归档失败：源目录不存在 ${srcDir}`)
     process.exit(1)
   }
+  // 移动前硬校验：变更包必须含 plan.md，否则不该归档。
+  // 在移动前阻断（而非移动后），目录尚未动，用户可直接修复后重试。
+  if (!existsSync(join(srcDir, 'plan.md'))) {
+    console.error(`❌ 归档失败：变更目录缺少 plan.md（${srcDir}）`)
+    console.error(`   plan.md 是归档的必需产物。请先补全 plan 阶段产出再归档。`)
+    process.exit(1)
+  }
   if (existsSync(destDir)) {
     console.error(`❌ 归档失败：目标目录已存在 ${destDir}`)
     process.exit(1)
@@ -1917,7 +2077,32 @@ async function archiveChangeDirectory(pm, cwd, progress, specBase) {
   }
 
   await pm.unregisterChange(cwd, archiveChangeName)
+
+  // 归档时清理可能残留的 worktree（execute 自动清理未走到 / 有未 apply 变更被遗弃）。
+  // 安全策略：有未 apply 变更时保留 worktree 并警告，避免误删用户未应用的代码。
+  try {
+    const { WorktreeManager } = await import('./worktree.js')
+    const wm = new WorktreeManager({ cwd })
+    const meta = wm.getMeta(archiveChangeName)
+    if (meta) {
+      const check = meta.mode !== 'in-place-fallback' ? wm.hasUnappliedChanges(archiveChangeName) : { hasChanges: false }
+      if (check.hasChanges) {
+        console.warn(`⚠️  归档时 worktree 仍有 ${check.changedFiles.length} 个未 apply 变更，保留 worktree`)
+        console.warn(`   确认不需要后手动清理: sillyspec worktree cleanup ${archiveChangeName} --force`)
+      } else {
+        const cleanResult = wm.cleanup(archiveChangeName)
+        if (cleanResult.residual?.length > 0) {
+          console.warn(`⚠️  归档 worktree 清理残留: ${cleanResult.residual.join('; ')}`)
+          console.warn(`   手动处理: sillyspec worktree cleanup ${archiveChangeName} --force`)
+        }
+      }
+    }
+  } catch (e) {
+    console.warn(`⚠️  归档 worktree 清理失败（不阻断归档）: ${e.message}`)
+  }
+
   console.log(`📦 已归档：${archiveChangeName} → archive/${date}-${archiveChangeName}/`)
+  return destDir
 }
 
 // ── Wait Step ──
@@ -2129,9 +2314,8 @@ async function continueStep(pm, progress, stageName, cwd, answer, options = {})
           console.log('🔗 Worktree: n/a (no meta)');
         } else if (meta.mode === 'native-worktree') {
           console.log('🔗 Worktree: kept (外部隔离环境)');
-        } else if (meta.mode === 'in-place-fallback') {
-          console.log('🔗 Worktree: n/a (in-place 模式)');
         } else {
+          // in-place 模式不再短路：cleanup 现在能安全处理 in-place（只清 meta，不碰主工作区）
           const check = wm.hasUnappliedChanges(changeName);
           if (check.hasChanges) {
             console.log(`🔗 Worktree: pending apply (${check.changedFiles.length} 个未应用变更)`);
@@ -2139,6 +2323,10 @@ async function continueStep(pm, progress, stageName, cwd, answer, options = {})
           } else {
             const cleanResult = wm.cleanup(changeName);
             console.log(`🔗 Worktree: ${cleanResult.result}`);
+            if (cleanResult.residual?.length > 0) {
+              console.warn(`   ⚠️ 清理残留: ${cleanResult.residual.join('; ')}`);
+              console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`);
+            }
           }
         }
       } catch (e) {
@@ -2255,6 +2443,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
   const stageData = progress.stages[stageName]
   const scanProfile = stageData?.scanProfile || null
+  let archivedDir = null // archive step「确认归档」实际归档目录（archiveChangeDirectory 返回）
 
   // ── WAIT MARKER 硬校验 ──
   // 如果 output 包含等待标记，拒绝 --done 推进
@@ -2342,23 +2531,22 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
       return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
     }
-    await archiveChangeDirectory(pm, cwd, progress, specBase)
+    archivedDir = await archiveChangeDirectory(pm, cwd, progress, specBase)
   }
 
   // archive "确认归档" 步骤完成后，校验归档完整性
   if (stageName === 'archive' && steps[currentIdx]?.name === '确认归档' && confirm) {
-    const projectName = progress.project || basename(cwd)
-    const contractResult = runValidators('archive', cwd, changeName, { projectName, specRoot: platformOpts?.specRoot })
-    if (contractResult.errors.length > 0) {
-      console.error(`\n❌ 归档校验失败：`)
-      for (const err of contractResult.errors) {
-        console.error(`   - ${err}`)
-      }
-    }
-    if (contractResult.warnings.length > 0) {
-      console.warn(`\n⚠️ 归档校验警告：`)
-      for (const w of contractResult.warnings) {
-        console.warn(`   - ${w}`)
+    // contracts.archive.validators 为空数组（两个 validator 生效窗口互斥，注册为阶段级会误报），
+    // 故 runValidators('archive') 是空跑。这里直接对实际归档目录做内容完整性校验。
+    // plan.md 已在 archiveChangeDirectory 移动前硬校验阻断，此处只查推荐文档。
+    if (archivedDir && existsSync(archivedDir)) {
+      const recommendedDocs = ['design.md', 'module-impact.md']
+      const missingRecommended = recommendedDocs.filter(d => !existsSync(join(archivedDir, d)))
+      if (missingRecommended.length > 0) {
+        console.warn(`\n⚠️ 归档校验警告：归档目录缺少推荐文档`)
+        for (const d of missingRecommended) console.warn(`   - ${d}（${archivedDir}）`)
+      } else {
+        console.log(`\n✅ 归档校验通过：核心文档齐全`)
       }
     }
   }
@@ -2816,10 +3004,11 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         // summary 失败不影响主流程
         console.log('\n👉 下一步：sillyspec run verify（验证通过后才能归档）')
       }
-    } else if (stageName === 'verify') {
-      console.log('\n👉 下一步：sillyspec run archive（验证通过，可以归档了）')
     } else if (stageName === 'archive') {
       console.log('\n👉 归档完成！现在可以提交了：git commit -m "..."')
+    } else if (stageName === 'verify') {
+      // verify 的"验证通过"提示延后到下方 validator 通过后才打印，
+      // 避免校验失败（FAIL / 缺 verify-result.md）时仍声称"验证通过可以归档"。
     } else {
       console.log(`\n下一步由你决定：sillyspec run <stage>（brainstorm/plan/execute/verify/archive 等）`)
     }
@@ -2834,6 +3023,13 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
           console.error(`   - ${err}`)
         }
         console.error(`\n   提示：修复缺失产物后重新运行此步骤，或使用 --skip-approval 跳过校验`)
+        // 产物校验失败必须阻断完成 —— 否则 validator 形同虚设，
+        // verify 会带着 FAIL/缺 verify-result.md 被 ✅ 标记完成（历史教训）。
+        // plan/execute 的专项契约校验（下方）在产物齐全后才需要继续跑，故此处先 return。
+        progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
+        await pm._write(cwd, progress, changeName)
+        triggerSync(cwd, changeName, platformOpts)
+        return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
       }
       if (contractResult.warnings.length > 0) {
         console.warn(`\n⚠️ 阶段 ${stageName} 校验警告：`)
@@ -2842,6 +3038,11 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         }
       }
 
+      // verify 产物校验通过 + 结论非 FAIL（否则上面已阻断），此时才能声称"验证通过"
+      if (stageName === 'verify') {
+        console.log('\n✅ 验证通过，下一步：sillyspec run archive')
+      }
+
       // ── Plan postcheck contract：plan.md 必须满足 execute 契约 ──
       if (stageName === 'plan') {
         const planFile = resolveChangeDir(cwd, progress, platformOpts?.specRoot)
@@ -2941,23 +3142,21 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
           console.log('🔗 Worktree: n/a (no meta)');
         } else if (meta.mode === 'native-worktree') {
           console.log('🔗 Worktree: kept (外部隔离环境)');
-        } else if (meta.mode === 'in-place-fallback') {
-          console.log('🔗 Worktree: n/a (in-place 模式)');
         } else {
+          // in-place 模式不再短路：cleanup 现在能安全处理 in-place（只清 meta，不碰主工作区）
           const check = wm.hasUnappliedChanges(changeName);
           if (check.hasChanges) {
             console.log(`🔗 Worktree: pending apply (${check.changedFiles.length} 个未应用变更)`);
             console.log(`   下一步: sillyspec worktree apply ${changeName}`);
           } else {
             const cleanResult = wm.cleanup(changeName);
-            if (cleanResult.result === 'skipped' || cleanResult.result === 'kept') {
-              console.log(`🔗 Worktree: ${cleanResult.result}`);
-            } else {
-              console.log(`🔗 Worktree: ${cleanResult.result}`);
-              if (cleanResult.details?.length > 0) {
-                for (const d of cleanResult.details) {
-                  if (d.startsWith('⚠️')) console.log(`   ${d}`);
-                }
+            console.log(`🔗 Worktree: ${cleanResult.result}`);
+            if (cleanResult.residual?.length > 0) {
+              console.warn(`   ⚠️ 清理残留: ${cleanResult.residual.join('; ')}`);
+              console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`);
+            } else if (cleanResult.details?.length > 0) {
+              for (const d of cleanResult.details) {
+                if (d.startsWith('⚠️')) console.log(`   ${d}`);
               }
             }
           }
@@ -3213,6 +3412,28 @@ function showStatus(progress, stageName) {
 }
 
 async function resetStage(pm, progress, stageName, cwd, changeName, platformOpts = {}) {
+  // execute 阶段 reset 时清理自建 worktree，否则下次 run execute 会因 existingMeta 存在
+  // 直接复用带脏状态的旧 worktree（启动逻辑：meta 存在即复用，不查健康状态）
+  if (stageName === 'execute' && changeName) {
+    try {
+      const { WorktreeManager } = await import('./worktree.js')
+      const wm = new WorktreeManager({ cwd })
+      const meta = wm.getMeta(changeName)
+      if (meta) {
+        const cleanResult = wm.cleanup(changeName)
+        if (cleanResult.residual?.length > 0) {
+          console.warn(`⚠️  reset 清理 worktree 残留: ${cleanResult.residual.join('; ')}`)
+          console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`)
+        } else if (cleanResult.result === 'kept') {
+          console.log(`🔗 旧 worktree 保留 (${cleanResult.mode}: 外部隔离环境)`)
+        } else if (cleanResult.result !== 'skipped') {
+          console.log(`🧹 已清理旧 worktree (${cleanResult.result}, mode: ${cleanResult.mode})，下次 execute 将重建干净环境`)
+        }
+      }
+    } catch (e) {
+      console.warn(`⚠️  reset 清理 worktree 失败（不阻断 reset）: ${e.message}`)
+    }
+  }
   const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
   progress.stages[stageName] = {
     status: 'in-progress',