sillyspec 3.16.2 → 3.17.1

package/src/stage-contract.js

@@ -33,9 +33,12 @@ function validateScanOutputs(cwd, changeName, context = {}) {
   const { projectName, specRoot } = context
   // 平台模式使用 specRoot，本地模式使用 cwd
   const base = specRoot || cwd
+  // 如果 base 已经是 specDir（有 docs/ 子目录），直接用 base/docs/
+  // 否则按传统模式拼接 .sillyspec/docs/
+  const isSpecDir = existsSync(join(base, 'docs'))
   const docsRoot = projectName
-    ? join(base, '.sillyspec', 'docs', projectName, 'scan')
-    : join(base, '.sillyspec', 'docs', 'scan')
+    ? join(base, isSpecDir ? 'docs' : '.sillyspec/docs', projectName, 'scan')
+    : join(base, isSpecDir ? 'docs' : '.sillyspec/docs', 'scan')
 
   const requiredDocs = [
     'ARCHITECTURE.md',
@@ -58,8 +61,8 @@ function validateScanOutputs(cwd, changeName, context = {}) {
 
   // 检查 modules 目录
   const modulesRoot = projectName
-    ? join(base, '.sillyspec', 'docs', projectName, 'modules')
-    : join(base, '.sillyspec', 'docs', 'modules')
+    ? join(base, isSpecDir ? 'docs' : '.sillyspec/docs', projectName, 'modules')
+    : join(base, isSpecDir ? 'docs' : '.sillyspec/docs', 'modules')
   if (!existsSync(modulesRoot)) {
     warnings.push('modules 目录不存在')
   } else {
@@ -212,7 +215,13 @@ const contracts = {
     description: '归档与收口',
     allowedFrom: ['verify'],
     allowedTo: [],
-    validators: [validateChangeClosed, validateArchiveOutputs],
+    // 阶段级 validator 全部移除，改为 run.js 中 step 4 完成后的硬编码校验。
+    // 理由：两个 validator 的生效窗口互斥 ——
+    // validateChangeClosed 要求变更目录存在（step 4 --confirm 后已被移到 archive 目录）
+    // validateArchiveOutputs 要求 archive 目录存在（step 4 前还不存在）
+    // 注册为阶段级 validator 会导致每步都误报错误。
+    // run.js:893-909 已在正确的时机（step 4 完成后）执行相同检查。
+    validators: [],
   },
 
   // === 辅助阶段 ===

package/src/stages/execute.js

@@ -322,15 +322,21 @@ function buildWavePrompt(wave, waveIndex, changeDir, worktreePath) {
 
   const worktreeSection = (worktreePath)
     ? `
-### 工作目录
-你必须在以下 worktree 中工作（子代理的 cwd 设为此路径）：
-\`${worktreePath}\`
+### 工作目录（必须严格遵守）
 
-不要在主工作区修改源码文件。所有代码变更只在 worktree 中进行。
+调用 Task 工具启动子代理时，**workdir 参数是强制必传的**。
+不传 workdir 会导致子代理把文件写到主工作区而非 worktree，破坏隔离。
+
+\`\`\`json
+{
+  "subagent_type": "general",
+  "workdir": "${worktreePath}",
+  "prompt": "在此编写任务描述..."
+}
+\`\`\`
 
 ### 注意
 蓝图文件（tasks.md / design.md / proposal.md / requirements.md）在主工作区 .sillyspec/changes/<change>/ 下，它们可能不在 worktree 中。读取蓝图时使用主工作区路径，不要拼接到 worktree 路径下。
-子代理的 cwd 参数设为 \`${worktreePath}\`。
 `
     : ''
 

package/src/stages/scan.js

@@ -453,8 +453,24 @@ step1 → step2 → step3
 5. 清理：\`rm -f {DOCS_ROOT}/scan/_env-detect.md\`
 6. \`git add .sillyspec/\` — 暂存扫描结果（不要 commit，由用户通过统一提交工具处理）
 
+### ⛔ 路径合规检查（平台模式下必须执行）
+7. 确认所有文档都写入 \`{DOCS_ROOT}/\`（spec-root 下），**而非源码目录下的 .sillyspec/**
+8. 检查是否出现 tool_use_error 或 API Error 未恢复
+9. 检查 7 份文档 header 是否包含 author 和 created_at
+10. 检查 local.yaml 中 commands 是否在 package.json scripts 中真实存在，不存在的必须标记 unavailable
+
+### ⛔ 最终状态判定
+如果出现以下**任意**情况，最终状态**不能**写"全部通过"，只能写 \`completed_with_warnings\` 或 \`failed_post_check\`：
+- 源码目录下存在 docs（路径合规检查失败）
+- source_commit 为 null
+- Write 工具出现过失败
+- API Error 529 或 rate_limit
+- fallback / retry / skipped validation
+- 文档引用不存在的文件或模块
+- 文档内容包含 .sillyspec/ 等工具目录的扫描结果
+
 ### 输出
-每个项目的扫描完整性报告
+每个项目的扫描完整性报告（必须包含路径合规检查结果和最终状态）
 
 ### 注意
 - ❌ 修改代码 / 编造路径 / 读源码全文`,

package/src/worktree-apply.js

@@ -148,10 +148,12 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
   }
 
   // --- 4.5 校验：主工作区 baseline 是否变化（防 execute 期间主工作区被修改）---
+  // 注意：必须和 computeBaselineHash (worktree.js) 使用相同的排除规则
   if (meta.baselineHash) {
-    const staged = gitQuiet(projectRoot, 'diff --cached') || '';
-    const unstaged = gitQuiet(projectRoot, 'diff') || '';
-    const untracked = gitQuiet(projectRoot, 'ls-files --others --exclude-standard') || '';
+    const exclude = '-- . ":(exclude).sillyspec/"';
+    const staged = gitQuiet(projectRoot, `diff --cached ${exclude}`) || '';
+    const unstaged = gitQuiet(projectRoot, `diff ${exclude}`) || '';
+    const untracked = gitQuiet(projectRoot, `ls-files --others --exclude-standard ${exclude}`) || '';
     const raw = `staged:${staged}\nunstaged:${unstaged}\nuntracked:${untracked}`;
     const currentHash = createHash('sha256').update(raw).digest('hex').slice(0, 16);
     if (currentHash !== meta.baselineHash) {

package/src/worktree.js

@@ -73,9 +73,11 @@ function parseJSON(raw) {
 }
 
 function computeBaselineHash(cwd) {
-  const staged = gitQuiet(cwd, 'diff --cached') || '';
-  const unstaged = gitQuiet(cwd, 'diff') || '';
-  const untracked = gitQuiet(cwd, 'ls-files --others --exclude-standard') || '';
+  // 排除 .sillyspec/ 元数据目录，避免 brainstorm/plan 阶段修改的蓝图文件污染 baseline
+  const exclude = '-- . ":(exclude).sillyspec/"';
+  const staged = gitQuiet(cwd, `diff --cached ${exclude}`) || '';
+  const unstaged = gitQuiet(cwd, `diff ${exclude}`) || '';
+  const untracked = gitQuiet(cwd, `ls-files --others --exclude-standard ${exclude}`) || '';
   const raw = `staged:${staged}
 unstaged:${unstaged}
 untracked:${untracked}`;

package/test/platform-recovery.test.mjs

@@ -0,0 +1,139 @@
+/**
+ * platform-recovery.test.mjs — 平台模式参数恢复 + stage-contract 路径测试
+ */
+
+import { join, resolve, dirname, basename } from 'path'
+import { existsSync, mkdirSync, writeFileSync, rmSync, readFileSync } from 'fs'
+import { fileURLToPath, pathToFileURL } from 'url'
+import { execSync } from 'child_process'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const root = resolve(__dirname, '..')
+const binCLI = join(root, 'bin', 'sillyspec.js')
+
+let passed = 0, failed = 0
+
+function assert(cond, msg) {
+  if (cond) { console.log(`  ✅ PASS: ${msg}`); passed++ }
+  else { console.log(`  ❌ FAIL: ${msg}`); failed++ }
+}
+
+const P = 'recover'
+function setup(name) {
+  const d = join('/tmp', `${P}-${name}`)
+  mkdirSync(d, { recursive: true })
+  return d
+}
+function spec(name) {
+  const d = join('/tmp', `${P}-${name}-spec`)
+  mkdirSync(d, { recursive: true })
+  return d
+}
+function clean(...dirs) { for (const d of dirs) try { rmSync(d, { recursive: true, force: true }) } catch {} }
+
+function run(cmd) {
+  return execSync(cmd, { encoding: 'utf8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'] })
+}
+
+const DOCS = ['ARCHITECTURE.md','CONVENTIONS.md','STRUCTURE.md','INTEGRATIONS.md','TESTING.md','CONCERNS.md','PROJECT.md']
+function writeSpecDocs(dir) {
+  for (const d of DOCS) {
+    const p = join(dir, 'scan', d)
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, 'author: bot\ncreated_at: now\n# doc\n')
+  }
+}
+function writeLocalDocs(cwd) {
+  for (const d of DOCS) {
+    const p = join(cwd, '.sillyspec', 'docs', basename(cwd), 'scan', d)
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, 'author: bot\ncreated_at: now\n# doc\n')
+  }
+}
+
+// ── Test 1: platform-scan.json 写入位置 ──
+console.log('\n=== Test 1: platform-scan.json 写入位置 ===')
+{
+  const cwd = setup('t1'), sd = spec('t1')
+  run(`node "${binCLI}" init "${cwd}" --spec-dir "${sd}"`)
+  run(`node "${binCLI}" --dir "${cwd}" --spec-dir "${sd}" run scan --spec-root "${sd}" --runtime-root "${sd}/runtime" --workspace-id ws1 --scan-run-id sr1`)
+
+  const inSpecDir = join(sd, '.runtime', 'platform-scan.json')
+  const inCwd = join(cwd, '.sillyspec', '.runtime', 'platform-scan.json')
+  assert(existsSync(inSpecDir), `platform-scan.json 在 specDir/.runtime/`)
+  assert(existsSync(inCwd), `恢复指针也写入 cwd/.sillyspec/.runtime/`)
+
+  const content = JSON.parse(readFileSync(inSpecDir, 'utf8'))
+  assert(content.specRoot === sd, `specRoot 指向 specDir`)
+  assert(content.workspaceId === 'ws1', `workspaceId 保存正确`)
+  assert(content.scanRunId === 'sr1', `scanRunId 保存正确`)
+  clean(cwd, sd)
+}
+
+// ── Test 2: --done 不带 --spec-root 时恢复 ──
+console.log('\n=== Test 2: --done 恢复平台参数 ===')
+{
+  const cwd = setup('t2'), sd = spec('t2')
+  run(`node "${binCLI}" init "${cwd}" --spec-dir "${sd}"`)
+  run(`node "${binCLI}" --dir "${cwd}" --spec-dir "${sd}" run scan --spec-root "${sd}" --runtime-root "${sd}/runtime" --workspace-id ws2 --scan-run-id sr2`)
+  // --done 不带任何平台参数
+  const output = run(`node "${binCLI}" --dir "${cwd}" run scan --done --change default --dir "${cwd}" --input "test" --output "test done" 2>&1`)
+  assert(output.includes('平台模式'), `恢复成功：包含平台模式指令`)
+  assert(output.includes(sd), `恢复成功：包含 specDir 路径`)
+  clean(cwd, sd)
+}
+
+// ── Test 3-6: stage-contract 路径（通过 runValidators） ──
+const { runValidators } = await import(pathToFileURL(join(root, 'src', 'stage-contract.js')).href)
+
+console.log('\n=== Test 3: specDir 有文档 → 校验通过 ===')
+{
+  const cwd = setup('t3'), sd = spec('t3')
+  const proj = basename(cwd)
+  const scanDir = join(sd, 'docs', proj)
+  writeSpecDocs(scanDir)
+  const result = runValidators('scan', cwd, 'default', { projectName: proj, specRoot: sd })
+  assert(result.ok, `specDir 有文档: ok=${result.ok}, errors=${JSON.stringify(result.errors)}`)
+  clean(cwd, sd)
+}
+
+console.log('\n=== Test 4: specDir 缺文档 → 校验失败，路径不含 .sillyspec ===')
+{
+  const cwd = setup('t4'), sd = spec('t4')
+  const proj = basename(cwd)
+  mkdirSync(join(sd, 'docs'), { recursive: true })
+  const result = runValidators('scan', cwd, 'default', { projectName: proj, specRoot: sd })
+  assert(!result.ok, `specDir 缺文档: ok=${result.ok}`)
+  assert(result.errors.length > 0, `有 errors`)
+  const errMsg = result.errors[0]
+  assert(!errMsg.includes('.sillyspec/docs'), `路径不含 .sillyspec: ${errMsg}`)
+  assert(errMsg.includes('/docs/'), `路径含 /docs/: ${errMsg}`)
+  clean(cwd, sd)
+}
+
+console.log('\n=== Test 5: 非平台模式有文档 → 校验通过 ===')
+{
+  const cwd = setup('t5')
+  const proj = basename(cwd)
+  writeLocalDocs(cwd)
+  const result = runValidators('scan', cwd, 'default', { projectName: proj })
+  assert(result.ok, `非平台有文档: ok=${result.ok}`)
+  clean(cwd)
+}
+
+console.log('\n=== Test 6: 非平台模式缺文档 → 路径含 .sillyspec ===')
+{
+  const cwd = setup('t6')
+  const proj = basename(cwd)
+  const result = runValidators('scan', cwd, 'default', { projectName: proj })
+  assert(!result.ok, `非平台缺文档: ok=${result.ok}`)
+  const errMsg = result.errors[0]
+  assert(errMsg.includes('.sillyspec/docs'), `路径含 .sillyspec/docs/: ${errMsg}`)
+  clean(cwd)
+}
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(`${'='.repeat(50)}`)
+process.exit(failed > 0 ? 1 : 0)

package/test/scan-postcheck.test.mjs

@@ -0,0 +1,179 @@
+/**
+ * scan-postcheck.test.mjs — CLI 层 post-check 测试
+ */
+
+import { join, resolve, dirname, basename } from 'path'
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { fileURLToPath, pathToFileURL } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const root = resolve(__dirname, '..')
+
+const { runScanPostCheck } = await import(pathToFileURL(join(root, 'src', 'scan-postcheck.js')).href)
+
+let passed = 0, failed = 0
+
+function assert(cond, msg) {
+  if (cond) { console.log(`  ✅ PASS: ${msg}`); passed++ }
+  else { console.log(`  ❌ FAIL: ${msg}`); failed++ }
+}
+
+function setup(name) {
+  const cwd = join('/tmp', `pc-${name}`)
+  mkdirSync(cwd, { recursive: true })
+  return cwd
+}
+function specSetup(name) {
+  const d = join('/tmp', `pc-${name}-spec`)
+  mkdirSync(d, { recursive: true })
+  return d
+}
+function clean(...dirs) { for (const d of dirs) try { rmSync(d, { recursive: true, force: true }) } catch {} }
+
+const DOCS = ['ARCHITECTURE.md','CONVENTIONS.md','STRUCTURE.md','INTEGRATIONS.md','TESTING.md','CONCERNS.md','PROJECT.md']
+
+// 写入全部 7 份文档，项目名 = basename(cwd)
+function writeFull(cwd, specDir) {
+  const proj = basename(cwd)
+  for (const d of DOCS) {
+    const p = join(specDir, 'docs', proj, 'scan', d)
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, 'author: bot\ncreated_at: 2026-06-08 10:00:00\n# doc\n')
+  }
+}
+
+// 写入前 N 份文档
+function writeN(cwd, specDir, n) {
+  const proj = basename(cwd)
+  for (let i = 0; i < n; i++) {
+    const p = join(specDir, 'docs', proj, 'scan', DOCS[i])
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, 'author: bot\ncreated_at: 2026-06-08 10:00:00\n# doc\n')
+  }
+}
+
+// ── 1: source_root 有文档 → failed ──
+console.log('\n=== Test 1: source_root 泄漏 → failed_post_check ===')
+{
+  const cwd = setup('t1'), spec = specSetup('t1')
+  const proj = basename(cwd)
+  mkdirSync(join(cwd, '.sillyspec/docs', proj, 'scan'), { recursive: true })
+  writeFileSync(join(cwd, '.sillyspec/docs', proj, 'scan', 'ARCHITECTURE.md'), '# leak')
+  const r = runScanPostCheck({ cwd, specDir: spec })
+  assert(r.status === 'failed_post_check', `状态: ${r.status}`)
+  assert(r.checks.some(c => c.name === 'source_root_docs_leak'), `source_root_docs_leak`)
+  clean(cwd, spec)
+}
+
+// ── 2: spec 无文档 → failed ──
+console.log('\n=== Test 2: spec 无文档 → failed_post_check ===')
+{
+  const cwd = setup('t2'), spec = specSetup('t2')
+  const r = runScanPostCheck({ cwd, specDir: spec })
+  assert(r.status === 'failed_post_check', `状态: ${r.status}`)
+  assert(r.checks.some(c => c.name === 'all_docs_missing'), `all_docs_missing`)
+  clean(cwd, spec)
+}
+
+// ── 3: 缺部分 required 文档 → failed ──
+console.log('\n=== Test 3: 部分缺失 → failed_post_check ===')
+{
+  const cwd = setup('t3'), spec = specSetup('t3')
+  writeN(cwd, spec, 6)
+  const r = runScanPostCheck({ cwd, specDir: spec })
+  assert(r.status === 'failed_post_check', `状态: ${r.status}`)
+  assert(r.checks.some(c => c.name === 'partial_docs_missing'), `partial_docs_missing`)
+  clean(cwd, spec)
+}
+
+// ── 4: local.yaml 命令不存在 → warnings ──
+console.log('\n=== Test 4: local.yaml 命令不存在 → completed_with_warnings ===')
+{
+  const cwd = setup('t4'), spec = specSetup('t4')
+  writeFull(cwd, spec)
+  writeFileSync(join(spec, 'local.yaml'),
+    'project:\n  type: nodejs\ncommands:\n  build: "npm run build"\n  test: "npm run test"\n  lint: "npm run lint"\n')
+  writeFileSync(join(cwd, 'package.json'), '{"name":"t4","scripts":{"start":"node server.js"}}')
+  const r = runScanPostCheck({ cwd, specDir: spec })
+  assert(r.status === 'completed_with_warnings', `状态: ${r.status}`)
+  assert(r.checks.some(c => c.name === 'local_config_invalid'), `local_config_invalid`)
+  clean(cwd, spec)
+}
+
+// ── 5-8: AI 输出错误标记 → warnings ──
+const errorCases = [
+  { id: 'e5', name: 'tool_use_error', output: 'tool_use_error: file not found' },
+  { id: 'e6', name: 'API Error 529', output: 'API Error 529 server overloaded' },
+  { id: 'e7', name: 'rate_limit', output: 'rate limit exhausted' },
+  { id: 'e8', name: 'fallback', output: 'fallback to default, skipped validation' },
+]
+for (const ec of errorCases) {
+  console.log(`\n=== Test: ${ec.name} → completed_with_warnings ===`)
+  const cwd = setup(ec.id), spec = specSetup(ec.id)
+  writeFull(cwd, spec)
+  const r = runScanPostCheck({ cwd, specDir: spec, outputText: ec.output })
+  assert(r.status === 'completed_with_warnings', `${ec.name}: 状态 ${r.status}`)
+  clean(cwd, spec)
+}
+
+// ── 9: 文档缺 header → warnings ──
+console.log('\n=== Test 9: 文档缺 header → completed_with_warnings ===')
+{
+  const cwd = setup('t9'), spec = specSetup('t9')
+  const proj = basename(cwd)
+  for (const d of DOCS) {
+    const p = join(spec, 'docs', proj, 'scan', d)
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, '# no header\n')
+  }
+  const r = runScanPostCheck({ cwd, specDir: spec })
+  assert(r.status === 'completed_with_warnings', `状态: ${r.status}`)
+  assert(r.checks.some(c => c.name === 'docs_missing_header'), `docs_missing_header`)
+  clean(cwd, spec)
+}
+
+// ── 10: 全部通过 → success ──
+console.log('\n=== Test 10: 全部通过 → success ===')
+{
+  const cwd = setup('t10'), spec = specSetup('t10')
+  writeFull(cwd, spec)
+  const r = runScanPostCheck({ cwd, specDir: spec, outputText: 'done' })
+  assert(r.status === 'success', `状态: ${r.status}`)
+  assert(r.checks.length === 0, `checks.length=0`)
+  clean(cwd, spec)
+}
+
+// ── 11: 非平台模式 ──
+console.log('\n=== Test 11: 非平台模式 ===')
+{
+  const cwd = setup('t11')
+  const proj = basename(cwd)
+  for (let i = 0; i < 5; i++) {
+    const p = join(cwd, '.sillyspec', 'docs', proj, 'scan', DOCS[i])
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, 'author: bot\ncreated_at: now\n# doc\n')
+  }
+  const r = runScanPostCheck({ cwd, specDir: null })
+  assert(r.status === 'completed_with_warnings', `非平台: ${r.status}`)
+  assert(!r.checks.some(c => c.name === 'source_root_docs_leak'), `无 source_root_leak`)
+  clean(cwd)
+}
+
+// ── 12: 多问题 failed 优先 ──
+console.log('\n=== Test 12: failed 优先 ===')
+{
+  const cwd = setup('t12'), spec = specSetup('t12')
+  const proj = basename(cwd)
+  mkdirSync(join(cwd, '.sillyspec/docs', proj, 'scan'), { recursive: true })
+  writeFileSync(join(cwd, '.sillyspec/docs', proj, 'scan', 'ARCHITECTURE.md'), '# leak')
+  writeN(cwd, spec, 3)
+  const r = runScanPostCheck({ cwd, specDir: spec })
+  assert(r.status === 'failed_post_check', `failed 优先: ${r.status}`)
+  clean(cwd, spec)
+}
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(`${'='.repeat(50)}`)
+process.exit(failed > 0 ? 1 : 0)

package/test/spec-dir.test.mjs

@@ -0,0 +1,200 @@
+/**
+ * --spec-dir 功能测试
+ * 
+ * 测试点：
+ * 1. ProgressManager 外部 specDir 路径正确
+ * 2. init 外部 specDir 不污染源码
+ * 3. 默认模式不受影响
+ * 4. 平台模式 prompt 注入（scan/brainstorm/plan/execute/verify/quick）
+ * 5. 非 platform 模式占位符替换（无 undefined/null）
+ * 6. --spec-dir 与 --spec-root 兼容
+ * 7. progress 使用外部 specDir
+ */
+
+import { join, resolve, basename, dirname } from 'path'
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { fileURLToPath, pathToFileURL } from 'url'
+import { execSync } from 'child_process'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const root = resolve(__dirname, '..')
+const binCLI = join(root, 'bin', 'sillyspec.js')
+
+function imp(path) {
+  return import(pathToFileURL(path).href)
+}
+
+let passed = 0
+let failed = 0
+
+function assert(condition, msg) {
+  if (condition) {
+    console.log(`  ✅ PASS: ${msg}`)
+    passed++
+  } else {
+    console.log(`  ❌ FAIL: ${msg}`)
+    failed++
+  }
+}
+
+function tmpDir(name) {
+  const dir = join('/tmp', `spec-dir-test-${name}-${Date.now()}`)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+function cleanup(dir) {
+  try { rmSync(dir, { recursive: true, force: true }) } catch {}
+}
+
+function run(cmd) {
+  return execSync(cmd, { encoding: 'utf8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] })
+}
+
+// ── Test 1: ProgressManager 外部 specDir ──
+console.log('\n=== Test 1: ProgressManager 外部 specDir ===')
+{
+  const { ProgressManager } = await imp(join(root, 'src', 'progress.js'))
+  const tmp = tmpDir('pm')
+  const specDir = join(tmp, 'external-spec')
+  
+  const pm = new ProgressManager({ specDir })
+  assert(pm._getSpecDir(tmp) === specDir, `_getSpecDir 返回自定义路径`)
+  
+  const pm2 = new ProgressManager()
+  assert(pm2._getSpecDir(tmp) === join(tmp, '.sillyspec'), `_getSpecDir 无自定义时返回 cwd/.sillyspec`)
+  
+  assert(pm._runtimePath(tmp) === join(specDir, '.runtime'), `_runtimePath 基于 specDir`)
+  assert(pm._changePath(tmp, 'c') === join(specDir, 'changes', 'c'), `_changePath 基于 specDir`)
+  
+  // 外部 specDir 时 _ensureGitignore 应跳过
+  const gitignoreResult = pm._ensureGitignore(tmp)
+  assert(gitignoreResult === undefined, `外部 specDir 时 _ensureGitignore 跳过`)
+  
+  cleanup(tmp)
+}
+
+// ── Test 2: init 外部 specDir 不污染源码 ──
+console.log('\n=== Test 2: init 外部 specDir 不污染源码 ===')
+{
+  const { cmdInit } = await imp(join(root, 'src', 'init.js'))
+  const projectDir = tmpDir('project')
+  const specDir = tmpDir('spec')
+  
+  await cmdInit(projectDir, { specDir })
+  
+  assert(!existsSync(join(projectDir, '.sillyspec')), '源码目录不含 .sillyspec')
+  assert(!existsSync(join(projectDir, '.gitignore')), '外部 specDir 时不创建 .gitignore')
+  assert(existsSync(join(specDir, 'projects')), `specDir/projects 存在`)
+  assert(existsSync(join(specDir, 'docs')), `specDir/docs 存在`)
+  assert(existsSync(join(specDir, '.runtime', 'sillyspec.db')), `specDir/.runtime/sillyspec.db 存在`)
+  assert(existsSync(join(specDir, 'workflows')), `specDir/workflows 存在`)
+  assert(existsSync(join(projectDir, '.claude')), `源码目录 .claude 存在（工具指令）`)
+  
+  cleanup(projectDir)
+  cleanup(specDir)
+}
+
+// ── Test 3: 默认模式不受影响 ──
+console.log('\n=== Test 3: 默认模式不受影响 ===')
+{
+  const { cmdInit } = await imp(join(root, 'src', 'init.js'))
+  const projectDir = tmpDir('default')
+  
+  await cmdInit(projectDir, {})
+  
+  assert(existsSync(join(projectDir, '.sillyspec')), '默认模式创建 .sillyspec 在项目内')
+  assert(existsSync(join(projectDir, '.sillyspec', '.runtime', 'sillyspec.db')), '默认模式 DB 在项目内')
+  assert(existsSync(join(projectDir, '.gitignore')), '默认模式创建 .gitignore')
+  
+  cleanup(projectDir)
+}
+
+// ── Test 4: 平台模式 prompt 注入（多 stage） ──
+console.log('\n=== Test 4: 平台模式 prompt 注入 ===')
+{
+  const projectDir = tmpDir('prompt-p')
+  const specDir = tmpDir('prompt-s')
+  
+  run(`node "${binCLI}" init "${projectDir}" --spec-dir "${specDir}"`)
+  
+  const stages = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'quick']
+  for (const stage of stages) {
+    const output = run(`node "${binCLI}" --dir "${projectDir}" --spec-dir "${specDir}" run ${stage}`)
+    assert(output.includes('平台模式'), `${stage}: 包含平台模式指令`)
+    assert(output.includes(`规范目录（specDir）: \`${specDir}\``), `${stage}: 包含正确的 specDir 路径`)
+  }
+  
+  // scan 额外检查
+  const scanOutput = run(`node "${binCLI}" --dir "${projectDir}" --spec-dir "${specDir}" run scan`)
+  assert(scanOutput.includes('严禁写入源码目录'), 'scan: 包含严禁写入源码目录')
+  assert(scanOutput.includes('Write 工具失败时，不允许'), 'scan: 包含 Write 工具规则')
+  assert(scanOutput.includes('变更目录'), 'scan: 包含变更目录')
+  
+  cleanup(projectDir)
+  cleanup(specDir)
+}
+
+// ── Test 5: 非 platform 模式占位符替换 ──
+console.log('\n=== Test 5: 非 platform 模式占位符替换 ===')
+{
+  const projectDir = tmpDir('noplatform')
+  
+  run(`node "${binCLI}" init "${projectDir}"`)
+  
+  const output = run(`node "${binCLI}" --dir "${projectDir}" run scan`)
+  
+  assert(!output.includes('平台模式 — 写入路径约束'), '非 platform 模式不含平台指令')
+  assert(!output.includes('{DOCS_ROOT}'), '{DOCS_ROOT} 被正确替换')
+  assert(!output.includes('undefined'), '输出不含 undefined 路径')
+  assert(!output.includes('null/.sillyspec'), '输出不含 null 路径')
+  
+  cleanup(projectDir)
+}
+
+// ── Test 6: --spec-root 兼容 ──
+console.log('\n=== Test 6: --spec-root 兼容 ===')
+{
+  const projectDir = tmpDir('compat-p')
+  const specDir = tmpDir('compat-s')
+  
+  run(`node "${binCLI}" init "${projectDir}" --spec-dir "${specDir}"`)
+  
+  const output = run(`node "${binCLI}" --dir "${projectDir}" run scan --spec-root "${specDir}"`)
+  assert(output.includes('平台模式'), '--spec-root 兼容：仍触发平台模式指令')
+  
+  cleanup(projectDir)
+  cleanup(specDir)
+}
+
+// ── Test 7: progress 使用外部 specDir ──
+console.log('\n=== Test 7: progress 使用外部 specDir ===')
+{
+  const { ProgressManager } = await imp(join(root, 'src', 'progress.js'))
+  const projectDir = tmpDir('progress-p')
+  const specDir = tmpDir('progress-s')
+  
+  const pm = new ProgressManager({ specDir })
+  await pm.init(projectDir)
+  
+  assert(existsSync(join(specDir, '.runtime', 'sillyspec.db')), 'DB 创建在外部 specDir')
+  assert(!existsSync(join(projectDir, '.sillyspec')), '源码目录不含 .sillyspec')
+  
+  await pm.initChange(projectDir, 'test-change')
+  assert(existsSync(join(specDir, 'changes', 'test-change')), 'changes 创建在外部 specDir')
+  
+  const progress = await pm.read(projectDir, 'test-change')
+  assert(progress !== null, '能从外部 specDir 读取 progress')
+  assert(progress.currentChange === 'test-change', `currentChange 正确`)
+  
+  cleanup(projectDir)
+  cleanup(specDir)
+}
+
+// ── 汇总 ──
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(`${'='.repeat(50)}`)
+
+process.exit(failed > 0 ? 1 : 0)