sillyspec 3.20.4 → 3.20.5

package/docs/sillyspec/file-lifecycle.md

@@ -1,7 +1,7 @@
 ---
 author: qinyi
 created_at: 2026-05-31 11:00:00
-updated_at: 2026-06-19 15:00:00
+updated_at: 2026-07-01 15:00:00
 ---
 
 # SillySpec 文件生命周期
@@ -73,6 +73,9 @@ updated_at: 2026-06-19 15:00:00
 
 `init.js` 会把 `.sillyspec/.runtime/`、`.sillyspec/local.yaml`、`.sillyspec/codebase/SCAN-RAW.md` 追加到 `.gitignore`。
 
+> **平台模式残留清理边界**（`init.js` `cleanupRuntimeResidue`，由 `run.js` 启动时复用）：
+> 当 `specRoot` 指向外部、源码目录的 `.sillyspec/` 含真实资产（`changes/`/`projects/`/`sillyspec.db`）时，只清理运行时残留，**不整删 `.runtime/`**。清理白名单保留权威状态：`worktrees/`、`sillyspec.db`、`global.json`、`gate-status.json`、`contract-artifacts/`、`execute-runs/`；其余子项（`artifacts/`、`scan-runs/`、`scan-projects.json`、`user-inputs.md`、`postcheck-result.json` 等可重建缓存）逐项删除，`local.yaml`、`codebase/` 整删。未知子项默认保留（安全侧倾斜）。
+
 ## 主要文件流
 
 ```text
@@ -122,4 +125,7 @@ quick
 - `archive` 的目录移动已经由 `run.js` 在第 4 步 `--confirm` 时执行；未带 `--confirm` 会回退该步骤并提示补参。
 - scan 第 10 步「Extract Project Knowledge」把长期有效的项目知识写入 `.sillyspec/knowledge/`（`conventions.md`/`patterns.md`/`known-issues.md` + 更新 `INDEX.md`）；`scan-postcheck.js` 校验产物（INDEX.md 存在、引用文件真实存在）。
 - execute 启动时由 `knowledge-match.js` 按 plan.md 的 task 关键词匹配知识库，命中报告注入 prompt 并写 `.runtime/knowledge-hit-report.json`。
+- 平台模式残留清理只删缓存、保留权威状态（`worktrees/`、`sillyspec.db`、`global.json`、`gate-status.json`、`contract-artifacts/`、`execute-runs/`），不再整删 `.runtime/`——否则 worktree meta 被清掉会导致 `depsStatus` 恒为 unknown、`branch already exists` 死循环、`worktree doctor` orphan 误判。
+- plan→execute Contract 校验（`parseWavesFromPlan`）只解析 `## Wave N` 段内的 `- [ ] task-XX:` 行；遇到非 Wave 标题行（`## 自检` 等）即退出当前 Wave 段，避免自检 `- [x]` checkbox 被误当 task 定义。
+- `executePlanPostcheck` 的 `resolveChangeDir` 复用 `run.js` 模块内本地函数，不从 `./modules.js` 导入（该模块未导出此函数）。
 - Revision v1：`stages` 表新增 `revision`/`reopened_from_step`/`reopened_at`/`stale_reason` 列；阶段新增 `revising`/`stale` 状态；`sillyspec run <stage> --reopen --from-step <n>` 重开已完成阶段、级联标记下游 stale；`.runtime/postcheck-result.json` 由 `scan-postcheck.js` 的 `writeStructuredResult` 落盘（本地写 `specDir/.runtime`，平台写 `runtimeRoot/scan-runs/<id>`）。

package/package.json

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

package/src/init.js

@@ -8,6 +8,48 @@ import chalk from 'chalk';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+// ── .runtime/ 残留清理（平台模式防源码污染） ──
+// 平台模式（specRoot 指向外部）下，源码目录的 .sillyspec/.runtime/ 是旧残留，
+// 应让 specRoot 成为唯一运行时根。但若源码目录的 .sillyspec/ 本身就是该项目
+// 的 specDir（含真实资产），其 .runtime/ 里的 worktrees/、sillyspec.db、
+// global.json、gate-status.json 是真实工作状态，整删会摧毁 worktree meta、
+// 导致 depsStatus 恒为 unknown、branch already exists 死循环。
+// 详见 docs/sillyspec/runtime-cleanup-destroys-worktree-meta.md
+//
+// 策略：白名单保留权威状态，逐项删除可重建的缓存子项；未知子项默认保留（安全侧倾斜）。
+const RUNTIME_KEEP = new Set([
+  'worktrees',          // worktree 目录 + meta.json（worktree.js:17）
+  'sillyspec.db',       // SQLite 进度库（权威状态源，progress.js:7）
+  'global.json',        // 项目名/活跃变更缓存（progress.js:8）
+  'gate-status.json',   // worktree-guard 门禁状态（progress.js:9）
+  'contract-artifacts', // execute endpoint 契约（verify 阶段读取）
+  'execute-runs',       // task review 结果（task-review.js）
+]);
+
+/**
+ * 清理 .sillyspec/ 下的运行时残留，保留权威状态。
+ * 同时清理 local.yaml、codebase/（这些非权威，整删安全）。
+ * @param {string} legacyDir - 源码目录的 .sillyspec/ 路径
+ */
+export function cleanupRuntimeResidue(legacyDir) {
+  // local.yaml、codebase/ 非权威，整删
+  for (const residue of ['local.yaml', 'codebase']) {
+    const p = join(legacyDir, residue);
+    if (existsSync(p)) { try { rmSync(p, { recursive: true, force: true }) } catch {} }
+  }
+  // .runtime/ 逐项清理，白名单保留
+  const runtimeDir = join(legacyDir, '.runtime');
+  if (existsSync(runtimeDir)) {
+    let entries = [];
+    try { entries = readdirSync(runtimeDir, { withFileTypes: true }); } catch {}
+    for (const entry of entries) {
+      if (RUNTIME_KEEP.has(entry.name)) continue;
+      const p = join(runtimeDir, entry.name);
+      try { rmSync(p, { recursive: true, force: true }) } catch {}
+    }
+  }
+}
+
 // ── 递归复制目录 ──
 function copyDirSync(src, dst) {
   mkdirSync(dst, { recursive: true });
@@ -130,11 +172,8 @@ async function doInstall(projectDir, tools, subprojects = [], specDir = null) {
       // 真实资产存在：拒绝整体删除，仅清理运行时残留
       console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产（changes/、projects/ 或 sillyspec.db）。');
       console.error('   该项目似乎本身就用 SillySpec 管理。如需改用外部 spec 目录，请先手动迁移/备份。');
-      console.error('   本次仅清理运行时残留（.runtime/、local.yaml、codebase/）。');
-      for (const residue of ['.runtime', 'local.yaml', 'codebase']) {
-        const p = join(legacyDir, residue);
-        if (existsSync(p)) { try { rmSync(p, { recursive: true, force: true }) } catch {} }
-      }
+      console.error('   本次仅清理运行时残留（.runtime/ 缓存、local.yaml、codebase/），保留 worktrees 与进度状态。');
+      cleanupRuntimeResidue(legacyDir);
     } else {
       // 无真实资产：确属旧版本残留，安全删除
       try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}

package/src/run.js

@@ -1131,8 +1131,10 @@ async function executeScanPostcheck(cwd, platformOpts, scanProfile) {
  * Plan postcheck 的执行代理：委托给 plan-postcheck.js 模块
  */
 async function executePlanPostcheck(cwd, platformOpts, progress) {
+  // resolveChangeDir 是本模块 line 505 定义的本地函数；历史上曾误从 ./modules.js
+  // 导入（该模块未导出此函数，得到 undefined），导致 plan-postcheck.js:388 抛
+  // "resolveChangeDir is not a function"。详见 docs/sillyspec/plan-postcheck-resolvechangedir-not-a-function.md
   const { executePlanPostcheck: runPostcheck } = await import('./stages/plan-postcheck.js')
-  const { resolveChangeDir } = await import('./modules.js')
   await runPostcheck({
     cwd,
     specRoot: platformOpts?.specRoot,
@@ -1292,11 +1294,9 @@ export async function runCommand(args, cwd, specDir = null) {
       const hasDb = existsSync(join(legacyDir, 'sillyspec.db'));
 
       if (hasChanges || hasProjects || hasDb) {
-        console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产。仅清理运行时残留。');
-        for (const residue of ['.runtime', 'local.yaml', 'codebase']) {
-          const p = join(legacyDir, residue);
-          if (existsSync(p)) { try { rmSync(p, { recursive: true, force: true }) } catch {} }
-        }
+        console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产。仅清理运行时残留，保留 worktrees 与进度状态。');
+        const { cleanupRuntimeResidue } = await import('./init.js')
+        cleanupRuntimeResidue(legacyDir);
       } else {
         try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
       }

package/src/stages/execute.js

@@ -370,6 +370,15 @@ function parseWavesFromPlan(planContent) {
       continue
     }
 
+    // 遇到任何非 Wave 的标题行（## 自检、## 备注 等）时退出当前 Wave 段，
+    // 避免「## 自检」段里的 - [x] checkbox 被误当 task 定义解析（导致
+    // Contract 校验报 task id 重复/不连续）。详见 docs/sillyspec/plan-postcheck-self-check-checkbox-false-dup.md
+    if (/^#+\s/.test(line)) {
+      currentWave = null
+      currentTask = null
+      continue
+    }
+
     if (!currentWave) continue
 
     const taskMatch = line.match(/^[-*]\s*\[[ x]\]\s*(.+)/)

package/src/stages/plan-postcheck.js

@@ -470,6 +470,13 @@ export async function executePlanPostcheck(context) {
               currentWaveTasks = []
               continue
             }
+            // 非 Wave 标题行（## 自检 等）退出当前 Wave 段，避免自检 checkbox
+            // 被混入 task 列表导致 Wave 结构比对误判。
+            if (/^#+\s/.test(line)) {
+              if (currentWaveTasks) existingWaves.push(currentWaveTasks)
+              currentWaveTasks = null
+              continue
+            }
             const tm = line.match(/^[-*]\s*\[[ x]\]\s*task-(\d+)/i)
             if (tm && currentWaveTasks) {
               currentWaveTasks.push(`task-${tm[1]}`)

package/test/plan-execute-contract.test.mjs

@@ -318,9 +318,36 @@ console.log('\n--- Plan Postcheck: task id 不连续失败 ---')
   assert(!result.ok, 'id 不连续应不通过 postcheck')
 }
 
+// ─────────────────────────────────────────
+// Bug C 回归: 「## 自检」段的 - [x] checkbox 不应被解析为 task
+// 详见 docs/sillyspec/plan-postcheck-self-check-checkbox-false-dup.md
+// ─────────────────────────────────────────
+console.log('\n--- Bug C 回归: 自检段 checkbox 不误解析 ---')
+{
+  const plan = `# Plan
+
+## Wave 1
+- [ ] task-01: 建立 schema
+- [ ] task-02: 接口实现
+
+## Wave 2
+- [ ] task-03: 前端对接
+- [ ] task-04: 集成测试
+
+## 自检
+- [x] 每个 task 有编号(task-01~04),总数 4(≤15)
+- [x] 无泛泛风险(转为具体验收条目与 task-04/task-06 等)
+`
+  const result = validatePlanForExecute(plan)
+  assert(result.ok, `自检段含 - [x] 不应误报，errors: ${result.errors.join('; ')}`)
+  assert(result.tasks.length === 4, `应只解析 4 个 task，实际 ${result.tasks.length}（自检 checkbox 被误纳入）`)
+  const ids = result.tasks.map(t => t.index).sort((a, b) => a - b)
+  assert(JSON.stringify(ids) === JSON.stringify([1, 2, 3, 4]), `task id 应为 1-4，实际 ${ids}`)
+}
+
 // ── 结果 ──
 console.log(`\n${'='.repeat(50)}`)
-console.log(`✅ 通过: ${12 - failed}  ❌ 失败: ${failed}`)
+console.log(`✅ 通过: ${13 - failed}  ❌ 失败: ${failed}`)
 if (failures.length > 0) {
   console.log(`失败项:`)
   failures.forEach(f => console.log(`  - ${f}`))

package/test/runtime-cleanup-keeps-worktree.test.mjs

@@ -0,0 +1,107 @@
+/**
+ * Bug A 回归：清理逻辑不得摧毁 worktree meta / 进度状态
+ *
+ * 平台模式（specRoot 指向外部）下，源码目录 .sillyspec/ 含真实资产时，
+ * cleanupRuntimeResidue 应只清缓存，保留 worktrees/、sillyspec.db、
+ * global.json、gate-status.json、contract-artifacts/、execute-runs/。
+ * 详见 docs/sillyspec/runtime-cleanup-destroys-worktree-meta.md
+ */
+import { cleanupRuntimeResidue } from '../src/init.js'
+import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'fs'
+import { join } from 'path'
+import os from 'os'
+
+let failed = 0
+const failures = []
+function assert(condition, msg) {
+  if (!condition) { failed++; failures.push(msg); console.log(`  ❌ FAIL: ${msg}`) }
+  else console.log(`  ✅ PASS: ${msg}`)
+}
+
+function makeTempLegacy() {
+  const root = join(os.tmpdir(), `sillyspec-bugA-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  const legacyDir = join(root, '.sillyspec')
+  mkdirSync(join(legacyDir, '.runtime'), { recursive: true })
+  return { root, legacyDir }
+}
+
+console.log('=== Bug A 回归: cleanupRuntimeResidue 保留权威状态 ===\n')
+
+// ── Case 1: 权威状态全部保留 ──
+console.log('--- Case 1: worktrees / db / global.json / gate-status 保留 ---')
+{
+  const { root, legacyDir } = makeTempLegacy()
+  const runtime = join(legacyDir, '.runtime')
+  // 权威状态
+  mkdirSync(join(runtime, 'worktrees', 'my-change'), { recursive: true })
+  writeFileSync(join(runtime, 'worktrees', 'my-change', 'meta.json'), '{"depsStatus":"installed"}')
+  writeFileSync(join(runtime, 'sillyspec.db'), 'sqlite-bytes')
+  writeFileSync(join(runtime, 'global.json'), '{"projectName":"x"}')
+  writeFileSync(join(runtime, 'gate-status.json'), '{}')
+  mkdirSync(join(runtime, 'contract-artifacts'), { recursive: true })
+  writeFileSync(join(runtime, 'contract-artifacts', 'foo.json'), '{}')
+  mkdirSync(join(runtime, 'execute-runs'), { recursive: true })
+  // 可删缓存
+  mkdirSync(join(runtime, 'artifacts'), { recursive: true })
+  mkdirSync(join(runtime, 'scan-runs'), { recursive: true })
+  writeFileSync(join(runtime, 'scan-projects.json'), '{}')
+  writeFileSync(join(runtime, 'user-inputs.md'), 'x')
+  writeFileSync(join(runtime, 'postcheck-result.json'), '{}')
+  // local.yaml / codebase（非权威，应删）
+  writeFileSync(join(legacyDir, 'local.yaml'), 'x')
+  mkdirSync(join(legacyDir, 'codebase'), { recursive: true })
+
+  cleanupRuntimeResidue(legacyDir)
+
+  assert(existsSync(join(runtime, 'worktrees', 'my-change', 'meta.json')), 'worktrees/meta.json 应保留')
+  assert(existsSync(join(runtime, 'sillyspec.db')), 'sillyspec.db 应保留')
+  assert(existsSync(join(runtime, 'global.json')), 'global.json 应保留')
+  assert(existsSync(join(runtime, 'gate-status.json')), 'gate-status.json 应保留')
+  assert(existsSync(join(runtime, 'contract-artifacts', 'foo.json')), 'contract-artifacts/ 应保留')
+  assert(existsSync(join(runtime, 'execute-runs')), 'execute-runs/ 应保留')
+  assert(!existsSync(join(runtime, 'artifacts')), 'artifacts/ 缓存应删除')
+  assert(!existsSync(join(runtime, 'scan-runs')), 'scan-runs/ 缓存应删除')
+  assert(!existsSync(join(runtime, 'scan-projects.json')), 'scan-projects.json 缓存应删除')
+  assert(!existsSync(join(runtime, 'user-inputs.md')), 'user-inputs.md 缓存应删除')
+  assert(!existsSync(join(legacyDir, 'local.yaml')), 'local.yaml 应删除')
+  assert(!existsSync(join(legacyDir, 'codebase')), 'codebase/ 应删除')
+
+  rmSync(root, { recursive: true, force: true })
+}
+
+// ── Case 2: worktree meta 内容不被破坏（depsStatus 不丢） ──
+console.log('\n--- Case 2: 清理后 worktree meta 内容完整 ---')
+{
+  const { root, legacyDir } = makeTempLegacy()
+  const runtime = join(legacyDir, '.runtime')
+  mkdirSync(join(runtime, 'worktrees', 'c1'), { recursive: true })
+  const metaPath = join(runtime, 'worktrees', 'c1', 'meta.json')
+  const original = '{"depsStatus":"installed","worktreePath":"/x","branch":"sillyspec/c1"}'
+  writeFileSync(metaPath, original)
+
+  cleanupRuntimeResidue(legacyDir)
+
+  assert(existsSync(metaPath), 'meta.json 应仍存在')
+  const read = readFileSync(metaPath, 'utf8')
+  assert(read === original, 'meta.json 内容应未被改写')
+
+  rmSync(root, { recursive: true, force: true })
+}
+
+// ── Case 3: .runtime/ 不存在时不报错 ──
+console.log('\n--- Case 3: 无 .runtime/ 时安全无副作用 ---')
+{
+  const { root, legacyDir } = makeTempLegacy()
+  rmSync(join(legacyDir, '.runtime'), { recursive: true, force: true })
+  let threw = false
+  try { cleanupRuntimeResidue(legacyDir) } catch { threw = true }
+  assert(!threw, '无 .runtime/ 时不应抛错')
+  rmSync(root, { recursive: true, force: true })
+}
+
+// ── 结果 ──
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${28 - failed}  ❌ 失败: ${failed}`)
+if (failures.length > 0) { console.log('失败项:'); failures.forEach(f => console.log(`  - ${f}`)) }
+console.log('='.repeat(50))
+if (failed > 0) process.exit(1)