sillyspec 3.20.6 → 3.21.0

package/src/run.js

@@ -1341,7 +1341,18 @@ export async function runCommand(args, cwd, specDir = null) {
     inputText = flags[inputIdx + 1]
   }
 
-  // 解析 --change <name>（quick 阶段支持逗号分隔多值，作为「关联变更」）
+  // 解析 --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')
@@ -1352,6 +1363,10 @@ export async function runCommand(args, cwd, specDir = null) {
       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 间漂移，
@@ -1376,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',
@@ -1400,13 +1415,28 @@ export async function runCommand(args, cwd, specDir = null) {
 
   const pm = new ProgressManager({ specDir: specRoot })
 
-  // quick 阶段：多变更交互式选择关联变更（--change 未指定时）
-  if (stageName === 'quick' && linkedChanges.length === 0) {
-    linkedChanges = await resolveQuickLinkedChanges({
-      pm, cwd, specDir: specRoot, quickFiles,
-      taskDescription: inputText || '',
-      nonInteractive: isNonInteractive,
-    })
+  // 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)
@@ -1607,7 +1637,7 @@ async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles, taskDes
   if (activeChanges.length === 0) return []
   if (activeChanges.length === 1) return [activeChanges[0]]
 
-  if (nonInteractive || process.stdin.isTTY === false) {
+  if (nonInteractive || !process.stdin.isTTY) {
     console.log('💡 非交互环境，已默认不关联变更；如需关联请用 --change a,b')
     return []
   }
@@ -1702,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)
       }
     }
@@ -2024,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)
@@ -2037,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 ──
@@ -2249,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} 个未应用变更)`);
@@ -2259,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) {
@@ -2375,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 推进
@@ -2462,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✅ 归档校验通过：核心文档齐全`)
       }
     }
   }
@@ -2936,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 等）`)
     }
@@ -2954,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} 校验警告：`)
@@ -2962,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)
@@ -3061,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}`);
               }
             }
           }
@@ -3333,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',

package/src/stage-contract.js

@@ -391,10 +391,11 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
     return { ok: false, errors, warnings }
   }
 
-  // verify 阶段应该产出 verify-result.md（或类似报告）
+  // verify 阶段必须产出 verify-result.md —— 不存在则不能完成。
+  // 历史教训：AI 可能跳过报告直接 --done，导致"假完成"。此处提级为 error 强制阻断。
   const verifyResult = join(changeDir, 'verify-result.md')
   if (!existsSync(verifyResult)) {
-    warnings.push('verify-result.md 不存在（verify 阶段建议产出验证报告）')
+    errors.push(`verify-result.md 不存在 — verify 阶段必须产出验证报告才能完成（${verifyResult}）`)
   }
 
   // 确保核心规范文件仍然存在
@@ -415,6 +416,17 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
     const decisionIds = extractCurrentDecisionIds(decisions)
     warnMissingIds(warnings, decisionIds, verify, 'verify-result.md', 'decisions.md')
 
+    // ── FAIL 结论门控（适用于所有变更，不限风险等级）──
+    // verify-result.md 结论为 FAIL 时，verify 阶段不能 completed。
+    // 历史教训：CLI 曾不校验结论，AI 写 FAIL 后 verify 仍被标记完成并提示"验证通过可以归档"。
+    const conclusionLine = verify.match(/^##\s*结论\s*\n\s*(PASS(?:\s+WITH\s+NOTES)?|FAIL)/im)
+    const conclusionStr = conclusionLine ? conclusionLine[1].toUpperCase().replace(/\s+/g, ' ') : ''
+    if (conclusionStr === 'FAIL') {
+      errors.push('verify-result.md 结论为 FAIL — 验证未通过，不能标记 verify 完成；请修复后重新运行验证')
+    } else if (!conclusionStr) {
+      warnings.push('verify-result.md 未识别到「## 结论」章节（应为 PASS / PASS WITH NOTES / FAIL）')
+    }
+
     // ── P0: Change Risk Gate — 核心功能缺少真实集成验证时 FAIL ──
     const changeRiskProfile = detectChangeRisk({
       designContent: readIfExists(join(changeDir, 'design.md')),

package/src/stages/execute.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'fs'
 import path from 'path'
+import { buildContractMatrix, buildConsumerInjection, buildContractFieldInjection } from '../contract-matrix.js'
 
 /**
  * 校验 plan.md 是否满足 execute 执行契约
@@ -430,42 +431,60 @@ function buildWavePrompt(wave, waveIndex, changeDir, worktreePath) {
   let contractInjection = ''
   if (changeDir) {
     try {
-      const { buildContractMatrix, buildConsumerInjection } = require('../contract-matrix.js')
       const planFile = path.join(changeDir, 'plan.md')
       if (existsSync(planFile)) {
         const planContent = readFileSync(planFile, 'utf8')
+        // 收集本 wave 所有 task（端点注入与字段注入共用）
+        const waveTasks = wave.tasks.map((t, ti) => {
+          const num = String(t.index || (ti + 1)).padStart(2, '0')
+          return `task-${num}`
+        })
+
+        // 1) 端点级契约（provider/consumer via buildContractMatrix）
         const contracts = buildContractMatrix(planContent, changeDir)
-        if (contracts.length > 0) {
-          // 收集本 wave 所有 task 的注入内容
-          const waveTasks = wave.tasks.map((t, ti) => {
-            const num = String(t.index || (ti + 1)).padStart(2, '0')
-            return `task-${num}`
-          })
-          const relevantContracts = contracts.filter(c => waveTasks.includes(c.consumer))
-          if (relevantContracts.length > 0) {
-            contractInjection = `
+        const relevantContracts = contracts.filter(c => waveTasks.includes(c.consumer))
+        if (relevantContracts.length > 0) {
+          contractInjection = `
 ### API Contract Matrix
 本 Wave 存在前端/后端跨 task 契约：
 ${relevantContracts.map(c => `- **${c.consumer}** 消费 **${c.provider}** 产出的 API`).join('\n')}
 `
-            // 为每个 consumer task 生成详细注入
-            for (const taskName of waveTasks) {
-              const injection = buildConsumerInjection(changeDir, join(changeDir, '..', '..'), taskName, contracts)
-              if (injection) {
-                contractInjection += `
-### 子代理 ${taskName} 的契约注入
+          for (const taskName of waveTasks) {
+            const injection = buildConsumerInjection(changeDir, path.join(changeDir, '..', '..'), taskName, contracts)
+            if (injection) {
+              contractInjection += `
+### 子代理 ${taskName} 的端点契约注入
 为 ${taskName} 启动子代理时，在子代理 prompt 末尾追加以下内容：
 
 <contract-injection>
 ${injection}
 </contract-injection>
 `
-              }
             }
           }
         }
+
+        // 2) 字段级契约（expects_from ↔ provides）
+        // 命中「provider 漏字段、consumer fallback 编造 → 运行时 403/500」这类 bug：
+        // 把 consumer 期望字段 vs provider 承诺字段显式注入子代理 prompt
+        for (const taskName of waveTasks) {
+          const fi = buildContractFieldInjection(changeDir, taskName)
+          if (fi) {
+            contractInjection += `
+### 子代理 ${taskName} 的字段契约注入
+为 ${taskName} 启动子代理时，在子代理 prompt 末尾追加以下内容：
+
+<contract-field-injection>
+${fi}
+</contract-field-injection>
+`
+          }
+        }
       }
-    } catch {}
+    } catch (e) {
+      // 契约注入是 best-effort：失败不阻断 execute，只记录
+      console.warn(`  ⚠️ 契约注入跳过: ${e?.message || e}`)
+    }
   }
 
   // 构建任务摘要（不再内联完整蓝图，减少上下文污染）