sillyspec 3.20.3 → 3.20.5

package/test/spec-dir.test.mjs

@@ -0,0 +1,206 @@
+/**
+ * --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'
+import { tmpdir } from 'os'
+
+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(tmpdir(), `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 返回自定义路径`)
+  
+  // 无自定义 specDir 时，resolveSpecDir 会向上查找 .sillyspec 目录
+  // 在测试环境中可能命中上层已有的 .sillyspec，所以只检查返回值是否有效路径
+  const pm2 = new ProgressManager()
+  const resolved = pm2._getSpecDir(tmp)
+  assert(typeof resolved === 'string' && resolved.length > 0 && resolved.endsWith('.sillyspec'),
+    `_getSpecDir 无自定义时返回有效 .sillyspec 路径 (got: ${resolved})`)
+  
+  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}"`)
+  
+  // execute 阶段会自动创建 worktree，在非 git 环境下会失败，跳过
+  const stages = ['scan', 'brainstorm', 'plan', 'verify', 'quick']
+  for (const stage of stages) {
+    const output = run(`node "${binCLI}" --dir "${projectDir}" --spec-dir "${specDir}" run ${stage} --skip-approval`)
+    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)}`)
+
+if (failed > 0) throw new Error(`${failed} test(s) failed`)

package/test/stage-contract-failed-post-check.test.mjs

@@ -0,0 +1,102 @@
+/**
+ * task-07: checkTransition failed_post_check 门控
+ *
+ * 覆盖：
+ * - AC-1: scan → brainstorm (failed_post_check) → allowed=false, reason 含"scan post-check 未通过"
+ * - AC-2: scan → scan (重跑修复) → allowed=true
+ * - AC-3: scan → doctor/status (辅助阶段) → allowed=true
+ * - AC-4: 旧数据无 status 字段 → 行为同旧版（按 allowedFrom）
+ * - AC-5: status='completed' 不被拦
+ */
+import { checkTransition } from '../src/stage-contract.js'
+
+let passed = 0
+let failed = 0
+function assertEqual (actual, expected, msg) {
+  const ok = actual === expected
+  if (ok) { console.log(`✅ PASS: ${msg}`); passed++ }
+  else { console.error(`❌ FAIL: ${msg}\n   expected: ${JSON.stringify(expected)}\n   actual:   ${JSON.stringify(actual)}`); failed++ }
+}
+function assertMatch (actual, regex, msg) {
+  if (regex.test(actual)) { console.log(`✅ PASS: ${msg}`); passed++ }
+  else { console.error(`❌ FAIL: ${msg}\n   actual: ${JSON.stringify(actual)} 不匹配 ${regex}`); failed++ }
+}
+function assert (cond, msg) {
+  if (cond) { console.log(`✅ PASS: ${msg}`); passed++ }
+  else { console.error(`❌ FAIL: ${msg}`); failed++ }
+}
+
+console.log('=== AC-1: failed_post_check 状态下进 brainstorm/plan/execute 被拦 ===')
+
+// scan → brainstorm, failed_post_check
+{
+  const r = checkTransition('scan', 'brainstorm', { fromStageData: { status: 'failed_post_check' } })
+  assertEqual(r.allowed, false, "scan→brainstorm failed_post_check: allowed=false")
+  assertMatch(r.reason || '', /scan post-check 未通过/, 'reason 含 "scan post-check 未通过"')
+  assertMatch(r.reason || '', /重跑\s*scan|重跑\s*scan/, 'reason 含 "重跑 scan" 提示')
+}
+
+// scan → plan / execute 同样被拦
+{
+  const r1 = checkTransition('scan', 'plan', { fromStageData: { status: 'failed_post_check' } })
+  assertEqual(r1.allowed, false, "scan→plan failed_post_check: allowed=false")
+  const r2 = checkTransition('scan', 'execute', { fromStageData: { status: 'failed_post_check' } })
+  assertEqual(r2.allowed, false, "scan→execute failed_post_check: allowed=false")
+}
+
+console.log('\n=== AC-2: 允许 scan → scan 重跑修复（fromStage===toStage） ===')
+{
+  const r = checkTransition('scan', 'scan', { fromStageData: { status: 'failed_post_check' } })
+  assertEqual(r.allowed, true, "scan→scan failed_post_check: allowed=true（允许重跑修复）")
+}
+
+console.log('\n=== AC-3: failed_post_check 下辅助阶段（doctor/status）仍可执行 ===')
+{
+  const r1 = checkTransition('scan', 'doctor', { fromStageData: { status: 'failed_post_check' } })
+  assertEqual(r1.allowed, true, "scan→doctor failed_post_check: allowed=true（辅助阶段）")
+  const r2 = checkTransition('scan', 'status', { fromStageData: { status: 'failed_post_check' } })
+  assertEqual(r2.allowed, true, "scan→status failed_post_check: allowed=true（辅助阶段）")
+  const r3 = checkTransition('scan', 'quick', { fromStageData: { status: 'failed_post_check' } })
+  assertEqual(r3.allowed, true, "scan→quick failed_post_check: allowed=true（辅助阶段）")
+  const r4 = checkTransition('scan', 'explore', { fromStageData: { status: 'failed_post_check' } })
+  assertEqual(r4.allowed, true, "scan→explore failed_post_check: allowed=true（辅助阶段）")
+}
+
+console.log('\n=== AC-4: 旧数据兼容（无 options 或 status 缺失，行为同旧版） ===')
+{
+  // 无 options（旧调用）— scan→brainstorm 按 allowedFrom 规则允许（scan 是辅助阶段，可进主流程）
+  const r1 = checkTransition('scan', 'brainstorm')
+  assertEqual(r1.allowed, true, "scan→brainstorm 无 options: 行为同旧版（allowed=true）")
+
+  // options 提供 fromStageData 但 status 为 undefined
+  const r2 = checkTransition('scan', 'brainstorm', { fromStageData: { /* 无 status */ } })
+  assertEqual(r2.allowed, true, "scan→brainstorm status=undefined: 行为同旧版（allowed=true）")
+
+  // options 为空对象
+  const r3 = checkTransition('scan', 'brainstorm', {})
+  assertEqual(r3.allowed, true, "scan→brainstorm options={}: 行为同旧版（allowed=true）")
+}
+
+console.log('\n=== AC-5: status="completed" 不被门控拦截 ===')
+{
+  const r = checkTransition('scan', 'brainstorm', { fromStageData: { status: 'completed' } })
+  assertEqual(r.allowed, true, "scan→brainstorm status=completed: allowed=true")
+}
+
+console.log('\n=== AC-6: fromStage 非 scan 时门控不触发（门控只针对 scan 源） ===')
+{
+  const r = checkTransition('brainstorm', 'plan', { fromStageData: { status: 'failed_post_check' } })
+  assertEqual(r.allowed, true, "brainstorm→plan failed_post_check: 门控不触发（非 scan 源）")
+}
+
+console.log('\n=== 接口向后兼容：options 第 3 位可选 ===')
+{
+  // 仅 2 参调用（最常见旧用法）
+  const r = checkTransition('brainstorm', 'plan')
+  assert(r && typeof r.allowed === 'boolean', '2 参调用返回 { allowed: boolean }')
+}
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(`${'='.repeat(50)}`)
+if (failed > 0) process.exit(1)

package/test/stage-contract.test.mjs

@@ -0,0 +1,299 @@
+/**
+ * StageContract 状态转换 + validator 测试
+ */
+import { checkTransition, runValidators, getContract } from '../src/stage-contract.js'
+
+let failed = 0
+
+// === 状态转换测试 ===
+const transitionTests = [
+  // [from, to, expectedAllowed]
+  // 主流程正常顺序
+  ['', 'brainstorm', true],
+  ['brainstorm', 'plan', true],
+  ['plan', 'execute', true],
+  ['execute', 'verify', true],
+  ['verify', 'archive', true],
+
+  // 跳步应被拦截
+  ['', 'plan', false],
+  ['', 'execute', false],
+  ['brainstorm', 'execute', false],
+  ['plan', 'verify', false],
+  ['execute', 'archive', false],
+
+  // 回退应被拦截
+  ['plan', 'brainstorm', false],
+  ['execute', 'plan', false],
+  ['verify', 'execute', false],
+
+  // 辅助阶段随时可执行
+  ['', 'scan', true],
+  ['', 'quick', true],
+  ['', 'explore', true],
+  ['', 'doctor', true],
+  ['', 'archive', true],
+  ['brainstorm', 'scan', true],
+  ['plan', 'quick', true],
+  ['execute', 'doctor', true],
+
+  // 从辅助阶段进入主流程允许
+  ['scan', 'plan', true],
+  ['scan', 'brainstorm', true],
+  ['quick', 'plan', true],
+  ['doctor', 'brainstorm', true],
+
+  // archive 特殊：verify 后允许，其他主流程不允许直接跳
+  ['verify', 'archive', true],
+  ['execute', 'archive', false],
+  ['plan', 'archive', false],
+]
+
+console.log('=== 状态转换测试 ===')
+for (const [from, to, expected] of transitionTests) {
+  const r = checkTransition(from, to)
+  const ok = r.allowed === expected
+  if (!ok) failed++
+  console.log(ok ? '✅' : '❌', `${from || '(起始)'} → ${to}: allowed=${r.allowed} (exp ${expected})${ok ? '' : ' reason: ' + r.reason}`)
+}
+
+// === Validator 测试 ===
+console.log('\n=== Validator 测试 ===')
+
+// plan validator：plan.md 不存在应报错
+const planResult = runValidators('plan', '.', 'nonexistent-change')
+if (planResult.ok === false && planResult.errors.length > 0) {
+  console.log('✅ plan validator 检测到缺失 plan.md')
+} else {
+  console.log('❌ plan validator 未检测到缺失 plan.md')
+  failed++
+}
+
+// verify validator：变更目录不存在应报错
+const verifyResult = runValidators('verify', '.', 'nonexistent-change')
+if (verifyResult.ok === false && verifyResult.errors.length > 0) {
+  console.log('✅ verify validator 检测到缺失变更目录')
+} else {
+  console.log('❌ verify validator 未检测到缺失变更目录')
+  failed++
+}
+
+// scan validator：文档目录不存在应报错
+const scanResult = runValidators('scan', join(tmpdir(), 'nonexistent-project'), 'test', { projectName: 'test' })
+if (scanResult.ok === false && scanResult.errors.length > 0) {
+  console.log('✅ scan validator 检测到缺失 scan 文档')
+} else {
+  console.log('❌ scan validator 未检测到缺失 scan 文档')
+  failed++
+}
+
+// brainstorm 有 validator，但变更目录不存在时应该报错（因为产物不存在）
+const brainstormResult = runValidators('brainstorm', '.', 'test')
+if (brainstormResult.ok === false && brainstormResult.errors.length > 0) {
+  console.log('✅ brainstorm validator 检测到缺失产物文件')
+} else {
+  console.log('❌ brainstorm validator 未检测到缺失产物')
+  failed++
+}
+
+// === scan validator 平台模式 specRoot 测试 ===
+console.log('\n=== scan validator specRoot 测试 ===')
+
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+// 创建临时 specRoot 结构
+const specRoot = mkdtempSync(join(tmpdir(), 'sillyspec-test-'))
+const sourceRoot = mkdtempSync(join(tmpdir(), 'sillyspec-source-'))
+const projectName = 'myaaa'
+
+// specRoot 在实际代码中等价于 .sillyspec 目录本身（run.js: join(specRoot, 'docs', ...)）
+// 所以 scan 文档路径为 specRoot/docs/<project>/scan/，不需要额外的 .sillyspec/ 前缀
+const specDocsDir = join(specRoot, 'docs', projectName, 'scan')
+mkdirSync(specDocsDir, { recursive: true })
+for (const doc of ['ARCHITECTURE.md', 'CONVENTIONS.md', 'STRUCTURE.md', 'INTEGRATIONS.md', 'TESTING.md', 'CONCERNS.md', 'PROJECT.md']) {
+  writeFileSync(join(specDocsDir, doc), '# ' + doc)
+}
+mkdirSync(join(specRoot, 'docs', projectName, 'modules'), { recursive: true })
+writeFileSync(join(specRoot, 'docs', projectName, 'modules', 'app.md'), '# app')
+
+// 测试1：使用 specRoot 校验成功
+const specResult = runValidators('scan', sourceRoot, 'test', { projectName, specRoot })
+if (specResult.ok === true) {
+  console.log('✅ scan validator 使用 specRoot 校验通过')
+} else {
+  console.log('❌ scan validator specRoot 校验失败:', specResult.errors)
+  failed++
+}
+
+// 测试2：使用 sourceRoot 校验（不传 specRoot）应失败
+const localResult = runValidators('scan', sourceRoot, 'test', { projectName })
+if (localResult.ok === false && localResult.errors.length > 0) {
+  console.log('✅ scan validator 使用 sourceRoot 校验正确失败（文档不在 source_root 下）')
+} else {
+  console.log('❌ scan validator sourceRoot 校验未正确失败')
+  failed++
+}
+
+// 测试3：校验路径指向 specRoot 而非 sourceRoot
+const errors1 = localResult.errors.join(' ')
+const errors2 = specResult.errors.join(' ')
+if (errors1.includes(sourceRoot) || errors1.includes(join(sourceRoot, '.sillyspec'))) {
+  console.log('✅ 未传 specRoot 时校验路径指向 source_root')
+} else {
+  console.log('✅ 未传 specRoot 时校验失败（文档确实不在 source_root 下）')
+}
+if (!errors2.includes(specRoot)) {
+  console.log('✅ 传 specRoot 时校验路径指向 specRoot（无错误=不包含路径）')
+} else {
+  console.log('✅ 传 specRoot 时校验路径正确')
+}
+
+// 清理临时目录
+rmSync(specRoot, { recursive: true })
+rmSync(sourceRoot, { recursive: true })
+
+// === decisions.md traceability validator 测试 ===
+console.log('\n=== decisions traceability validator 测试 ===')
+
+const traceRoot = mkdtempSync(join(tmpdir(), 'sillyspec-trace-'))
+const traceDir = join(traceRoot, '.sillyspec', 'changes', 'trace')
+mkdirSync(traceDir, { recursive: true })
+writeFileSync(join(traceDir, 'proposal.md'), '# Proposal\n\n## 不在范围内\n- none\n')
+writeFileSync(join(traceDir, 'design.md'), '# Design\n\n## 文件变更清单\n\n## 风险登记\n\n## 自审\n\nD-001@v1\n')
+writeFileSync(join(traceDir, 'decisions.md'), '# Decisions\n\n## D-001@v1: Choose canonical account term\n- priority: P1\n- status: accepted\n')
+writeFileSync(join(traceDir, 'requirements.md'), '# Requirements\n\n### FR-01: Account naming\nGiven x\nWhen y\nThen z\n')
+writeFileSync(join(traceDir, 'tasks.md'), '- [ ] task-01: implement naming (D-001@v1)\n')
+
+const brainstormTrace = runValidators('brainstorm', traceRoot, 'trace')
+if (brainstormTrace.ok === true && brainstormTrace.warnings.some(w => w.includes('requirements.md 未引用') && w.includes('D-001@V1'))) {
+  console.log('✅ brainstorm validator 检测到 requirements.md 缺少 D-001@v1 引用')
+} else {
+  console.log('❌ brainstorm validator 未检测到 requirements.md 缺少 D-001@v1 引用', brainstormTrace)
+  failed++
+}
+
+writeFileSync(join(traceDir, 'requirements.md'), '# Requirements\n\n### FR-01: Account naming\n覆盖决策：D-001@v1\nGiven x\nWhen y\nThen z\n')
+writeFileSync(join(traceDir, 'plan.md'), '# Plan\n\n- [ ] task-01: implement naming\n')
+
+const planTrace = runValidators('plan', traceRoot, 'trace')
+if (planTrace.ok === true
+  && planTrace.warnings.some(w => w.includes('plan.md 未引用') && w.includes('FR-01'))
+  && planTrace.warnings.some(w => w.includes('plan.md 未引用') && w.includes('D-001@V1'))) {
+  console.log('✅ plan validator 检测到 plan.md 缺少 FR-01/D-001@v1 引用')
+} else {
+  console.log('❌ plan validator 未检测到 plan.md 缺少追踪 ID', planTrace)
+  failed++
+}
+
+writeFileSync(join(traceDir, 'plan.md'), '# Plan\n\n- [ ] task-01: implement naming（覆盖：FR-01, D-001@v1）\n')
+writeFileSync(join(traceDir, 'verify-result.md'), '# Verify\n\nPASS\n')
+
+const verifyTrace = runValidators('verify', traceRoot, 'trace')
+if (verifyTrace.ok === true && verifyTrace.warnings.some(w => w.includes('verify-result.md 未引用') && w.includes('D-001@V1'))) {
+  console.log('✅ verify validator 检测到 verify-result.md 缺少 D-001@v1 引用')
+} else {
+  console.log('❌ verify validator 未检测到 verify-result.md 缺少 D-001@v1 引用', verifyTrace)
+  failed++
+}
+
+writeFileSync(join(traceDir, 'verify-result.md'), '# Verify\n\n## 决策追踪矩阵\n| D-001@v1 | FR-01 | task-01 | evidence | PASS |\n')
+const verifyTraceOk = runValidators('verify', traceRoot, 'trace')
+if (verifyTraceOk.ok === true && !verifyTraceOk.warnings.some(w => w.includes('D-001@V1'))) {
+  console.log('✅ verify validator 在 D-001@v1 已覆盖时不再报警')
+} else {
+  console.log('❌ verify validator 覆盖后仍报警', verifyTraceOk)
+  failed++
+}
+
+writeFileSync(join(traceDir, 'decisions.md'), '# Decisions\n\n## D-002@v1: Unresolved schema conflict\n- priority: P0\n- status: unresolved\n')
+const blockerTrace = runValidators('plan', traceRoot, 'trace')
+if (blockerTrace.ok === false && blockerTrace.errors.some(e => e.includes('P0/P1 未决阻塞') && e.includes('D-002@V1'))) {
+  console.log('✅ plan validator 阻止 P0 unresolved decision 进入 plan')
+} else {
+  console.log('❌ plan validator 未阻止 P0 unresolved decision', blockerTrace)
+  failed++
+}
+
+writeFileSync(join(traceDir, 'decisions.md'), '# Decisions\n\n- id: D-003@v1\n  priority: P1\n  status: blocking\n  type: boundary\n')
+const yamlBlockerTrace = runValidators('plan', traceRoot, 'trace')
+if (yamlBlockerTrace.ok === false && yamlBlockerTrace.errors.some(e => e.includes('P0/P1 未决阻塞') && e.includes('D-003@V1'))) {
+  console.log('✅ plan validator 支持 list/YAML 风格 decision record')
+} else {
+  console.log('❌ plan validator 未识别 list/YAML 风格 decision record', yamlBlockerTrace)
+  failed++
+}
+
+writeFileSync(join(traceDir, 'decisions.md'), '# Decisions\n\n- id: D-004@v1\n  status: blocking\n  type: boundary\n')
+const missingPriorityTrace = runValidators('plan', traceRoot, 'trace')
+if (missingPriorityTrace.ok === false
+  && missingPriorityTrace.errors.some(e => e.includes('P0/P1 未决阻塞') && e.includes('D-004@V1') && e.includes('priority=missing->P1'))) {
+  console.log('✅ plan validator 将缺 priority 的 blocking decision 按 P1 阻断')
+} else {
+  console.log('❌ plan validator 未阻断缺 priority 的 blocking decision', missingPriorityTrace)
+  failed++
+}
+
+writeFileSync(join(traceDir, 'decisions.md'), '# Decisions\n\n- id: D-005@v1\n  status: accepted\n  type: term\n')
+writeFileSync(join(traceDir, 'plan.md'), '# Plan\n\n- [ ] task-01: implement naming（覆盖：FR-01）\n')
+const yamlAcceptedTrace = runValidators('plan', traceRoot, 'trace')
+if (yamlAcceptedTrace.ok === true && yamlAcceptedTrace.warnings.some(w => w.includes('plan.md 未引用') && w.includes('D-005@V1'))) {
+  console.log('✅ plan validator 将 YAML accepted decision 纳入追踪')
+} else {
+  console.log('❌ plan validator 未追踪 YAML accepted decision', yamlAcceptedTrace)
+  failed++
+}
+
+writeFileSync(join(traceDir, 'decisions.md'), '# Decisions\n')
+writeFileSync(join(traceDir, 'requirements.md'), '# Requirements\n\n普通说明提到 https://example.test/spec/FR-404 和注释里的 FR-405，但它们不是结构化需求 ID。\n')
+writeFileSync(join(traceDir, 'plan.md'), '# Plan\n\nNo structured requirement IDs here.\n')
+const looseIdTrace = runValidators('plan', traceRoot, 'trace')
+if (!looseIdTrace.warnings.some(w => w.includes('FR-404') || w.includes('FR-405'))) {
+  console.log('✅ plan validator 忽略普通正文/URL 中的 FR ID')
+} else {
+  console.log('❌ plan validator 误提取普通正文/URL 中的 FR ID', looseIdTrace)
+  failed++
+}
+
+writeFileSync(join(traceDir, 'decisions.md'), '# Decisions\n\n普通说明提到 https://example.test/spec/D-404@v1 和注释里的 D-405@v1，但它们不是结构化决策 ID。\n')
+const looseBrainstormTrace = runValidators('brainstorm', traceRoot, 'trace')
+if (!looseBrainstormTrace.warnings.some(w => w.includes('D-404@V1') || w.includes('D-405@V1'))) {
+  console.log('✅ brainstorm validator 忽略普通正文/URL 中的 D ID')
+} else {
+  console.log('❌ brainstorm validator 误提取普通正文/URL 中的 D ID', looseBrainstormTrace)
+  failed++
+}
+
+rmSync(traceRoot, { recursive: true })
+
+// === StageContract 结构测试 ===
+console.log('\n=== Contract 结构测试 ===')
+
+const plan = getContract('plan')
+if (plan.allowedFrom.includes('brainstorm') && plan.allowedTo.includes('execute') && plan.validators.length === 1) {
+  console.log('✅ plan contract 结构正确')
+} else {
+  console.log('❌ plan contract 结构异常:', JSON.stringify(plan))
+  failed++
+}
+
+const verify = getContract('verify')
+if (verify.allowedFrom.includes('execute') && verify.allowedTo.includes('archive')) {
+  console.log('✅ verify contract 结构正确')
+} else {
+  console.log('❌ verify contract 结构异常')
+  failed++
+}
+
+const unknown = getContract('nonexistent')
+if (unknown === null) {
+  console.log('✅ 未知阶段返回 null')
+} else {
+  console.log('❌ 未知阶段应返回 null')
+  failed++
+}
+
+// === 结果 ===
+console.log(`\n${failed === 0 ? '✅ 全部通过' : `❌ ${failed} 项失败`}`)
+if (failed > 0) throw new Error(`${failed} test(s) failed`)

package/test/stage-definitions.test.mjs

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict'
+import { stageRegistry } from '../src/stages/index.js'
+import { buildPlanSteps } from '../src/stages/plan.js'
+import { buildExecuteSteps } from '../src/stages/execute.js'
+
+const stageSteps = {
+  brainstorm: stageRegistry.brainstorm.steps,
+  scan: stageRegistry.scan.steps,
+  quick: stageRegistry.quick.steps,
+  archive: stageRegistry.archive.steps,
+  verify: stageRegistry.verify.steps,
+  plan: buildPlanSteps(null),
+  execute: buildExecuteSteps(null),
+}
+
+function names(stage) {
+  return stageSteps[stage].map(step => step.name)
+}
+
+function assertContains(stage, expectedNames) {
+  const actual = names(stage)
+  for (const name of expectedNames) {
+    assert.ok(actual.includes(name), `${stage} should include step "${name}". Actual: ${actual.join(', ')}`)
+  }
+}
+
+assert.equal(stageSteps.brainstorm.length, 13, 'brainstorm should include optional demand clarification and default Design Grill gates')
+assertContains('brainstorm', ['需求澄清 Grill', '写设计文档并自审', 'Design Grill 交叉审查', '用户确认并生成规范文件'])
+
+assert.equal(stageSteps.scan.length, 11, 'scan base definition should be 11 steps (with Extract Project Knowledge) before per-project expansion')
+assertContains('scan', ['构建扫描项目列表', '生成本地配置', '生成模块映射'])
+
+assert.equal(stageSteps.quick.length, 3, 'quick should remain a short auxiliary workflow')
+assertContains('quick', ['理解任务', '实现并验证', '暂存和更新记录'])
+
+assert.equal(stageSteps.archive.length, 5, 'archive should keep its five-step lifecycle')
+assertContains('archive', ['extract-module-impact', 'sync-module-docs', '确认归档'])
+
+console.log('✅ stage definition regression checks passed')