sillyspec 3.18.1 → 3.18.2

package/.claude/skills/sillyspec-brainstorm/SKILL.md

@@ -3,41 +3,42 @@ name: sillyspec:brainstorm
 description: 用于正式开始开发前的需求澄清和技术方案设计。适合用户提出新功能、新模块、架构调整、复杂改造，或说"先做需求分析、输出技术方案、创建变更前先梳理、帮我设计下"。产出结构化方案，但不直接写代码。
 ---
 
-# SillySpec Brainstorm — 需求探索
+## 多变更说明
 
-## 用法
-用户触发此 skill 时，使用 `sillyspec run brainstorm` 逐步执行需求探索。
+如果项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录），所有 `sillyspec run` 命令需要加 `--change <变更名>`。只有一个变更时可省略（CLI 自动检测）。
 
-## 执行步骤
+## 执行
 
-1. 确定变更名（格式：`YYYY-MM-DD-<简短描述>`，如 `2026-05-28-agent-log-streaming`）
-2. 运行 `sillyspec run brainstorm --change <变更名>` 获取当前步骤指令
-3. 按步骤指令执行（对话、分析需求、设计方案等）
-4. 完成步骤后运行 `sillyspec run brainstorm --done --change <变更名> --output "步骤摘要"`
-5. CLI 会自动输出下一步的指令，重复 3-4 直到阶段完成
+**你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
 
-## 示例
+1. 运行 `sillyspec run brainstorm` — 读取输出的步骤 prompt
+2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
+3. 步骤完成后，运行 `sillyspec run brainstorm --done --output "你的摘要"`
+4. 重复 2-3 直到阶段完成
+5. **禁止**在没有运行 CLI 的情况下自行决定流程
 
-```bash
-# 首次启动（推荐指定变更名）
-sillyspec run brainstorm --change 2026-05-28-agent-log-streaming
+## 特殊步骤：requiresWait
 
-# 不指定变更名时自动生成（格式：YYYY-MM-DD-new-change）
-sillyspec run brainstorm
+某些步骤（如"对话式探索"）需要等待用户输入。AI agent 可以：
 
-# 完成当前步骤
-sillyspec run brainstorm --done --change 2026-05-28-agent-log-streaming --output "需求已澄清"
+- **方式一（推荐）**：通过自己的对话工具与用户交互，完成后直接 `--done --answer "用户回答"` 一步完成
+- **方式二**：先 `--wait` 记录等待状态，再 `--continue --answer "用户回答"`，最后 `--done`
 
-# 查看进度
-sillyspec run brainstorm --status --change 2026-05-28-agent-log-streaming
+```bash
+# 一步完成 wait + done（AI agent 已自行与用户交互）
+sillyspec run brainstorm --done --change <变更名> --answer "信息够了，进入方案讨论" --output "需求已澄清"
 
-# 重置阶段
-sillyspec run brainstorm --reset --change 2026-05-28-agent-log-streaming
+# 分步完成
+sillyspec run brainstorm --wait --change <变更名> --reason "等待用户回答" --output "探索问题"
+sillyspec run brainstorm --continue --answer "用户回答" --change <变更名>
+sillyspec run brainstorm --done --change <变更名> --output "需求已澄清"
 ```
 
 ## 注意
-- 推荐指定 `--change <变更名>`（格式：`YYYY-MM-DD-<简短描述>`），不指定时自动生成 `YYYY-MM-DD-new-change`
+- 推荐指定 `--change <变更名>`（格式：`YYYY-MM-DD-<简短描述>`），不指定时自动生成
 - 步骤 prompt 由 CLI 管理，不需要手动读取
 - 依赖 scan 阶段完成，CLI 会自动提醒
-- brainstorm 阶段末步会自动生成四件套（proposal.md + design.md + requirements.md + tasks.md）
 - brainstorm 完成后，运行 `sillyspec run plan --change <变更名>` 进入实现计划
+
+## 用户指令
+$ARGUMENTS

package/.claude/skills/sillyspec-execute/SKILL.md

@@ -11,11 +11,18 @@ description: 用于按 plan 执行代码实现。适合用户说"开始写代码
 
 **你必须使用 exec 工具（shell）执行以下命令，不要自己编造流程：**
 
-1. 运行 `sillyspec run execute` — 读取输出的步骤 prompt
+1. 运行 `sillyspec run execute` — CLI 会自动创建 worktree 隔离环境，然后输出步骤 prompt
 2. 按照输出的 prompt **严格执行**，不要跳过或自行添加步骤
 3. 步骤完成后，运行 `sillyspec run execute --done --output "你的摘要"`
 4. 重复 2-3 直到阶段完成
 5. **禁止**在没有运行 CLI 的情况下自行决定流程
 
+## Worktree 隔离
+
+- CLI 启动 execute 阶段时**自动创建 git worktree**，AI agent 不需要手动创建
+- Worktree 路径在 Step 3（确认 worktree 路径）中输出，后续子代理的 cwd 必须设为该路径
+- **禁止跳过 worktree 或在主仓库直接写代码**
+- 如果 worktree 创建失败，CLI 会报错并退出，需要排查后再重试
+
 ## 用户指令
 $ARGUMENTS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.18.1",
+  "version": "3.18.2",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/run.js

@@ -1253,7 +1253,8 @@ export async function runCommand(args, cwd, specDir = null) {
 
   // --done
   if (isDone) {
-    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, confirmMode })
+    const doneAnswer = getFlagValue('--answer')
+    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, confirmMode, doneAnswer })
   }
 
   // 默认：输出当前步骤
@@ -1301,6 +1302,26 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
     }
   }
 
+  // execute 阶段：CLI 自动创建 worktree（不等 AI agent）
+  if (stageName === 'execute' && changeName) {
+    const effectiveChange = changeName
+    const { WorktreeManager } = await import('./worktree.js')
+    const wm = new WorktreeManager({ cwd })
+    const existingMeta = wm.getMeta(effectiveChange)
+    if (existingMeta) {
+      console.log(`🔗 worktree 已存在: ${existingMeta.worktreePath} (${existingMeta.mode})`)
+    } else {
+      try {
+        const result = wm.create(effectiveChange)
+        console.log(`🔗 worktree 已创建: ${result.worktreePath} (分支: ${result.branch}, 模式: ${result.mode})`)
+      } catch (e) {
+        console.error(`❌ worktree 创建失败: ${e.message}`)
+        console.error(`   继续执行前请解决上述问题，或使用 --no-worktree 跳过。`)
+        process.exit(1)
+      }
+    }
+  }
+
   // 自动探测 currentChange
   if (autoDetectChange(progress, cwd)) {
     progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })
@@ -1832,14 +1853,24 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
   const currentStepDef = defStepsForCurrent?.[currentIdx] || {}
   const currentStep = steps[currentIdx]
   if (currentStepDef.requiresWait === true && !currentStep.waitAnswer) {
-    console.error(`❌ Step "${currentStep.name}" 必须先等待用户输入，不能直接 --done。`)
-    console.error(`   原因：${currentStepDef.waitReason || '该步骤需要人工确认/回答'}`)
-    if (currentStepDef.waitOptions) {
-      console.error(`   选项：${currentStepDef.waitOptions.join(', ')}`)
+    // 检查 --done 是否带了 --answer：如果是，自动补全 waitAnswer 状态，一步完成
+    const doneAnswer = typeof options !== 'undefined' && options.doneAnswer ? options.doneAnswer : null
+    if (doneAnswer) {
+      currentStep.status = 'waiting'
+      currentStep.waitAnswer = doneAnswer
+      currentStep.waitReason = currentStepDef.waitReason || '等待用户输入'
+      console.log(`⚠️  Step "${currentStep.name}" 需要 wait，但 --done 带了 --answer，自动补全 wait 状态。`)
+    } else {
+      console.error(`❌ Step "${currentStep.name}" 必须先等待用户输入，不能直接 --done。`)
+      console.error(`   原因：${currentStepDef.waitReason || '该步骤需要人工确认/回答'}`)
+      if (currentStepDef.waitOptions) {
+        console.error(`   选项：${currentStepDef.waitOptions.join(', ')}`)
+      }
+      console.error(`   请先执行：`)
+      console.error(`   sillyspec run ${stageName} --wait --reason "${currentStepDef.waitReason || '等待用户输入'}" --options "${(currentStepDef.waitOptions || ['确认']).join(',')}"${changeName ? ` --change ${changeName}` : ''} --output "你的问题/方案摘要"`)
+      console.error(`   或使用 --done --answer "用户回答" 一步完成 wait + done`)
+      process.exit(1)
     }
-    console.error(`   请先执行：`)
-    console.error(`   sillyspec run ${stageName} --wait --reason "${currentStepDef.waitReason || '等待用户输入'}" --options "${(currentStepDef.waitOptions || ['确认']).join(',')}"${changeName ? ` --change ${changeName}` : ''} --output "你的问题/方案摘要"`)
-    process.exit(1)
   }
 
   steps[currentIdx].status = 'completed'
@@ -2234,10 +2265,16 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       }
     }
 
+    // 防御性守卫变量：确认所有步骤确实标记为 completed
+    const actualCompleted = steps.filter(s => s.status === 'completed').length
+    const actualTotal = steps.length
+
     validateMetadata(cwd, stageName, specBase)
 
-    // 验证关键文件是否在正确的变更目录下
-    validateFileLocations(cwd, stageName, progress, changeName, specBase)
+    // 验证关键文件是否在正确的变更目录下（仅当所有步骤确实完成时才校验）
+    if (actualCompleted === actualTotal && actualTotal > 0) {
+      validateFileLocations(cwd, stageName, progress, changeName, specBase)
+    }
 
     // 辅助阶段完成后重置步骤
     const stageDef = stageRegistry[stageName]
@@ -2281,24 +2318,30 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     } else {
       console.log(`\n下一步由你决定：sillyspec run <stage>（brainstorm/plan/execute/verify/archive 等）`)
     }
-    return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
-  }
 
-  // 阶段完成校验
-  const projectName = progress.project || basename(cwd)
-  const contractResult = runValidators(stageName, cwd, changeName, { projectName, specRoot: platformOpts?.specRoot })
-  if (contractResult.errors.length > 0) {
-    console.error(`\n❌ 阶段 ${stageName} 校验失败：`)
-    for (const err of contractResult.errors) {
-      console.error(`   - ${err}`)
-    }
-    console.error(`\n   提示：修复缺失产物后重新运行此步骤，或使用 --skip-approval 跳过校验`)
-  }
-  if (contractResult.warnings.length > 0) {
-    console.warn(`\n⚠️ 阶段 ${stageName} 校验警告：`)
-    for (const w of contractResult.warnings) {
-      console.warn(`   - ${w}`)
+    // 阶段完成校验 — 防御性守卫：仅当所有步骤确实标记为 completed 时才跑 validator
+    if (actualCompleted === actualTotal && actualTotal > 0) {
+      const projectName = progress.project || basename(cwd)
+      const contractResult = runValidators(stageName, cwd, changeName, { projectName, specRoot: platformOpts?.specRoot })
+      if (contractResult.errors.length > 0) {
+        console.error(`\n❌ 阶段 ${stageName} 校验失败：`)
+        for (const err of contractResult.errors) {
+          console.error(`   - ${err}`)
+        }
+        console.error(`\n   提示：修复缺失产物后重新运行此步骤，或使用 --skip-approval 跳过校验`)
+      }
+      if (contractResult.warnings.length > 0) {
+        console.warn(`\n⚠️ 阶段 ${stageName} 校验警告：`)
+        for (const w of contractResult.warnings) {
+          console.warn(`   - ${w}`)
+        }
+      }
+    } else if (actualCompleted < actualTotal) {
+      // 实际步骤未全部完成，跳过 validator（状态可能不同步）
+      console.log(`\n⚠️ 阶段校验跳过：${actualTotal} 步中仅 ${actualCompleted} 步标记为已完成，可能存在状态不同步。如确认阶段已完成，请运行 --status 确认。`)
     }
+
+    return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
   }
 
   progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})

package/src/stage-contract.js

@@ -520,6 +520,11 @@ export function checkTransition(fromStage, toStage) {
     return { allowed: true }
   }
 
+  // 同阶段内重复运行：允许（继续执行当前阶段的下一步）
+  if (fromStage === toStage) {
+    return { allowed: true }
+  }
+
   // archive 特殊处理：从 verify 来的允许，从其他主流程阶段来的需要校验
   if (toStage === 'archive') {
     if (fromStage === 'verify') {

package/src/stages/execute.js

@@ -52,27 +52,25 @@ const fixedPrefix = [
     optional: false
   },
   {
-    name: '创建 worktree',
-    prompt: `为本次执行创建隔离的 git worktree。
+    name: '确认 worktree 路径',
+    prompt: `确认当前 worktree 状态，提取隔离路径。
 
 ### 操作
-1. 运行 \`sillyspec worktree create <change-name>\`
-2. 记录输出的 worktree 路径
-3. 后续所有子代理的 cwd 设为该 worktree 路径
-4. 如果创建失败 → 报错并停止（不要在无隔离状态下继续）
+1. 运行 \`sillyspec worktree meta <change-name>\` 读取 meta.json
+2. 从输出中提取 worktreePath、branch、mode 字段
+3. 确认 worktree 目录存在（如果是 worktree/native-worktree 模式）
 
-### 降级模式
-CLI 可能自动降级（sandbox 限制、已在 linked worktree 中）：
-- \`mode: native-worktree\` — 已在 linked worktree，直接复用
-- \`mode: in-place-fallback\` — git worktree add 失败，降级为 in-place + baseline protection
-- 这两种模式都会输出 worktree 路径和分支名，正常继续即可
+### 铁律
+- **worktree 已由 CLI 在 execute 阶段启动时自动创建，不要自行创建或跳过**
+- **后续所有子代理的 cwd 必须设为该 worktree 路径**
+- 如果 meta.json 不存在（说明创建失败），停止并报错
 
 ### 输出
-worktree 路径 + 分支名 + 模式（如果有）
+worktree 路径 + 分支名 + 模式
 
 ### 完成后执行
-sillyspec run execute --done --output "worktree 路径 + 分支名"`,
-    outputHint: 'worktree 路径 + 分支名',
+sillyspec run execute --done --output "worktree 路径 + 分支名 + 模式"`,
+    outputHint: 'worktree 路径 + 分支名 + 模式',
     optional: false
   },
   {