sillyspec 3.20.3 → 3.20.5

package/test/worktree-deps-provision.test.mjs

@@ -0,0 +1,148 @@
+/**
+ * worktree-deps-provision 测试
+ * 覆盖 FR-01/02/03/05：lockfileHash + provisionDeps（junction 快路径 / install 兜底判定 / generic→n/a）
+ * change 2026-06-28-worktree-deps-provision
+ */
+import { provisionDeps, lockfileHash } from '../src/worktree-deps.js'
+import { mkdtempSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+let failed = 0
+let passed = 0
+const failures = []
+function assert(cond, msg) {
+  if (cond) { passed++; console.log(`  ✅ PASS: ${msg}`) }
+  else { failed++; failures.push(msg); console.log(`  ❌ FAIL: ${msg}`) }
+}
+
+const tmpDirs = []
+function mkTmp(prefix) {
+  const d = mkdtempSync(join(tmpdir(), `wtdeps-${prefix}-`))
+  tmpDirs.push(d)
+  return d
+}
+function cleanup() {
+  for (const d of tmpDirs) {
+    try { rmSync(d, { recursive: true, force: true }) } catch {}
+  }
+}
+
+console.log('=== worktree-deps-provision 测试 ===\n')
+
+// ── lockfileHash ──
+console.log('--- lockfileHash ---')
+{
+  const d = mkTmp('lh')
+  assert(lockfileHash(d) === null, '空目录返回 null')
+  writeFileSync(join(d, 'pnpm-lock.yaml'), 'lockversion: 6.0\npackages: []\n')
+  const h1 = lockfileHash(d)
+  assert(typeof h1 === 'string' && h1.length === 16, `pnpm-lock 返回 16 位 hash: ${h1}`)
+
+  const d2 = mkTmp('lh2')
+  writeFileSync(join(d2, 'package-lock.json'), '{"lockfileVersion":3}')
+  const h2 = lockfileHash(d2)
+  assert(typeof h2 === 'string' && h2.length === 16, `package-lock 返回 hash: ${h2}`)
+  assert(h1 !== h2, '不同 lockfile 内容产生不同 hash')
+
+  const d3 = mkTmp('lh3')
+  writeFileSync(join(d3, 'yarn.lock'), '# yarn lock v1\n')
+  assert(typeof lockfileHash(d3) === 'string', 'yarn.lock 返回 hash')
+
+  const d4 = mkTmp('lh4')
+  writeFileSync(join(d4, 'package.json'), '{"name":"x"}')
+  assert(typeof lockfileHash(d4) === 'string', '无 lockfile 时回退 hash package.json')
+
+  // 一致性：相同内容相同 hash
+  const d5 = mkTmp('lh5')
+  writeFileSync(join(d5, 'pnpm-lock.yaml'), 'lockversion: 6.0\npackages: []\n')
+  assert(lockfileHash(d5) === h1, '相同 lockfile 内容产生相同 hash（快路径判定基础）')
+}
+
+// ── provisionDeps: generic → n/a ──
+console.log('\n--- provisionDeps: generic / 无依赖 → n/a ---')
+{
+  const wt = mkTmp('gen-wt')
+  const main = mkTmp('gen-main')
+  const r = provisionDeps(wt, main, {})
+  assert(r.depsStatus === 'n/a', `无 package.json/lockfile 的目录 → n/a（实际 ${r.depsStatus}）`)
+  assert(!existsSync(join(wt, 'node_modules')), 'n/a 不创建 node_modules')
+}
+
+// ── provisionDeps: nodejs junction 快路径（lockfile 一致）──
+console.log('\n--- provisionDeps: nodejs lockfile 一致 → linked (junction/symlink) ---')
+{
+  const main = mkTmp('link-main')
+  const wt = mkTmp('link-wt')
+  // 主 checkout：有 node_modules + lockfile
+  mkdirSync(join(main, 'node_modules'))
+  writeFileSync(join(main, 'node_modules', '.placeholder'), 'x')
+  const lockContent = 'lockversion: 6.0\npackages: []\n'
+  writeFileSync(join(main, 'package-lock.json'), lockContent)
+  writeFileSync(join(main, 'package.json'), '{"name":"main","scripts":{}}')
+  // worktree：相同 lockfile（hash 一致）+ package.json
+  writeFileSync(join(wt, 'package-lock.json'), lockContent)
+  writeFileSync(join(wt, 'package.json'), '{"name":"wt","scripts":{}}')
+
+  const r = provisionDeps(wt, main, {})
+  assert(r.depsStatus === 'linked', `lockfile 一致 → linked（实际 ${r.depsStatus}）`)
+  assert(['junction', 'symlink', 'install'].includes(r.depsMethod), `depsMethod 合法（${r.depsMethod}）`)
+  assert(r.depsSource === 'main-checkout', `depsSource=main-checkout（${r.depsSource}）`)
+  assert(existsSync(join(wt, 'node_modules')), 'worktree/node_modules 已创建（junction/symlink）')
+  assert(existsSync(join(wt, 'node_modules', '.placeholder')), 'junction 指向 main 的内容可访问')
+  assert(typeof r.depsLockHash === 'string', 'depsLockHash 已记录')
+}
+
+// ── provisionDeps: lockfile 不一致 → 走 install 兜底（不验证真实 install，只验证不走 linked）──
+console.log('\n--- provisionDeps: lockfile 不一致 → 不走 linked 快路径 ---')
+{
+  const main = mkTmp('mis-main')
+  const wt = mkTmp('mis-wt')
+  mkdirSync(join(main, 'node_modules'))
+  writeFileSync(join(main, 'package-lock.json'), 'lockversion-A')
+  writeFileSync(join(main, 'package.json'), '{"name":"main"}')
+  writeFileSync(join(wt, 'package-lock.json'), 'lockversion-B-DIFFERENT') // 不一致
+  writeFileSync(join(wt, 'package.json'), '{"name":"wt"}')
+
+  const r = provisionDeps(wt, main, {})
+  // lockfile 不一致 → 不会 linked；会尝试 install（真实 install 在 CI 可能失败/超时）
+  assert(r.depsStatus !== 'linked', `lockfile 不一致时不应 linked（实际 ${r.depsStatus}）`)
+  assert(['installed', 'failed'].includes(r.depsStatus), `兜底为 installed 或 failed（实际 ${r.depsStatus}）`)
+  // install 失败时应带 depsError
+  if (r.depsStatus === 'failed') {
+    assert(typeof r.depsError === 'string' && r.depsError.length > 0, 'failed 带 depsError 信息')
+  }
+}
+
+// ── provisionDeps: main 无 node_modules → 不走 linked ──
+console.log('\n--- provisionDeps: main 无 node_modules → 不走 linked ---')
+{
+  const main = mkTmp('nomain-main')
+  const wt = mkTmp('nomain-wt')
+  const lockContent = 'same-lock\n'
+  writeFileSync(join(main, 'package-lock.json'), lockContent)
+  writeFileSync(join(main, 'package.json'), '{"name":"main"}')
+  writeFileSync(join(wt, 'package-lock.json'), lockContent)
+  writeFileSync(join(wt, 'package.json'), '{"name":"wt"}')
+  // main 无 node_modules
+
+  const r = provisionDeps(wt, main, {})
+  assert(r.depsStatus !== 'linked', `main 无 node_modules 时不应 linked（实际 ${r.depsStatus}）`)
+}
+
+// ── provisionDeps: maven/gradle 推断（无 node_modules，验证不崩）──
+console.log('\n--- provisionDeps: 非 nodejs 项目类型不崩 ---')
+{
+  const wt = mkTmp('maven-wt')
+  writeFileSync(join(wt, 'pom.xml'), '<project></project>')
+  const r = provisionDeps(wt, mkTmp('maven-main'), {})
+  assert(['installed', 'failed'].includes(r.depsStatus), `maven 项目返回 installed/failed（${r.depsStatus}，mvn 可能不可用）`)
+}
+
+cleanup()
+
+console.log(`\n==================================================`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(failed === 0 ? '全部通过' : `❌ 失败项: ${failures.join('; ')}`)
+console.log(`==================================================`)
+process.exit(failed === 0 ? 0 : 1)

package/test/worktree-guard.test.mjs

@@ -0,0 +1,136 @@
+import assert from 'node:assert/strict'
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { shouldBlock } from '../src/hooks/worktree-guard.js'
+
+const root = join(tmpdir(), `sillyspec-guard-test-${Date.now()}`)
+const changeName = '2026-06-04-guard-test'
+const runtimeDir = join(root, '.sillyspec', '.runtime')
+const registeredWorktree = join(runtimeDir, 'worktrees', changeName)
+const unregisteredWorktree = join(runtimeDir, 'worktrees', 'other-change')
+
+mkdirSync(registeredWorktree, { recursive: true })
+mkdirSync(unregisteredWorktree, { recursive: true })
+writeFileSync(join(runtimeDir, 'gate-status.json'), JSON.stringify({
+  stage: 'execute',
+  changes: [changeName],
+  updatedAt: new Date().toISOString(),
+}, null, 2))
+writeFileSync(join(registeredWorktree, 'meta.json'), JSON.stringify({
+  changeName,
+  worktreePath: registeredWorktree,
+  mode: 'worktree',
+}, null, 2))
+
+try {
+  assert.equal(
+    shouldBlock({ tool: 'Write', filePath: join(registeredWorktree, 'src', 'ok.js'), cwd: root }).blocked,
+    false,
+    'registered worktree writes should be allowed'
+  )
+
+  assert.equal(
+    shouldBlock({ tool: 'Bash', command: 'npm run build', cwd: registeredWorktree }).blocked,
+    false,
+    'bash commands from a registered worktree cwd should be allowed'
+  )
+
+  assert.equal(
+    shouldBlock({ tool: 'Write', filePath: join(unregisteredWorktree, 'src', 'blocked.js'), cwd: root }).blocked,
+    true,
+    'unregistered worktree storage writes should be blocked'
+  )
+
+  assert.equal(
+    shouldBlock({ tool: 'Write', filePath: join(root, '.sillyspec', 'docs', 'note.md'), cwd: root }).blocked,
+    false,
+    'ordinary .sillyspec docs should remain writable'
+  )
+
+  writeFileSync(join(runtimeDir, 'gate-status.json'), JSON.stringify({
+    stage: 'scan',
+    changes: [changeName],
+    updatedAt: new Date().toISOString(),
+  }, null, 2))
+  writeFileSync(join(runtimeDir, 'scan-guard.json'), JSON.stringify({
+    sourceCommit: 'new-head',
+    startedAt: '2026-06-16T10:00:00.000Z',
+    forceRescan: false,
+  }, null, 2))
+  const scanDoc = join(root, '.sillyspec', 'docs', 'app', 'scan', 'ARCHITECTURE.md')
+  mkdirSync(join(root, '.sillyspec', 'docs', 'app', 'scan'), { recursive: true })
+  writeFileSync(scanDoc, [
+    '---',
+    'source_commit: old-head',
+    'updated_at: 2026-06-16T09:00:00.000Z',
+    '---',
+    '# Architecture',
+    '',
+  ].join('\n'))
+  assert.equal(
+    shouldBlock({ tool: 'Write', filePath: scanDoc, cwd: root }).blocked,
+    true,
+    'scan overwrite should block stale source_commit without --force-rescan'
+  )
+  writeFileSync(join(runtimeDir, 'scan-guard.json'), JSON.stringify({
+    sourceCommit: 'new-head',
+    startedAt: '2026-06-16T10:00:00.000Z',
+    forceRescan: true,
+  }, null, 2))
+  assert.equal(
+    shouldBlock({ tool: 'Write', filePath: scanDoc, cwd: root }).blocked,
+    false,
+    'scan overwrite should allow stale source_commit with --force-rescan'
+  )
+  const externalSpec = join(root, 'external-spec')
+  const externalScanDoc = join(externalSpec, 'docs', 'app', 'scan', 'ARCHITECTURE.md')
+  mkdirSync(join(externalSpec, '.runtime'), { recursive: true })
+  mkdirSync(join(externalSpec, 'docs', 'app', 'scan'), { recursive: true })
+  writeFileSync(join(externalSpec, '.runtime', 'scan-guard.json'), JSON.stringify({
+    sourceCommit: 'external-new-head',
+    startedAt: '2026-06-16T10:00:00.000Z',
+    forceRescan: false,
+  }, null, 2))
+  writeFileSync(externalScanDoc, [
+    '---',
+    'source_commit: external-old-head',
+    'updated_at: 2026-06-16T09:00:00.000Z',
+    '---',
+    '# Architecture',
+    '',
+  ].join('\n'))
+  assert.equal(
+    shouldBlock({ tool: 'Write', filePath: externalScanDoc, cwd: root }).blocked,
+    true,
+    'external specRoot scan overwrite should read specRoot/.runtime/scan-guard.json'
+  )
+
+  rmSync(join(runtimeDir, 'gate-status.json'), { force: true })
+  writeFileSync(join(root, '.sillyspec', 'local.yaml'), [
+    'worktreeHook:',
+    '  readonlyCommands:',
+    '    - custom-read',
+    '',
+  ].join('\n'))
+  assert.equal(
+    shouldBlock({ tool: 'Bash', command: 'custom-read status', cwd: root }).blocked,
+    false,
+    '.sillyspec/local.yaml readonlyCommands should extend the bash whitelist'
+  )
+
+  writeFileSync(join(runtimeDir, 'gate-status.json'), JSON.stringify({
+    stage: 'quick',
+    changes: [changeName],
+    updatedAt: new Date().toISOString(),
+  }, null, 2))
+  assert.equal(
+    shouldBlock({ tool: 'Write', filePath: join(root, 'src', 'quick.js'), cwd: root }).blocked,
+    false,
+    'quick writes should still be allowed in the main workspace'
+  )
+
+  console.log('✅ worktree guard regression checks passed')
+} finally {
+  rmSync(root, { recursive: true, force: true })
+}

package/test/worktree-native-overlay.test.mjs

@@ -0,0 +1,188 @@
+/**
+ * worktree native-worktree overlay regression tests
+ *
+ * 验证 Bug 1 + Bug 2 修复：
+ * 1. worktreeBase 固定到主仓库路径，不跟着 cwd 变化
+ * 2. 禁止 self-overlay（source === target 时）
+ * 3. native-worktree meta 缺失时 recover，不 overlay
+ * 4. meta 已存在时幂等返回，不重建
+ */
+
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { execSync } from 'child_process'
+
+// ── Test 1: _resolveMainRepoRoot 在主仓库内返回 cwd ──
+
+async function test1_mainRepoRoot() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-'))
+  execSync('git init', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.email "test@test.com"', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.name "test"', { cwd: d, stdio: 'pipe' })
+  execSync('git commit --allow-empty -m "init"', { cwd: d, stdio: 'pipe' })
+
+  // Add .gitignore to allow worktreeBase path
+  fs.mkdirSync(path.join(d, '.sillyspec'), { recursive: true })
+  fs.writeFileSync(path.join(d, '.gitignore'), '.sillyspec/\n')
+
+  const { WorktreeManager } = await import('../src/worktree.js')
+  const wm = new WorktreeManager({ cwd: d })
+  const root = wm._resolveMainRepoRoot()
+  console.assert(root === d, `Test 1 FAIL: expected ${d}, got ${root}`)
+  console.log('✅ Test 1: main repo root resolves to cwd')
+
+  fs.rmSync(d, { recursive: true })
+}
+
+// ── Test 2: native-worktree 检测 + 幂等守卫 ──
+
+async function test2_nativeWorktreeIdempotent() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-'))
+  execSync('git init', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.email "test@test.com"', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.name "test"', { cwd: d, stdio: 'pipe' })
+  execSync('git commit --allow-empty -m "init"', { cwd: d, stdio: 'pipe' })
+
+  const wtDir = path.join(d, 'wt')
+  execSync(`git worktree add ${wtDir} -b test-branch`, { cwd: d, stdio: 'pipe' })
+
+  // wtDir is a linked worktree
+  const { WorktreeManager } = await import('../src/worktree.js')
+
+  // First: create meta from inside worktree (simulating native-worktree mode)
+  const wm1 = new WorktreeManager({ cwd: wtDir })
+  // This simulates what happens when Claude Code runs in the worktree
+  // and SillySpec calls create() — detectIsolation should return inWorktree=true
+  // and meta should be written to main repo's worktreeBase, not worktree's
+
+  // Verify worktreeBase points to main repo
+  const expectedBase = path.join(d, '.sillyspec', '.runtime', 'worktrees')
+  console.assert(wm1.worktreeBase === expectedBase, `Test 2 FAIL: worktreeBase=${wm1.worktreeBase}, expected=${expectedBase}`)
+  console.log('✅ Test 2: worktreeBase fixed to main repo path')
+
+  fs.rmSync(d, { recursive: true })
+}
+
+// ── Test 3: self-overlay 禁止 ──
+
+async function test3_selfOverlayBlocked() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-'))
+  execSync('git init', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.email "test@test.com"', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.name "test"', { cwd: d, stdio: 'pipe' })
+  execSync('git commit --allow-empty -m "init"', { cwd: d, stdio: 'pipe' })
+  fs.mkdirSync(path.join(d, '.sillyspec'), { recursive: true })
+  fs.writeFileSync(path.join(d, '.gitignore'), '.sillyspec/\n')
+
+  const { WorktreeManager } = await import('../src/worktree.js')
+  const wm = new WorktreeManager({ cwd: d })
+
+  // Create with in-place-fallback mode (source === target)
+  const result = wm._createInPlaceMeta('test-change', {
+    worktreePath: d,
+    branch: 'test-branch',
+    mode: 'in-place-fallback',
+  })
+
+  console.assert(result.mode === 'in-place-fallback', `Test 3 FAIL: mode=${result.mode}`)
+  // 返回值不包含 baselineFiles（是简化的返回结构），验证 meta 文件本身
+  const meta3 = wm.getMeta('test-change')
+  console.assert(meta3 && meta3.baselineFiles.length === 0, `Test 3 FAIL: meta baselineFiles should be empty`)
+  console.log('✅ Test 3: self-overlay blocked, baselineFiles empty')
+
+  fs.rmSync(d, { recursive: true })
+}
+
+// ── Test 4: meta 幂等，不重复 overlay ──
+
+async function test4_metaIdempotent() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-'))
+  execSync('git init', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.email "test@test.com"', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.name "test"', { cwd: d, stdio: 'pipe' })
+  execSync('git commit --allow-empty -m "init"', { cwd: d, stdio: 'pipe' })
+  fs.mkdirSync(path.join(d, '.sillyspec'), { recursive: true })
+  fs.writeFileSync(path.join(d, '.gitignore'), '.sillyspec/\n')
+
+  const { WorktreeManager } = await import('../src/worktree.js')
+  const wm = new WorktreeManager({ cwd: d })
+
+  // First create
+  const r1 = wm._createInPlaceMeta('test-change', {
+    worktreePath: d,
+    branch: 'test-branch',
+    mode: 'in-place-fallback',
+  })
+
+  // Second create (should return existing, not re-overlay)
+  const r2 = wm._createInPlaceMeta('test-change', {
+    worktreePath: d,
+    branch: 'test-branch',
+    mode: 'in-place-fallback',
+  })
+
+  console.assert(r1.baseHash === r2.baseHash, `Test 4 FAIL: hashes differ`)
+  console.log('✅ Test 4: _createInPlaceMeta idempotent')
+
+  fs.rmSync(d, { recursive: true })
+}
+
+// ── Test 5: native-worktree meta 恢复 ──
+
+async function test5_nativeRecovery() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-'))
+  execSync('git init', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.email "test@test.com"', { cwd: d, stdio: 'pipe' })
+  execSync('git config user.name "test"', { cwd: d, stdio: 'pipe' })
+  execSync('git commit --allow-empty -m "init"', { cwd: d, stdio: 'pipe' })
+
+  const wtDir = path.join(d, 'wt')
+  execSync(`git worktree add ${wtDir} -b test-branch`, { cwd: d, stdio: 'pipe' })
+
+  const { WorktreeManager } = await import('../src/worktree.js')
+  const wm = new WorktreeManager({ cwd: wtDir })
+
+  // Simulate meta missing in native-worktree (should recover, not overlay)
+  const result = wm._recoverNativeWorktreeMeta('test-change', {
+    worktreePath: wtDir,
+    branch: 'test-branch',
+  })
+
+  console.assert(result.mode === 'native-worktree', `Test 5 FAIL: mode=${result.mode}`)
+  // 返回值不包含 baselineFiles，验证 meta 文件本身
+  const meta5 = wm.getMeta('test-change')
+  console.assert(meta5 && meta5.baselineFiles.length === 0, `Test 5 FAIL: meta baselineFiles should be empty`)
+
+  // Verify meta is readable now
+  const meta = wm.getMeta('test-change')
+  console.assert(meta !== null, `Test 5 FAIL: meta should exist after recovery`)
+  console.assert(meta.mode === 'native-worktree', `Test 5 FAIL: meta.mode=${meta.mode}`)
+  console.log('✅ Test 5: native-worktree meta recovery without overlay')
+
+  fs.rmSync(d, { recursive: true })
+}
+
+// ── Run all ──
+
+const tests = [
+  ['main repo root', test1_mainRepoRoot],
+  ['native worktree worktreeBase', test2_nativeWorktreeIdempotent],
+  ['self-overlay blocked', test3_selfOverlayBlocked],
+  ['meta idempotent', test4_metaIdempotent],
+  ['native recovery', test5_nativeRecovery],
+]
+
+let passed = 0, failed = 0
+for (const [name, fn] of tests) {
+  try {
+    await fn()
+    passed++
+  } catch (e) {
+    console.log(`❌ ${name}: ${e.message}`)
+    failed++
+  }
+}
+
+console.log(`\n${passed}/${tests.length} passed`)
+if (failed) process.exit(1)

package/.sillyspec/changes/archive/2026-04-08-derive-state/design.md

@@ -1,97 +0,0 @@
-# deriveState 状态推导
-
-author: qinyi
-created_at: 2026-04-08 07:10:00
-
-## 背景
-
-当前 sillyspec 的状态管理依赖 `progress.json` 作为唯一数据源。如果 AI 崩溃或异常中断，progress.json 可能与实际产出不一致（如 artifacts 文件已生成但步骤未标记完成）。
-
-借鉴 GSD v2 的 deriveState 架构，从文件系统反推状态，与 progress.json 交叉校验。
-
-## 需求
-
-1. `--done` 完成步骤时轻量校验当前步骤
-2. `doctor` 自检时全量扫描所有阶段
-3. `progress validate --deep` 支持手动触发全量校验
-4. 安全修复策略：明显正确的情况自动修复，有歧义的不动
-
-## 设计
-
-### 新增文件：`src/derive.js`
-
-纯函数模块，零外部依赖（仅 fs/path）。
-
-```js
-export function deriveState(cwd, options = {}) {
-  // options.mode: 'light' | 'full'（默认 light）
-  // options.fix: boolean（默认 false，只报告不修复）
-  // 返回 { issues: [{type, severity, step, artifact, suggestion}], fixed: number }
-}
-```
-
-#### 扫描逻辑
-
-1. 读取 progress.json，获取所有阶段步骤状态
-2. 扫描 `.sillyspec/.runtime/artifacts/` 目录
-3. 文件名格式：`{stage}-step{N}-{timestamp}.txt`
-4. 解析文件名提取 stage、stepIndex 信息
-5. 对比规则：
-
-| 情况 | 严重度 | 自动修复 |
-|------|--------|----------|
-| artifacts 有文件但 progress 标记未完成 | issue | ✅ 标记为 done |
-| progress 标记已完成但 artifacts 无文件 | warning | ❌ 可能被手动清理 |
-| artifacts 有 step5 但 progress 只到 step3 | issue | ✅ 补齐中间步骤 |
-
-#### 模式
-
-- **light**：只检查 currentStage 的当前步骤和前一步
-- **full**：检查所有阶段所有步骤
-
-### 集成方式
-
-#### 1. run.js — `--done` 轻量校验
-
-在 `completeStep` 末尾：
-```js
-import { deriveState } from './derive.js';
-const result = deriveState(cwd, { mode: 'light', fix: true });
-if (result.fixed > 0) {
-  console.log(`⚠️ 状态修复：${result.fixed} 个步骤已从 artifacts 恢复`);
-}
-```
-
-#### 2. doctor.js — 全量扫描
-
-第一步（SillySpec 内部检查）调用：
-```js
-const result = deriveState(cwd, { mode: 'full', fix: false });
-// 将 issues 加入自检报告
-```
-
-#### 3. progress.js — `validate --deep`
-
-validate 方法支持 deep 参数：
-```js
-validate(cwd, deep = false) {
-  // ...现有校验逻辑...
-  if (deep) {
-    const result = deriveState(cwd, { mode: 'full', fix: true });
-    // 输出校验结果
-  }
-}
-```
-
-CLI：`sillyspec progress validate --deep`
-
-## 改动范围
-
-- 新增：`src/derive.js`（~80 行）
-- 修改：`src/run.js`（2 行）、`src/stages/doctor.js`（3 行）、`src/progress.js`（5 行）、`src/index.js`（parse --deep）
-
-## 不做的事
-
-- 不引入 SQLite 或其他新依赖
-- 不改变 progress.json 的数据结构
-- 不自动删除 progress 中有但 artifacts 无的步骤（可能被手动清理）

package/.sillyspec/changes/archive/2026-04-08-derive-state/plan.md

@@ -1,51 +0,0 @@
-# deriveState 状态推导 — 实现计划
-
-author: qinyi
-created_at: 2026-04-08 07:12:00
-
-## Wave 1（核心，无依赖）
-
-- [ ] 实现 derive.js 核心函数
-  - 新增: `src/derive.js`
-  - 步骤:
-    1. 实现 `deriveState(cwd, options)` 纯函数
-    2. 实现 artifacts 文件名解析（`{stage}-step{N}-{timestamp}.txt`）
-    3. 实现 light/full 模式扫描逻辑
-    4. 实现安全修复策略（issues 分类 + fix 逻辑）
-    5. 验证: 在 sillyspec 项目上手动创建测试 artifacts，运行 `node -e "import('./src/derive.js').then(m => console.log(m.deriveState(process.cwd(), {mode:'full'})))"` 确认输出
-
-## Wave 2（集成，依赖 Wave 1）
-
-- [ ] 集成 run.js --done 轻量校验
-  - 修改: `src/run.js`
-  - 参考: `completeStep` 函数末尾
-  - 步骤:
-    1. 在 completeStep 末尾 import 并调用 deriveState(cwd, {mode:'light', fix:true})
-    2. 有修复时输出警告信息
-    3. 验证: 运行 brainstorm 完成 --done，确认无报错
-
-- [ ] 扩展 validate 支持 --deep
-  - 修改: `src/progress.js`
-  - 参考: `validate()` 方法
-  - 步骤:
-    1. validate 方法加 deep 参数
-    2. deep=true 时调用 deriveState(cwd, {mode:'full', fix:true})
-    3. 验证: `sillyspec progress validate --deep` 确认输出校验结果
-
-- [ ] CLI parse --deep 参数
-  - 修改: `src/index.js`
-  - 参考: progress 子命令的参数解析
-  - 步骤:
-    1. 在 progress validate 命令中解析 --deep flag
-    2. 传递给 validate 方法
-    3. 验证: `sillyspec progress validate --deep` 确认 flag 生效
-
-## Wave 3（集成，依赖 Wave 1）
-
-- [ ] 集成 doctor.js 全量扫描
-  - 修改: `src/stages/doctor.js`
-  - 参考: doctor 第一步（SillySpec 内部检查）的 prompt
-  - 步骤:
-    1. 在第一步 prompt 中加入 deriveState 全量扫描指令
-    2. 将 issues 列表纳入自检报告
-    3. 验证: `sillyspec run doctor` 确认第一步输出包含状态一致性检查

package/.sillyspec/changes/archive/2026-04-08-derive-state/proposal.md

@@ -1,29 +0,0 @@
-# deriveState 状态推导 — 提案
-
-author: qinyi
-created_at: 2026-04-08 07:11:00
-
-## 动机
-
-当前 progress.json 是 sillyspec 唯一的状态数据源。AI 崩溃或异常中断时，progress.json 可能与实际产出不一致（artifacts 已生成但步骤未标记完成）。需要从文件系统反推状态，交叉校验。
-
-## 变更范围
-
-- 新增 `src/derive.js`（状态推导纯函数）
-- 修改 `src/run.js`（--done 轻量校验）
-- 修改 `src/stages/doctor.js`（全量扫描）
-- 修改 `src/progress.js`（validate --deep）
-- 修改 `src/index.js`（parse --deep 参数）
-
-## 不在范围内
-
-- 不改 progress.json 数据结构
-- 不引入新依赖
-- 不自动删除 progress 中有但 artifacts 无的步骤
-
-## 成功标准
-
-1. `--done` 完成步骤时自动校验并修复当前步骤
-2. `doctor` 输出全量状态一致性报告
-3. `sillyspec progress validate --deep` 可手动触发全量校验
-4. 所有校验通过现有测试

package/.sillyspec/changes/archive/2026-04-08-derive-state/requirements.md

@@ -1,34 +0,0 @@
-# deriveState 状态推导 — 需求
-
-author: qinyi
-created_at: 2026-04-08 07:11:00
-
-## 功能需求
-
-### FR1: deriveState 核心函数
-- 从 artifacts 目录扫描文件，解析 `{stage}-step{N}-{timestamp}.txt` 格式
-- 与 progress.json 步骤状态对比
-- 返回 issues 列表和修复计数
-
-### FR2: 轻量模式（light）
-- 只检查 currentStage 的当前步骤和前一步
-- 用于 `--done` 完成时
-
-### FR3: 全量模式（full）
-- 检查所有阶段所有步骤
-- 用于 doctor 和 validate --deep
-
-### FR4: 安全修复策略
-- artifacts 有但 progress 漏记 → 自动修复为 done
-- artifacts 有 step5 但 progress 只到 step3 → 自动补齐
-- progress 有但 artifacts 无 → 只警告，不修复
-
-### FR5: CLI 集成
-- `--done` 时静默调用轻量校验，有修复才输出
-- `doctor` 第一步输出全量报告
-- `sillyspec progress validate --deep` 手动触发
-
-## 非功能需求
-- 零外部依赖（仅 fs/path）
-- 纯函数，易于测试
-- 不改变现有 API 行为