sillyspec 3.18.0 → 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.0",
+  "version": "3.18.2",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/db.js

@@ -175,6 +175,10 @@ export class DB {
     this._migrateAddColumn('steps', 'wait_options', 'TEXT');
     this._migrateAddColumn('steps', 'wait_answer', 'TEXT');
     this._migrateAddColumn('steps', 'waited_at', 'TEXT');
+    // repeatableWait support
+    this._migrateAddColumn('steps', 'wait_answers', 'TEXT'); // JSON array
+    this._migrateAddColumn('steps', 'wait_round', 'INTEGER');
+    this._migrateAddColumn('steps', 'max_wait_rounds', 'INTEGER');
   }
 
   /**

package/src/hooks/worktree-guard.js

@@ -126,6 +126,96 @@ function isPathInside(child, parent) {
   return absChild === absParent || absChild.startsWith(absParent + path.sep)
 }
 
+function toPosixPath(filePath) {
+  return filePath.replace(/\\/g, '/')
+}
+
+function parseFrontmatter(content) {
+  if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return {}
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/)
+  if (!match) return {}
+  const result = {}
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/)
+    if (!m) continue
+    result[m[1]] = m[2].replace(/^['"]|['"]$/g, '').trim()
+  }
+  return result
+}
+
+function parseTimestamp(value) {
+  if (!value) return null
+  const time = Date.parse(value)
+  return Number.isNaN(time) ? null : time
+}
+
+function getScanDocInfo(filePath) {
+  const normalized = toPosixPath(path.resolve(filePath))
+  const match = normalized.match(/^(.*)\/docs\/([^/]+)\/scan\/([^/]+\.md)$/)
+  if (!match) return null
+  return {
+    specRoot: path.resolve(match[1]),
+    projectName: match[2],
+    docName: match[3],
+  }
+}
+
+function readScanGuard(scanDocInfo, projectRoot) {
+  const candidates = [
+    path.join(scanDocInfo.specRoot, '.runtime', 'scan-guard.json'),
+    path.join(projectRoot, '.sillyspec', '.runtime', 'scan-guard.json'),
+  ]
+  for (const p of candidates) {
+    if (!existsSync(p)) continue
+    try {
+      return JSON.parse(readFileSync(p, 'utf8'))
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+function shouldBlockScanDocOverwrite(filePath, projectRoot) {
+  const scanDocInfo = getScanDocInfo(filePath)
+  if (!scanDocInfo || !existsSync(filePath)) return { blocked: false }
+
+  const guard = readScanGuard(scanDocInfo, projectRoot)
+  if (!guard || guard.forceRescan) return { blocked: false }
+
+  let frontmatter = {}
+  try {
+    frontmatter = parseFrontmatter(readFileSync(filePath, 'utf8'))
+  } catch {
+    return { blocked: false }
+  }
+
+  const relPath = toPosixPath(path.relative(projectRoot, filePath))
+  if (frontmatter.source_commit && guard.sourceCommit && frontmatter.source_commit !== guard.sourceCommit) {
+    return {
+      blocked: true,
+      reason: [
+        `scan 覆盖保护：${relPath} 的 source_commit=${frontmatter.source_commit} 与当前 scan source_commit=${guard.sourceCommit} 不一致。`,
+        '如确认要重新生成，请重新运行 scan 并添加 --force-rescan。',
+      ].join('\n')
+    }
+  }
+
+  const existingUpdatedAt = parseTimestamp(frontmatter.updated_at)
+  const scanStartedAt = parseTimestamp(guard.startedAt)
+  if (existingUpdatedAt && scanStartedAt && existingUpdatedAt > scanStartedAt) {
+    return {
+      blocked: true,
+      reason: [
+        `scan 覆盖保护：${relPath} 的 updated_at 晚于本次 scan 开始时间，可能包含手工编辑。`,
+        '如确认要覆盖，请重新运行 scan 并添加 --force-rescan。',
+      ].join('\n')
+    }
+  }
+
+  return { blocked: false }
+}
+
 function isInsideWorktreeStorage(filePath, cwd) {
   const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd || process.cwd(), filePath)
   return isPathInside(absPath, resolveWorktreeDir(cwd || process.cwd()))
@@ -489,12 +579,15 @@ export function shouldBlockWrite(filePath, cwd) {
   const projectRoot = findProjectRoot(callerCwd)
   const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(callerCwd, filePath)
 
-  // 1. 文件门禁：文档类/配置类始终放行，但 worktree 存储区内的源码必须继续走登记校验。
-  if (!isInsideWorktreeStorage(absPath, projectRoot) && matchFileWhitelist(absPath)) return { blocked: false }
-
-  // 2. 阶段门禁（使用 fallback 读取）
+  // 1. 阶段门禁（使用 fallback 读取）
   const stage = readCurrentStage(projectRoot) || '(none)'
 
+  const scanGuardResult = shouldBlockScanDocOverwrite(absPath, projectRoot)
+  if (scanGuardResult.blocked) return scanGuardResult
+
+  // 2. 文件门禁：文档类/配置类始终放行，但 worktree 存储区内的源码必须继续走登记校验。
+  if (!isInsideWorktreeStorage(absPath, projectRoot) && matchFileWhitelist(absPath)) return { blocked: false }
+
   if (!['execute', 'quick'].includes(stage)) {
     return {
       blocked: true,

package/src/index.js

@@ -40,7 +40,7 @@ SillySpec CLI — 规范驱动开发工具包
     auto                       连续推进 brainstorm→plan→execute→verify
 
   可选阶段:
-    scan, brainstorm, propose, plan, execute, verify, archive
+    scan, brainstorm, plan, execute, verify, archive
     quick, explore, status, doctor
 
   sillyspec progress <cmd>     进度记录（轻量，不强制顺序）

package/src/progress.js

@@ -12,16 +12,32 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'fs';
-import { join, basename } from 'path';
+import { join, basename, dirname, resolve } from 'path';
 import { DB } from './db.js';
 
 // 默认规范目录名（相对于 cwd）
 const SPEC_DIR_NAME = '.sillyspec';
 const RUNTIME_SUBDIR = '.runtime';
+
+/**
+ * 向上查找含 .sillyspec 目录的祖先目录，类似 git 找 .git 的逻辑。
+ * 找到则返回 <祖先>/.sillyspec，否则 fallback 到 <cwd>/.sillyspec。
+ */
+export function resolveSpecDir(startDir) {
+  let dir = resolve(startDir);
+  while (true) {
+    const candidate = join(dir, SPEC_DIR_NAME);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break; // 到达根目录
+    dir = parent;
+  }
+  return join(resolve(startDir), SPEC_DIR_NAME);
+}
 const CHANGES_SUBDIR = 'changes';
 const GLOBAL_FILE = 'global.json';
 const CURRENT_VERSION = 3;
-const VALID_STAGES = ['scan', 'brainstorm', 'propose', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore'];
+const VALID_STAGES = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore'];
 const VALID_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked', 'waiting'];
 
 const STAGE_LABELS = {
@@ -62,9 +78,10 @@ export class ProgressManager {
 
   // ── 路径工具 ──
 
-  /** 获取 specDir（优先自定义，否则 cwd/.sillyspec） */
+  /** 获取 specDir（优先自定义，否则向上查找含 .sillyspec 的目录，fallback 到 cwd/.sillyspec） */
   _getSpecDir(cwd) {
-    return this._customSpecDir || join(cwd, SPEC_DIR_NAME);
+    if (this._customSpecDir) return this._customSpecDir;
+    return resolveSpecDir(cwd);
   }
 
   _runtimePath(cwd, ...parts) {
@@ -207,21 +224,29 @@ export class ProgressManager {
     if (stageIds.length > 0) {
       const placeholders = stageIds.map(() => '?').join(',');
       stepRows = sqlDb.exec(
-        `SELECT stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`,
+        `SELECT stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at, wait_answers, wait_round, max_wait_rounds FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`,
         stageIds
       );
     }
     // 按阶段分组步骤
     const stepsByStage = {};
     if (stepRows && stepRows.length > 0) {
-      for (const [stageId, name, status, output, completedAt, ordering, waitReason, waitOptions, waitAnswer, waitedAt] of stepRows[0].values) {
+      for (const row of stepRows[0].values) {
+        const [stageId, name, status, output, completedAt, ordering, waitReason, waitOptions, waitAnswer, waitedAt, waitAnswersJson, waitRound, maxWaitRounds] = row;
         if (!stepsByStage[stageId]) stepsByStage[stageId] = [];
+        let waitAnswers = null;
+        if (waitAnswersJson) {
+          try { waitAnswers = JSON.parse(waitAnswersJson); } catch {}
+        }
         stepsByStage[stageId].push({
           name, status, output, completedAt,
           ...(waitReason ? { waitReason } : {}),
           ...(waitOptions ? { waitOptions } : {}),
           ...(waitAnswer ? { waitAnswer } : {}),
           ...(waitedAt ? { waitedAt } : {}),
+          ...(waitAnswers ? { waitAnswers } : {}),
+          ...(waitRound != null ? { waitRound } : {}),
+          ...(maxWaitRounds != null ? { maxWaitRounds } : {}),
         });
       }
     }
@@ -257,6 +282,9 @@ export class ProgressManager {
         ...(s.waitOptions ? { waitOptions: s.waitOptions } : {}),
         ...(s.waitAnswer ? { waitAnswer: s.waitAnswer } : {}),
         ...(s.waitedAt ? { waitedAt: s.waitedAt } : {}),
+        ...(s.waitAnswers ? { waitAnswers: s.waitAnswers } : {}),
+        ...(s.waitRound != null ? { waitRound: s.waitRound } : {}),
+        ...(s.maxWaitRounds != null ? { maxWaitRounds: s.maxWaitRounds } : {}),
       }));
       stages[stage] = {
         status: info.status,
@@ -340,9 +368,11 @@ export class ProgressManager {
               // UPSERT 步骤（先删再插，steps 表无 UNIQUE 约束）
               sqlDb.run('DELETE FROM steps WHERE stage_id = ? AND name = ?', [stageId, step.name]);
               sqlDb.run(
-                'INSERT INTO steps (stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+                'INSERT INTO steps (stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at, wait_answers, wait_round, max_wait_rounds) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
                 [stageId, step.name, step.status || 'pending', step.output || null, step.completedAt || null, i,
-                  step.waitReason || null, step.waitOptions || null, step.waitAnswer || null, step.waitedAt || null]
+                  step.waitReason ?? null, step.waitOptions ?? null, step.waitAnswer ?? null, step.waitedAt ?? null,
+                  Array.isArray(step.waitAnswers) ? JSON.stringify(step.waitAnswers) : null,
+                  step.waitRound ?? null, step.maxWaitRounds ?? null]
               );
             }
           }
@@ -411,11 +441,8 @@ export class ProgressManager {
          VALUES (?, ?, ?)`,
         [changeName, now, now]
       );
-      // 如果已存在但为 archived，恢复为 active
-      sqlDb.run(
-        `UPDATE changes SET status = 'active', last_active = ? WHERE name = ? AND status = 'archived'`,
-        [now, changeName]
-      );
+      // 注意：不复活已归档的变更——归档是不可逆操作
+      // 如果变更已存在且为 archived，保持 archived 状态不变
     });
   }
 
@@ -634,7 +661,7 @@ export class ProgressManager {
       const changeId = changeRow[0].values[0][0];
 
       // 批量插入 9 个阶段（INSERT OR IGNORE 跳过已存在的）
-      const allStages = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'propose'];
+      const allStages = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore'];
       for (const stage of allStages) {
         sqlDb.run(
           `INSERT OR IGNORE INTO stages (change_id, stage, status)