sillyspec 3.24.6 → 3.24.8

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:archive
-description: 归档已验证完成的变更：模块影响分析 + 同步模块文档 + 移动到 archive + 更新 ROADMAP。
+description: 用于归档已验证完成的变更。适合用户说"归档、archive、收尾这个变更"。执行模块影响分析 + 同步模块文档 + 移动到 archive 目录 + 更新 ROADMAP。
 ---
 
 ## 何时使用

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:brainstorm
-description: 正式开发前的需求澄清与技术方案设计。产出结构化方案（design/proposal/requirements/tasks 四件套），不直接写代码。
+description: 用于正式开始开发前的需求澄清和技术方案设计。适合用户提出新功能、新模块、架构调整、复杂改造，或说"先做需求分析、输出技术方案、创建变更前先梳理、帮我设计下"。产出结构化方案（design/proposal/requirements/tasks 四件套），但不直接写代码。
 ---
 
 ## 交互规范

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:doctor
-description: SillySpec 自检与状态修复：全量扫描进度一致性，修复进度数据与实际产出不匹配。
+description: 用于 SillySpec 自检和状态修复。适合用户说"检查下状态、修复 progress、doctor、状态不对"。全量扫描进度一致性，修复进度数据与实际产出不匹配的问题。
 ---
 
 ## 何时使用

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:execute
-description: 按 plan 执行代码实现：依 plan.md 的 Wave/Task 逐步实现，遵循 design.md 与模块文档。
+description: 用于按 plan 执行代码实现。适合用户说"开始写代码、执行任务、跑 execute、开干"。按 plan.md 中的 Wave 和 Task 逐步实现，遵循 design.md 和模块文档。
 ---
 
 ## 何时使用

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:explore
-description: 用于自由讨论、代码库调研、方案比较、画 ASCII 图。只读，不写代码不实现功能。
+description: 用于自由讨论、代码库调研、方案比较、画 ASCII 图、澄清问题。适合用户说"分析下、讨论下、看看怎么设计、先别写代码、调研一下、画个结构图、帮我再分析下"。只读，不修改文件，不实现功能。
 ---
 
 ## 交互规范

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:plan
-description: 把 design 拆解为可执行的实现计划。产出 plan.md（Wave 分组 + Task 列表 + 依赖关系）。
+description: 用于把 design 拆解为可执行的实现计划。适合用户说"拆任务、做计划、排 wave、规划实现步骤"。产出 plan.md（Wave 分组 + Task 列表 + 依赖关系）。
 ---
 
 ## 何时使用

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:propose
-description: 生成结构化规范：proposal.md + design.md + tasks.md（+ 可能 requirements.md）。
+description: 生成结构化规范 — proposal + design + tasks。适合用户说"生成规范、补全四件套、propose"。产出 proposal.md + design.md + tasks.md（+ 可能的 requirements.md）。
 ---
 
 ## 何时使用

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:quick
-description: 用于明确、低风险、小范围的直接修改（改文案/修小 bug/更新单文件）。跳过 brainstorm/plan，仍走 quick 流程。
+description: 用于明确、低风险、范围很小的直接任务。适合用户说"直接改、快速修、顺手调整、改个文案、修个小 bug、更新一个文件、不要完整流程"。跳过 brainstorm/plan，但仍按 sillyspec quick 流程执行。
 ---
 
 ## 何时使用

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:scan
-description: 扫描项目代码库，生成架构文档、代码约定、目录结构。产出 7 份扫描文档 + 模块映射。
+description: 用于扫描项目代码库，生成架构文档、代码约定、目录结构等。适合用户说"扫描项目、分析代码库、生成文档、scan"。产出 7 份扫描文档 + 模块映射。
 ---
 
 ## 何时使用

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:status
-description: 查看 SillySpec 当前进度与状态：当前阶段、步骤完成度、活跃变更。
+description: 用于查看 SillySpec 当前进度和状态。适合用户说"看下状态、当前进度、status"。显示当前阶段、步骤完成度、活跃变更。
 ---
 
 ## 何时使用

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:verify
-description: 验证代码实现是否符合 design 与模块文档。对照 design.md + 模块文档检查任务完成度、设计一致性、运行测试。
+description: 用于验证代码实现是否符合 design 和模块文档。适合用户说"验证下、检查下、跑 verify"。对照 design.md + 模块文档检查任务完成度、设计一致性、运行测试。
 ---
 
 ## 何时使用

package/package.json

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

package/src/constants.js

@@ -68,3 +68,15 @@ export function isPointerStale(pointer) {
 export function isPointerCorrupted(pointer) {
   return !pointer || !pointer.specRoot || !pointer.savedAt
 }
+
+// ── scan 必需文档清单（stage-contract validator 与 scan-postcheck 共用单一真相源）──
+// 曾分两处硬编码同一份清单，加新文档需同步改两处，易分叉。现收敛到此处一处。
+export const SCAN_REQUIRED_DOCS = Object.freeze([
+  'ARCHITECTURE.md',
+  'CONVENTIONS.md',
+  'STRUCTURE.md',
+  'INTEGRATIONS.md',
+  'TESTING.md',
+  'CONCERNS.md',
+  'PROJECT.md',
+])

package/src/fs-atomic.js

@@ -0,0 +1,69 @@
+/**
+ * fs-atomic.js — 原子文件写 + Windows 友好的 rename 重试
+ *
+ * 用于 .runtime/*.json、pointer、guard.json 等「会被其他进程 / hook 读取」的配置文件。
+ * 保证读者要么看到旧完整内容、要么看到新完整内容，不会读到半截 JSON。
+ *
+ * 注意：db.js 有自己的 _atomicWriteSync（含 .bak 备份），那是 DB 专属持久化逻辑，
+ * 已经过稳定性验证，此处不复用、不替换——保持 db.js 零改动。
+ */
+import { writeFileSync, renameSync, unlinkSync } from 'fs';
+import { dirname, basename, join } from 'path';
+
+// Windows 上杀毒 / 索引 / IDE 占用文件时，rename 偶发这些错误，短退避重试即可
+const RENAME_RETRY_CODES = ['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY'];
+
+/** 同步退避：优先 Atomics.wait，不可用时退化忙等（仅在 rename 冲突的极端情况触发）。 */
+function sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    const end = Date.now() + ms;
+    while (Date.now() < end) { /* busy wait */ }
+  }
+}
+
+/**
+ * rename 带退避重试，覆盖 Windows 偶发的 EPERM/EBUSY/EACCES/ENOTEMPTY。
+ * 目录 rename 同样适用（归档移动目录时可复用）。
+ * @param {string} from
+ * @param {string} to
+ * @param {number} [retries=5]
+ */
+export function renameSyncRetry(from, to, retries = 5) {
+  let lastErr;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      renameSync(from, to);
+      return;
+    } catch (err) {
+      lastErr = err;
+      const code = err && err.code;
+      // 非可重试错误码立即抛出，不浪费时间
+      if (!code || !RENAME_RETRY_CODES.includes(code)) throw err;
+      if (attempt < retries) sleepSync(15 * (attempt + 1));
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * 原子写文本文件：同目录 tmp 写入 → rename 覆盖目标（带 Windows 退避重试）。
+ * - tmp 名含 pid，避免多进程并发写同一目标时 tmp 名碰撞（如多会话写 gate-status.json）。
+ * - rename 失败时清理 tmp，避免留下孤儿 .tmp 文件。
+ * - Node 的 rename 在 Windows 上用 MoveFileEx(REPLACE_EXISTING)，可覆盖已存在目标；
+ *   EPERM 仅在文件被其他进程锁定时出现，由 renameSyncRetry 退避重试。
+ * @param {string} filePath - 目标文件绝对路径
+ * @param {string} content - 文件内容
+ */
+export function writeAtomicSync(filePath, content) {
+  const dir = dirname(filePath);
+  const tmpPath = join(dir, `.${basename(filePath)}.${process.pid}.tmp`);
+  writeFileSync(tmpPath, content);
+  try {
+    renameSyncRetry(tmpPath, filePath);
+  } catch (err) {
+    try { unlinkSync(tmpPath); } catch { /* tmp 可能已被 rename 走，忽略 */ }
+    throw err;
+  }
+}

package/src/index.js

@@ -7,6 +7,7 @@
  * 状态管理通过 sillyspec.db（SQLite）完成，使用 `sillyspec progress` 命令。
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
+import { writeAtomicSync } from './fs-atomic.js';
 import { join, resolve } from 'path';
 import { cmdInit, getVersion } from './init.js';
 import { ProgressManager, resolvePlatformSpecDir } from './progress.js';
@@ -280,7 +281,7 @@ async function main() {
         }
         case 'batch': {
           if (filteredArgs.includes('--status')) {
-            const bp = pm.readBatchProgress(dir, progChangeName);
+            const bp = await pm.readBatchProgress(dir, progChangeName);
             if (!bp) { console.log('📭 无批量进度数据'); break; }
             const line = pm._renderBatchProgress(bp);
             console.log(line || '📭 无批量进度数据');
@@ -299,7 +300,7 @@ async function main() {
               console.log('     sillyspec progress batch --status');
               break;
             }
-            pm.updateBatchProgress(dir, batchData, progChangeName);
+            await pm.updateBatchProgress(dir, batchData, progChangeName);
             console.log('✅ 批量进度已更新');
           }
           break;
@@ -1171,11 +1172,9 @@ SillySpec modules — 模块文档管理
       lines.push('#   order-service: "order/"');
       const yamlText = lines.join('\n') + '\n';
 
-      // 原子写：mkdir -p specRoot → 写 tmp → rename
+      // 原子写（tmp + rename + Windows EPERM 重试），避免半截 local.yaml
       mkdirSync(specRoot, { recursive: true });
-      const tmpPath = localYamlPath + '.tmp';
-      writeFileSync(tmpPath, yamlText, 'utf8');
-      renameSync(tmpPath, localYamlPath);
+      writeAtomicSync(localYamlPath, yamlText);
 
       console.log(`✅ 已生成 local.yaml (type: ${detected.project.type})`);
       console.log(`   路径: ${localYamlPath}`);

package/src/modules.js

@@ -79,7 +79,7 @@ export async function rebuildModuleMap(cwd) {
       const content = readFileSync(join(modulesDir, f), 'utf8');
       const fm = parseModuleCardFrontmatter(content);
       const moduleId = fm.module_id || parseModuleIdFromFilename(f);
-      cards.push({ filename: f, moduleId });
+      cards.push({ filename: f, moduleId, content });
     }
   }
 
@@ -134,7 +134,7 @@ export async function rebuildModuleMap(cwd) {
 
   for (const moduleId of allModuleIds) {
     const card = cards.find(c => c.moduleId === moduleId);
-    const cardContent = card ? readFileSync(join(modulesDir, card.filename), 'utf8') : '';
+    const cardContent = card?.content || '';
 
     // 从模块卡片提取 context index 字段
     const role = extractSection(cardContent, '定位') || '';

package/src/progress.js

@@ -13,6 +13,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync } from 'fs';
 import { join, basename, dirname, resolve } from 'path';
 import { DB } from './db.js';
+import { writeAtomicSync } from './fs-atomic.js';
 
 // 默认规范目录名（相对于 cwd）
 const SPEC_DIR_NAME = '.sillyspec';
@@ -156,7 +157,14 @@ export class ProgressManager {
   /** 获取 specDir（优先自定义，否则向上查找含 .sillyspec 的目录，fallback 到 cwd/.sillyspec） */
   _getSpecDir(cwd) {
     if (this._customSpecDir) return this._customSpecDir;
-    return resolveSpecDir(cwd);
+    // specDir 对给定 cwd 在进程生命周期内不变（.sillyspec 目录不会被移动），
+    // 按 cwd 缓存，避免每次路径解析都向上 existsSync 遍历目录树（热路径）。
+    if (!this._specDirCache) this._specDirCache = new Map();
+    const cached = this._specDirCache.get(cwd);
+    if (cached) return cached;
+    const resolved = resolveSpecDir(cwd);
+    this._specDirCache.set(cwd, resolved);
+    return resolved;
   }
 
   _runtimePath(cwd, ...parts) {
@@ -1064,7 +1072,7 @@ export class ProgressManager {
       mkdirSync(historyDir, { recursive: true });
       const ts = now.replace(/[:.TZ-]/g, '');
       const stageData = data.stages[stage];
-      writeFileSync(
+      writeAtomicSync(
         join(historyDir, `${cn}-${stage}-${ts}.json`),
         JSON.stringify({ change: cn, stage, data: stageData, completedAt: now }, null, 2) + '\n'
       );
@@ -1666,8 +1674,7 @@ export class ProgressManager {
             const changeId = changeRow[0].values[0][0];
             sqlDb.run('DELETE FROM steps WHERE stage_id IN (SELECT id FROM stages WHERE change_id = ?)', [changeId]);
             sqlDb.run('DELETE FROM stages WHERE change_id = ?', [changeId]);
-            sqlDb.run('UPDATE stages SET status = "pending", started_at = NULL, completed_at = NULL WHERE change_id = ?', [changeId]);
-            // 重新插入所有阶段
+            // 重新插入所有阶段（注意：上方已 DELETE stages，无需再 UPDATE）
             for (const s of VALID_STAGES) {
               sqlDb.run('INSERT OR IGNORE INTO stages (change_id, stage, status) VALUES (?, ?, "pending")', [changeId, s]);
             }
@@ -1865,9 +1872,7 @@ export class ProgressManager {
         updatedAt: new Date().toISOString(),
         ...(hasNoWorktree ? { noWorktree: true } : {}),
       };
-      const tmpPath = gatePath + '.tmp';
-      writeFileSync(tmpPath, JSON.stringify(gateData, null, 2) + '\n');
-      renameSync(tmpPath, gatePath);
+      writeAtomicSync(gatePath, JSON.stringify(gateData, null, 2) + '\n');
     } catch (err) {
       console.warn('⚠️  写入 gate-status.json 失败:', err.message);
     }

package/src/run.js

@@ -6,6 +6,7 @@
  */
 import { basename, join, resolve, dirname, relative, isAbsolute } from 'path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, rmSync, statSync } from 'fs'
+import { writeAtomicSync, renameSyncRetry } from './fs-atomic.js'
 import { randomBytes, randomUUID } from 'crypto'
 import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
@@ -1245,12 +1246,15 @@ async function executeScanPreflight(cwd, platformOpts, scanProfile) {
   const projectName = basename(cwd)
   console.log(`  📁 项目: ${projectName}`)
   console.log(`  📊 Profile: ${scanProfile.mode} (${scanProfile.reason})`)
-  // 快速列出顶层结构
+  // 快速列出顶层结构（readdirSync 跨平台，避免 spawn shell + 5 个 grep 进程）
   try {
-    const { execSync } = await import('child_process')
-    const dirs = execSync(`ls -d */ 2>/dev/null | grep -v node_modules | grep -v '.git' | grep -v '.sillyspec' | grep -v '.claude' | head -20`, { cwd, encoding: 'utf8' }).trim()
-    if (dirs) {
-      console.log(`  📂 目录: ${dirs.split('\n').map(d => d.replace(/\/$/, '')).join(', ')}`)
+    const skip = new Set(['node_modules', '.git', '.sillyspec', '.claude'])
+    const dirNames = readdirSync(cwd, { withFileTypes: true })
+      .filter(d => d.isDirectory() && !skip.has(d.name) && !d.name.startsWith('.'))
+      .slice(0, 20)
+      .map(d => d.name)
+    if (dirNames.length) {
+      console.log(`  📂 目录: ${dirNames.join(', ')}`)
     }
   } catch {}
   console.log(`  ✅ Preflight 完成，准备生成核心文档\n`)
@@ -2199,7 +2203,7 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
         // 写入 .runtime/quick-sessions/<sessionId>/guard.json 供 worktree-guard hook 读取
         // （D-002：按 session 存，多会话各自 guard 不互覆盖。runStage 作用域内 sessionId == changeName == quick-<uuid8>，见 §4.4/4.5）
         mkdirSync(sessionGuardDir, { recursive: true })
-        writeFileSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
+        writeAtomicSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
         const parts = [`${baselineFiles.length} 个已有脏文件`]
         if (allowedFiles.length > 0) parts.push(`${allowedFiles.length} 个 allowedFiles`)
         if (allowNew) parts.push('允许新增文件')
@@ -2383,7 +2387,13 @@ async function archiveChangeDirectory(pm, cwd, progress, specBase) {
     process.exit(1)
   }
   mkdirSync(archiveDir, { recursive: true })
-  renameSync(srcDir, destDir)
+  try {
+    renameSyncRetry(srcDir, destDir)
+  } catch (e) {
+    console.error(`❌ 归档失败：移动变更目录时出错（${e.message}）`)
+    console.error(`   常见原因：变更目录内文件被 IDE / 杀毒 / 索引占用，已重试 5 次仍失败。请关闭相关程序后重试。`)
+    process.exit(1)
+  }
 
   if (!existsSync(destDir) || existsSync(srcDir)) {
     console.error('❌ 归档校验失败：移动操作异常')
@@ -2749,7 +2759,11 @@ async function enforceDepsGate(stageName, cwd, changeName, step, steps, currentI
     const { WorktreeManager } = await import('./worktree.js')
     wm = new WorktreeManager({ cwd })
     meta = wm.getMeta(changeName)
-  } catch {}
+  } catch (e) {
+    // WorktreeManager 构造/读取失败（git 不可用 / worktree 元数据损坏）不阻断 deps gate；
+    // 下游已有物理目录存在性判定兜底（G2/R3），这里 warn 留下根因线索，避免静默误诊。
+    console.warn(`⚠️ worktree meta 读取失败（deps gate 将走物理目录判定）: ${e.message}`)
+  }
   const depsStatus = meta?.depsStatus
   if (['linked', 'installed', 'n/a'].includes(depsStatus)) return true
   const changeDir = changeName ? join(specBase, 'changes', changeName) : null
@@ -3402,8 +3416,12 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
           pointer.status = POINTER_STATUS.SCAN_COMPLETED
           pointer.completedAt = new Date().toISOString()
           pointer.scanStatus = postResult.status
-          writeFileSync(pointerPath, JSON.stringify(pointer, null, 2) + '\n')
-        } catch {}
+          writeAtomicSync(pointerPath, JSON.stringify(pointer, null, 2) + '\n')
+        } catch (e) {
+          // 不阻断 scan 主流程，但暴露失败——pointer 写失败会让平台看不到 scan_completed，
+          // 与项目 fail-loud 原则一致：宁可可见地 warn，也不静默吞错。
+          console.warn(`⚠️ 更新平台指针状态失败（scan_completed 可能未落盘）: ${e.message}`)
+        }
 
         // failed_post_check 时强制阻止 clean success
         if (postResult.status === 'failed_post_check') {

package/src/scan-postcheck.js

@@ -7,17 +7,9 @@
 
 import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync } from 'fs'
 import { join, basename } from 'path'
-import { SCAN_STATUS, CHECK_SEVERITY } from './constants.js'
+import { SCAN_STATUS, CHECK_SEVERITY, SCAN_REQUIRED_DOCS } from './constants.js'
 
-const REQUIRED_SCAN_DOCS = [
-  'ARCHITECTURE.md',
-  'CONVENTIONS.md',
-  'STRUCTURE.md',
-  'INTEGRATIONS.md',
-  'TESTING.md',
-  'CONCERNS.md',
-  'PROJECT.md',
-]
+const REQUIRED_SCAN_DOCS = SCAN_REQUIRED_DOCS
 
 /**
  * @param {object} opts

package/src/stage-contract.js

@@ -9,6 +9,7 @@ import { existsSync, readdirSync, readFileSync } from 'fs'
 import { join, basename } from 'path'
 import { execFileSync } from 'child_process'
 import { detectChangeRisk, checkIntegrationEvidence } from './change-risk-profile.js'
+import { SCAN_REQUIRED_DOCS } from './constants.js'
 
 /**
  * 校验结果
@@ -215,15 +216,7 @@ function validateScanOutputs(cwd, changeName, context = {}) {
     ? join(specBase, 'docs', projectName, 'scan')
     : join(specBase, 'docs', 'scan')
 
-  const requiredDocs = [
-    'ARCHITECTURE.md',
-    'CONVENTIONS.md',
-    'STRUCTURE.md',
-    'INTEGRATIONS.md',
-    'TESTING.md',
-    'CONCERNS.md',
-    'PROJECT.md',
-  ]
+  const requiredDocs = SCAN_REQUIRED_DOCS
 
   const errors = []
   const warnings = []

package/src/stages/brainstorm-auto.js

@@ -25,7 +25,7 @@ export const definition = {
 3. **检查变更名称**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change-a3f2b7c1\`），直接重命名为有意义名称，然后运行 \`sillyspec change-rename <旧名> <新名>\`
 
 ### 加载上下文
-4. 读取 CODEBASE-OVERVIEW.md + 共享规范 + 子项目上下文
+4. 读取项目总览 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（如存在）+ 共享规范 + 子项目上下文
 5. 加载项目信息：\`cat .sillyspec/projects/*.yaml 2>/dev/null\`
 6. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`
 7. 棕地项目：读取 scan 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md