sillyspec 3.24.7 → 3.25.0

package/package.json

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

package/src/constants.js

@@ -68,3 +68,28 @@ 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',
+])
+
+// ── 辅助 stage 清单（stage-contract 转移规则 与 stages/index 注册表 共用单一真相源）──
+// 曾在 stage-contract.js 与 stages/index.js 逐字重复定义，新增/调整辅助 stage 需同步改两处
+// 易分叉。现收敛一处。（注意：主流程序 STAGE_ORDER/mainFlowStages/flowStages 语义不同、
+// 各自用途正确，不在本清单范围。）
+export const AUXILIARY_STAGES = Object.freeze([
+  'scan',
+  'quick',
+  'explore',
+  'archive',
+  'status',
+  'doctor',
+])

package/src/contract-matrix.js

@@ -14,6 +14,7 @@ import {
   scanBackendEndpoints,
   scanFrontendApiCalls,
   normalizePath,
+  diffApiParity,
 } from './endpoint-extractor.js'
 import { parseTaskContracts } from './stages/plan-postcheck.js'
 
@@ -59,8 +60,12 @@ export function buildContractMatrix(planContent, changeDir) {
   const taskDeps = parseTaskDependencies(planContent)
 
   // 读取各 task 文档，分类 provider/consumer
+  // classify consumers（taskDeps keys）+ providers（deps 值）。
+  // 旧实现只 classify consumers → provider task 不在 keys 里 → providerClass 恒 undefined
+  // → contracts 恒空 → 端点契约管线（buildConsumerInjection / extractArtifactsForChange）全失效。
   const taskClasses = {}
-  for (const taskName of Object.keys(taskDeps)) {
+  const allTaskNames = new Set([...Object.keys(taskDeps), ...Object.values(taskDeps).flat()])
+  for (const taskName of allTaskNames) {
     const taskFile = join(changeDir, 'tasks', `${taskName}.md`)
     if (existsSync(taskFile)) {
       taskClasses[taskName] = classifyTask(readFileSync(taskFile, 'utf8'))
@@ -103,7 +108,9 @@ function parseTaskDependencies(planContent) {
   const deps = {}
 
   // 方式 1: 表格形式 | task-04 | ... | 01,02 |
-  const tableRows = planContent.matchAll(/\|[^|]*task-(\d+)[^|]*\|[^|]*\|[^|]*(?:task-)?(\d+(?:\s*[,，]\s*\d+)*)[^|]*\|/gi)
+  // 列前缀用 [^|\d]*（不吃数字）：旧 [^|]* 贪婪会吃掉 deps 列前导 0（" 01" → g2=1 → task-1），
+  // 导致 provider task-1.md 不存在 → contracts 恒空，端点契约管线失效。
+  const tableRows = planContent.matchAll(/\|[^|]*task-(\d+)[^|]*\|[^|]*\|[^|\d]*(?:task-)?(\d+(?:\s*[,，]\s*\d+)*)[^|]*\|/gi)
   for (const match of tableRows) {
     const task = `task-${match[1]}`
     const depList = match[2].split(/[,，\s]+/).map(d => `task-${d.trim()}`).filter(d => d.startsWith('task-'))
@@ -137,7 +144,9 @@ function parseTaskDependencies(planContent) {
 export function extractProviderArtifact(changeDir, worktreePath, specBase, taskName, runtimeRoot) {
   // 平台模式 contract-artifacts 落 runtimeRoot；否则落 specBase/.runtime
   const artifactRoot = runtimeRoot || join(specBase, '.runtime')
-  const artifactDir = join(artifactRoot, 'contract-artifacts', taskName)
+  // 跨变更隔离：contract-artifacts/<changeName>/<taskName>/，避免不同变更同名 task 互相覆盖污染对账
+  const changeName = changeDir ? basename(changeDir) : '_unknown'
+  const artifactDir = join(artifactRoot, 'contract-artifacts', changeName, taskName)
   const artifactPath = join(artifactDir, 'endpoints.json')
 
   if (!worktreePath || !existsSync(worktreePath)) {
@@ -171,6 +180,28 @@ export function extractProviderArtifact(changeDir, worktreePath, specBase, taskN
   }
 }
 
+/**
+ * 汇总提取一个变更内所有 provider task 的 endpoint artifact。
+ * run.js completeStep 在 execute Wave 完成时调用：扫 worktree → 按 buildContractMatrix 识别的
+ * provider task，各自落 contract-artifacts/<changeName>/<taskName>/endpoints.json。
+ * @param {{ changeDir: string, specBase: string, changeName: string, worktreePath: string|null }} args
+ * @returns {string|null} 日志摘要；无 provider/无 plan/worktree 缺失时返回 null（不打扰）
+ */
+export function extractArtifactsForChange({ changeDir, specBase, changeName, worktreePath }) {
+  if (!worktreePath || !changeDir || !existsSync(changeDir)) return null
+  const planFile = join(changeDir, 'plan.md')
+  if (!existsSync(planFile)) return null
+  const contracts = buildContractMatrix(readFileSync(planFile, 'utf8'), changeDir)
+  const providers = [...new Set(contracts.map(c => c.provider))]
+  if (providers.length === 0) return null
+  let withEndpoints = 0
+  for (const taskName of providers) {
+    const r = extractProviderArtifact(changeDir, worktreePath, specBase, taskName)
+    if (r.ok && r.endpoints.length > 0) withEndpoints++
+  }
+  return `📦 契约 artifact 提取: providers=${providers.join(',')}（${withEndpoints}/${providers.length} 含端点）`
+}
+
 // ─── Execute 阶段：前端 task 开始时注入契约 ─────────────────────────────
 
 /**
@@ -184,12 +215,13 @@ export function extractProviderArtifact(changeDir, worktreePath, specBase, taskN
 export function buildConsumerInjection(changeDir, specBase, taskName, contracts, runtimeRoot) {
   // 平台模式 contract-artifacts 落 runtimeRoot；否则落 specBase/.runtime
   const artifactRoot = runtimeRoot || join(specBase, '.runtime')
+  const changeName = changeDir ? basename(changeDir) : '_unknown'
   const myContracts = contracts.filter(c => c.consumer === taskName)
   if (myContracts.length === 0) return null
 
   const parts = []
   for (const contract of myContracts) {
-    const artifactDir = join(artifactRoot, 'contract-artifacts', contract.provider)
+    const artifactDir = join(artifactRoot, 'contract-artifacts', changeName, contract.provider)
     const artifactFile = join(artifactDir, 'endpoints.json')
 
     let endpoints = []
@@ -295,15 +327,16 @@ export function buildContractFieldInjection(changeDir, taskName) {
  * verify 阶段执行 API parity check
  * @param {string} specBase - .sillyspec 目录
  * @param {string} worktreePath - worktree 路径
- * @returns {{ ok: boolean, missingBackend: Array, unusedBackend: Array, summary: string }}
+ * @returns {{ ok: boolean, missingBackend: Array, unusedBackend: Array, summary: string, backendCount: number, frontendCount: number }}
  */
-export function verifyApiParity(specBase, worktreePath, runtimeRoot) {
-  const { diffApiParity } = require('./endpoint-extractor.js')
-
+export function verifyApiParity(specBase, scanRoot, runtimeRoot, changeName = null) {
   // 平台模式 contract-artifacts 落 runtimeRoot；否则落 specBase/.runtime
   const artifactRoot = runtimeRoot || join(specBase, '.runtime')
-  // 读取所有 provider artifacts
-  const artifactBase = join(artifactRoot, 'contract-artifacts')
+  // 读取该变更的所有 provider artifacts（contract-artifacts/<changeName>/*/endpoints.json）。
+  // changeName 缺失时回退扫顶层 contract-artifacts（CLI contractScan 跨变更场景兼容）。
+  const artifactBase = changeName
+    ? join(artifactRoot, 'contract-artifacts', changeName)
+    : join(artifactRoot, 'contract-artifacts')
   const allProviderEndpoints = []
 
   if (existsSync(artifactBase)) {
@@ -325,17 +358,12 @@ export function verifyApiParity(specBase, worktreePath, runtimeRoot) {
     }
   }
 
-  // 扫描前端调用
-  if (!worktreePath || !existsSync(worktreePath)) {
-    return {
-      ok: true,
-      missingBackend: [],
-      unusedBackend: [],
-      summary: 'No worktree to scan for parity check',
-    }
+  // 扫描前端调用（scanRoot 通常 = 主工作区 cwd：verify 时代码已 apply 到主工作区）
+  if (!scanRoot || !existsSync(scanRoot)) {
+    return { ok: true, missingBackend: [], unusedBackend: [], summary: 'No scan root for parity check', backendCount: allProviderEndpoints.length, frontendCount: 0 }
   }
 
-  const frontendCalls = scanFrontendApiCalls(worktreePath)
+  const frontendCalls = scanFrontendApiCalls(scanRoot)
   const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, allProviderEndpoints)
 
   const ok = missingBackend.length === 0
@@ -347,5 +375,5 @@ export function verifyApiParity(specBase, worktreePath, runtimeRoot) {
     summary += ` | ${unusedBackend.length} backend endpoints unused by frontend`
   }
 
-  return { ok, missingBackend, unusedBackend, summary }
+  return { ok, missingBackend, unusedBackend, summary, backendCount: allProviderEndpoints.length, frontendCount: frontendCalls.length }
 }

package/src/endpoint-extractor.js

@@ -75,14 +75,96 @@ export function extractFastApiEndpoints(filePath) {
 }
 
 /**
- * 从目录递归扫描所有 Python router 文件的端点
+ * 从单个文件提取 Express（Node）路由端点。
+ * 支持 router/app.get|post|put|delete|patch("path") 与链式 router.route("path").<method>()。
+ * app.use("prefix", router) 的前缀只做同文件近似（跨文件追踪不在首版范围）。
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function extractExpressEndpoints(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const endpoints = []
+
+  // 同文件内最后一个 app.use("prefix", ...) 作为前缀近似
+  let routerPrefix = ''
+  for (const line of lines) {
+    const useMatch = line.match(/\bapp\.use\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (useMatch) routerPrefix = useMatch[1]
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const m = line.match(/\b(?:app|router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/i)
+    if (m) {
+      endpoints.push({ method: m[1].toUpperCase(), path: routerPrefix + m[2], source: filePath, line: i + 1 })
+      continue
+    }
+    const routeChain = line.match(/\.route\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (routeChain) {
+      // 链式 .route(path).get(h).put(h) —— 同行所有 method 配上 path
+      const chainPath = routerPrefix + routeChain[1]
+      for (const mm of line.matchAll(/\.(get|post|put|delete|patch)\s*\(/gi)) {
+        endpoints.push({ method: mm[1].toUpperCase(), path: chainPath, source: filePath, line: i + 1 })
+      }
+    }
+  }
+
+  return endpoints
+}
+
+/**
+ * 从单个文件提取 Spring（Java）端点。
+ * 支持 @GetMapping/@PostMapping/.../@PatchMapping 与旧式 @RequestMapping(value="path", method=RequestMethod.X)；
+ * 类级 @RequestMapping("api") 前缀合并（取文件内第一个作类前缀，近似）。
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function extractSpringEndpoints(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const endpoints = []
+
+  let classPrefix = ''
+  for (const line of lines) {
+    const cm = line.match(/@RequestMapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`]/)
+    if (cm) { classPrefix = cm[1]; break }
+  }
+
+  const methodMap = { get: 'GET', post: 'POST', put: 'PUT', delete: 'DELETE', patch: 'PATCH' }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const shortMatch = line.match(/@(Get|Post|Put|Delete|Patch)Mapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`]/i)
+    if (shortMatch) {
+      endpoints.push({ method: methodMap[shortMatch[1].toLowerCase()], path: classPrefix + shortMatch[2], source: filePath, line: i + 1 })
+      continue
+    }
+    const oldMatch = line.match(/@RequestMapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`][^)]*?method\s*=\s*RequestMethod\.(\w+)/i)
+    if (oldMatch) {
+      endpoints.push({ method: oldMatch[2].toUpperCase(), path: classPrefix + oldMatch[1], source: filePath, line: i + 1 })
+    }
+  }
+
+  return endpoints
+}
+
+/**
+ * 从目录递归扫描后端端点（多框架）。
+ * 按扩展名分派：.py→FastAPI / .js,.ts→Express / .java→Spring。
+ * 保留 excludePatterns（向后兼容 opts）；filePattern 在多框架分派下不再适用。
  * @param {string} dir
- * @param {{ filePattern?: RegExp, excludePatterns?: RegExp[] }} opts
+ * @param {{ excludePatterns?: RegExp[] }} opts
  * @returns {Array<{ method: string, path: string, source: string, line: number }>}
  */
 export function scanBackendEndpoints(dir, opts = {}) {
-  const filePattern = opts.filePattern || /(?:router|routes|api|endpoint|controller)\.py$/i
-  const excludePatterns = opts.excludePatterns || [/__pycache__/, /node_modules/, /\.venv/, /test/i]
+  const excludePatterns = opts.excludePatterns || [
+    /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^\.git$/, /^\.gradle$/,
+    /^(dist|build|target|out)$/i,
+    /test/i,
+  ]
 
   const results = []
   if (!existsSync(dir)) return results
@@ -93,9 +175,12 @@ export function scanBackendEndpoints(dir, opts = {}) {
       if (entry.isDirectory()) {
         if (excludePatterns.some(p => p.test(entry.name))) continue
         walk(full)
-      } else if (entry.isFile() && filePattern.test(entry.name)) {
+      } else if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase()
         try {
-          results.push(...extractFastApiEndpoints(full))
+          if (ext === '.py') results.push(...extractFastApiEndpoints(full))
+          else if (ext === '.js' || ext === '.ts') results.push(...extractExpressEndpoints(full))
+          else if (ext === '.java') results.push(...extractSpringEndpoints(full))
         } catch {}
       }
     }
@@ -224,6 +309,7 @@ export function normalizePath(rawPath) {
     .replace(/\$\{[^}]+\}/g, '{param}')
     .replace(/:\w+/g, '{param}')
     .replace(/\$\w+/g, '{param}')
+    .replace(/\{[^}]+\}/g, '{param}')   // Spring {planId} / FastAPI {plan_id} → {param}
 }
 
 // ─── 对账 ───────────────────────────────────────────────────────────────

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/hooks/worktree-guard.js

@@ -267,7 +267,11 @@ function queryDbFirstCell(cwd, sql) {
 }
 
 export { queryDbFirstCell as _queryDbFirstCellForTest };
-
+export {
+  matchReadonlyWhitelist as _matchReadonlyWhitelistForTest,
+  matchDangerBlacklist as _matchDangerBlacklistForTest,
+  isSingleCommandReadonly as _isSingleCommandReadonlyForTest,
+};
 /**
  * 从 sillyspec.db 读取 currentStage
  * 优先级：gate-status.json > sillyspec.db
@@ -472,7 +476,11 @@ function isSingleCommandReadonly(cmd, extraReadonlyCommands = []) {
     // node/npm/npx 需要进一步检查子命令
     if (cmdName === 'node' || cmdName === 'npm' || cmdName === 'npx') {
       const rest = parts.slice(1).join(' ')
-      return rest.includes('--version') || rest.includes('-v') && parts.length <= 3 || rest === 'run test' || rest.startsWith('test')
+      // 仅纯版本查询（`npm --version` / `node -v`，恰好两段）放行。
+      // 不能用 rest.includes('--version')：`npx any-pkg --version` 会执行 any-pkg，
+      // 旧实现因 && 优先级高于 || 使 --version 分支无长度约束，可绕过只读白名单。
+      const isBareVersionQuery = parts.length === 2 && (parts[1] === '--version' || parts[1] === '-v')
+      return isBareVersionQuery || rest === 'run test' || rest.startsWith('test')
     }
     return true
   }
@@ -531,8 +539,12 @@ function isSingleCommandDangerous(cmd) {
  * @returns {string[]}
  */
 function splitCommandParts(command) {
-  // 按管道和链式操作符拆分
-  return command.split(/(?:\|\|&&|&&|\|)/g).map(s => s.trim()).filter(Boolean)
+  // 按管道、链式操作符、语句分隔、重定向拆分。
+  // 必须覆盖 `||`/`&&`/`;`/`&`/`|`/`>`/`<`：否则 `echo foo; rm -rf x`、
+  // `cat f > /etc/passwd` 会被当成单一片段，首命令命中只读白名单 → 整条放行，
+  // 后半段的危险/写入操作绕过只读白名单与危险黑名单两道门。
+  // （`$(...)`/反引号命令替换需 shell-token 化，与零依赖风格冲突，暂不覆盖。）
+  return command.split(/\|\||&&|;|&|\||>|</g).map(s => s.trim()).filter(Boolean)
 }
 
 /**

package/src/index.js

@@ -7,7 +7,9 @@
  * 状态管理通过 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 { execSync } from 'child_process';
 import { cmdInit, getVersion } from './init.js';
 import { ProgressManager, resolvePlatformSpecDir } from './progress.js';
 import { detectLocalYaml } from './local-detect.js';
@@ -185,7 +187,6 @@ async function main() {
   function resolveEffectiveDir(baseDir) {
     if (existsSync(join(baseDir, '.sillyspec'))) return baseDir
     try {
-      const { execSync } = require('child_process')
       const gitRoot = execSync('git rev-parse --show-toplevel', {
         cwd: baseDir, encoding: 'utf8', timeout: 5000
       }).trim()
@@ -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) {
@@ -217,44 +225,6 @@ export class ProgressManager {
     };
   }
 
-  async writeGlobal(cwd, data) {
-    // SQL: UPDATE project + UPSERT changes status
-    const db = await this._ensureDB(cwd);
-    db.transaction((sqlDb) => {
-      const now = new Date().toISOString();
-
-      // UPSERT project 行
-      sqlDb.run(`
-        INSERT INTO project (id, name, schema_version, created_at, updated_at)
-        VALUES (1, ?, ?, ?, ?)
-        ON CONFLICT(id) DO UPDATE SET
-          name = excluded.name,
-          schema_version = excluded.schema_version,
-          updated_at = excluded.updated_at
-      `, [data.project || '', data._version || CURRENT_VERSION, now, now]);
-
-      // 同步 changes 表：确保 activeChanges 列表中的变更存在且为 active，
-      // 不在列表中的设为 archived
-      const activeChanges = data.activeChanges || [];
-      for (const cn of activeChanges) {
-        sqlDb.run(`
-          INSERT INTO changes (name, status, created_at, last_active)
-          VALUES (?, 'active', ?, ?)
-          ON CONFLICT(name) DO UPDATE SET status = 'active', last_active = excluded.last_active
-        `, [cn, now, now]);
-      }
-      if (activeChanges.length > 0) {
-        sqlDb.run(`
-          UPDATE changes SET status = 'archived'
-          WHERE status = 'active' AND name NOT IN (${activeChanges.map(() => '?').join(',')})
-        `, activeChanges);
-      } else {
-        // 没有活跃变更，将所有 active 归档
-        sqlDb.run("UPDATE changes SET status = 'archived' WHERE status = 'active'");
-      }
-    });
-  }
-
   // ── 变更级别状态 ──
 
   /**
@@ -650,20 +620,38 @@ export class ProgressManager {
       console.error(`❌ 变更 ${newName} 已存在`);
       return;
     }
-    // 重命名目录
+    // 先更新 DB，再重命名目录；FS 失败则回滚 DB，避免"目录已改名但 DB 旧名"的孤儿
+    // （旧实现 FS-first 无补偿：renameSync 成功后 DB transaction 抛 EPERM/EBUSY 会让
+    //  目录已是 newName、DB 仍是 oldName，read(两名) 都失联且无自动恢复）。
     const oldDir = this._changePath(cwd, oldName);
     const newDir = this._changePath(cwd, newName);
+    const now = new Date().toISOString();
+    try {
+      db.transaction((sqlDb) => {
+        sqlDb.run(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`, [newName, now, oldName]);
+      });
+    } catch (e) {
+      console.error(`❌ 重命名失败：更新数据库时出错（${e.message}）`);
+      return;
+    }
+    let renamed = true;
     if (existsSync(oldDir)) {
-      renameSync(oldDir, newDir);
+      try {
+        renameSync(oldDir, newDir);
+      } catch (e) {
+        renamed = false;
+        // FS 重命名失败：回滚 DB 恢复 oldName，保持 DB 与目录一致
+        try {
+          db.transaction((sqlDb) => {
+            sqlDb.run(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`, [oldName, now, newName]);
+          });
+        } catch {}
+        console.error(`❌ 重命名失败：移动目录出错（${e.message}），已回滚数据库`);
+      }
     } else {
       mkdirSync(newDir, { recursive: true });
     }
-    // 更新 DB
-    const now = new Date().toISOString();
-    db.transaction((sqlDb) => {
-      sqlDb.run(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`, [newName, now, oldName]);
-    });
-    console.log(`✅ 变更已重命名：${oldName} → ${newName}`);
+    if (renamed) console.log(`✅ 变更已重命名：${oldName} → ${newName}`);
   }
 
   /**
@@ -1064,7 +1052,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 +1654,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 +1852,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);
     }