sillyspec 3.16.0 → 3.16.2

package/src/stage-contract.js

@@ -0,0 +1,349 @@
+/**
+ * StageContract — 阶段协议
+ *
+ * 每个阶段声明：允许的前置阶段、必须的产出、校验器、后续阶段。
+ * CLI 不再相信 prompt 完成，completeStep 后必须过 validator。
+ */
+
+import { existsSync, readdirSync } from 'fs'
+import { join, basename } from 'path'
+
+/**
+ * 校验结果
+ * @typedef {{ ok: boolean, errors: string[], warnings: string[] }} ValidationResult
+ */
+
+/**
+ * 阶段合约
+ * @typedef {{
+ *   stage: string,
+ *   description: string,
+ *   allowedFrom: string[],
+ *   allowedTo: string[],
+ *   validators: Function[],
+ * }} StageContract
+ */
+
+// ============ Validators ============
+
+/**
+ * scan 完成校验：检查 7 份 scan 文档 + manifest
+ */
+function validateScanOutputs(cwd, changeName, context = {}) {
+  const { projectName, specRoot } = context
+  // 平台模式使用 specRoot，本地模式使用 cwd
+  const base = specRoot || cwd
+  const docsRoot = projectName
+    ? join(base, '.sillyspec', 'docs', projectName, 'scan')
+    : join(base, '.sillyspec', 'docs', 'scan')
+
+  const requiredDocs = [
+    'ARCHITECTURE.md',
+    'CONVENTIONS.md',
+    'STRUCTURE.md',
+    'INTEGRATIONS.md',
+    'TESTING.md',
+    'CONCERNS.md',
+    'PROJECT.md',
+  ]
+
+  const errors = []
+  const warnings = []
+
+  for (const doc of requiredDocs) {
+    if (!existsSync(join(docsRoot, doc))) {
+      errors.push(`scan 文档缺失: ${docsRoot}/${doc}`)
+    }
+  }
+
+  // 检查 modules 目录
+  const modulesRoot = projectName
+    ? join(base, '.sillyspec', 'docs', projectName, 'modules')
+    : join(base, '.sillyspec', 'docs', 'modules')
+  if (!existsSync(modulesRoot)) {
+    warnings.push('modules 目录不存在')
+  } else {
+    const modules = readdirSync(modulesRoot).filter(f => f.endsWith('.md'))
+    if (modules.length === 0) {
+      warnings.push('modules 目录为空')
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+/**
+ * plan 完成校验：检查 plan.md 生成
+ */
+function validatePlanOutputs(cwd, changeName) {
+  const planDir = join(cwd, '.sillyspec', 'changes', changeName)
+  const planFile = join(planDir, 'plan.md')
+  const errors = []
+
+  if (!existsSync(planFile)) {
+    errors.push(`plan.md 缺失: ${planFile}`)
+  }
+
+  const warnings = []
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+/**
+ * verify 完成校验：检查 verify 报告存在
+ */
+function validateVerifyOutputs(cwd, changeName) {
+  const planDir = join(cwd, '.sillyspec', 'changes', changeName)
+  const errors = []
+  const warnings = []
+
+  // verify 至少应该有 run 记录
+  if (!existsSync(join(planDir, 'plan.md'))) {
+    errors.push(`变更目录缺失: ${planDir}`)
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+/**
+ * archive 完成校验：检查归档目录完整性
+ */
+function validateArchiveOutputs(cwd, changeName) {
+  const errors = []
+  const warnings = []
+  const archiveDir = join(cwd, '.sillyspec', 'changes', 'archive')
+  const date = new Date().toISOString().slice(0, 10)
+  const destDir = join(archiveDir, `${date}-${changeName}`)
+
+  // 检查归档目录是否存在
+  if (!existsSync(destDir)) {
+    errors.push(`归档目录缺失: ${destDir}`)
+    return { ok: false, errors, warnings }
+  }
+
+  // 检查核心文档
+  const requiredDocs = ['plan.md']
+  const recommendedDocs = ['design.md', 'module-impact.md']
+
+  for (const doc of requiredDocs) {
+    if (!existsSync(join(destDir, doc))) {
+      errors.push(`归档目录缺失核心文档: ${doc}`)
+    }
+  }
+
+  for (const doc of recommendedDocs) {
+    if (!existsSync(join(destDir, doc))) {
+      warnings.push(`归档目录缺少推荐文档: ${doc}`)
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+/**
+ * archive 前置校验：所有主流程阶段完成
+ */
+function validateChangeClosed(cwd, changeName) {
+  const errors = []
+  const warnings = []
+
+  // 检查前置阶段状态
+  const progressDir = join(cwd, '.sillyspec', '.runtime')
+  // 这里只做文件层面的检查，DB 检查在 run.js 里做
+  const changeDir = join(cwd, '.sillyspec', 'changes', changeName)
+  if (!existsSync(changeDir)) {
+    errors.push(`变更目录不存在: ${changeDir}`)
+    return { ok: false, errors, warnings }
+  }
+
+  if (!existsSync(join(changeDir, 'plan.md'))) {
+    errors.push(`plan.md 缺失 — 请确保 plan 阶段已完成`)
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+// ============ Contract Registry ============
+
+/**
+ * 主流程阶段（有严格转换顺序）
+ */
+const mainFlowStages = ['brainstorm', 'plan', 'execute', 'verify']
+
+/**
+ * 辅助阶段（可独立运行，无严格转换顺序）
+ */
+const auxiliaryStages = ['scan', 'quick', 'explore', 'archive', 'status', 'doctor']
+
+/**
+ * @type {Object<string, StageContract>}
+ */
+const contracts = {
+  // === 主流程 ===
+  brainstorm: {
+    stage: 'brainstorm',
+    description: '需求分析与设计',
+    allowedFrom: [],           // 任何变更的起始阶段
+    allowedTo: ['plan'],
+    validators: [],
+  },
+  plan: {
+    stage: 'plan',
+    description: '任务拆解与规划',
+    allowedFrom: ['brainstorm'],
+    allowedTo: ['execute'],
+    validators: [validatePlanOutputs],
+  },
+  execute: {
+    stage: 'execute',
+    description: '代码实现',
+    allowedFrom: ['plan'],
+    allowedTo: ['verify'],
+    validators: [],
+  },
+  verify: {
+    stage: 'verify',
+    description: '验证与测试',
+    allowedFrom: ['execute'],
+    allowedTo: ['archive'],
+    validators: [validateVerifyOutputs],
+  },
+  archive: {
+    stage: 'archive',
+    description: '归档与收口',
+    allowedFrom: ['verify'],
+    allowedTo: [],
+    validators: [validateChangeClosed, validateArchiveOutputs],
+  },
+
+  // === 辅助阶段 ===
+  scan: {
+    stage: 'scan',
+    description: '项目扫描',
+    allowedFrom: [],           // 无前置要求
+    allowedTo: [],             // 不进入主流程
+    validators: [validateScanOutputs],
+  },
+  quick: {
+    stage: 'quick',
+    description: '快速任务',
+    allowedFrom: [],           // 无前置要求
+    allowedTo: [],             // 不进入主流程
+    validators: [],
+  },
+  explore: {
+    stage: 'explore',
+    description: '代码探索',
+    allowedFrom: [],
+    allowedTo: [],
+    validators: [],
+  },
+  status: {
+    stage: 'status',
+    description: '状态查看',
+    allowedFrom: [],
+    allowedTo: [],
+    validators: [],
+  },
+  doctor: {
+    stage: 'doctor',
+    description: '环境诊断',
+    allowedFrom: [],
+    allowedTo: [],
+    validators: [],
+  },
+}
+
+// ============ Public API ============
+
+/**
+ * 获取阶段合约
+ */
+export function getContract(stageName) {
+  return contracts[stageName] || null
+}
+
+/**
+ * 校验状态转换是否允许
+ * @param {string} fromStage - 当前阶段（空字符串表示变更起始）
+ * @param {string} toStage - 目标阶段
+ * @returns {{ allowed: boolean, reason?: string }}
+ */
+export function checkTransition(fromStage, toStage) {
+  const contract = contracts[toStage]
+  if (!contract) {
+    return { allowed: false, reason: `未知阶段: ${toStage}` }
+  }
+
+  // 辅助阶段随时可执行（archive 除外：从主流程进入 archive 需要校验）
+  if (auxiliaryStages.includes(toStage) && toStage !== 'archive') {
+    return { allowed: true }
+  }
+
+  // archive 特殊处理：从 verify 来的允许，从其他主流程阶段来的需要校验
+  if (toStage === 'archive') {
+    if (fromStage === 'verify') {
+      return { allowed: true }
+    }
+    // 独立运行 archive（无前置）也允许
+    if (!fromStage || auxiliaryStages.includes(fromStage)) {
+      return { allowed: true }
+    }
+    return { allowed: false, reason: 'archive 的前置阶段是 verify，不能从 ' + fromStage + ' 跳转' }
+  }
+
+  // 从辅助阶段进入主流程：允许（用户可能 scan 完直接 brainstorm 或 plan）
+  if (auxiliaryStages.includes(fromStage)) {
+    return { allowed: true }
+  }
+
+  // 无前置阶段（变更起始）：只能开始 brainstorm 或辅助阶段
+  if (!fromStage) {
+    // 主流程必须从 brainstorm 开始
+    if (contract.allowedFrom.length === 0) {
+      return { allowed: true }
+    }
+    return { allowed: false, reason: `${toStage} 需要先完成 ${contract.allowedFrom.join(' 或 ')}` }
+  }
+
+  // 主流程内部跳转：检查目标阶段的 allowedFrom 是否包含 fromStage
+  if (contract.allowedFrom.includes(fromStage)) {
+    return { allowed: true }
+  }
+
+  return { allowed: false, reason: `${toStage} 的前置阶段是 ${contract.allowedFrom.join(' 或 ')}，不能从 ${fromStage} 跳转` }
+}
+
+/**
+ * 执行阶段完成校验
+ * @param {string} stageName
+ * @param {string} cwd
+ * @param {string} changeName
+ * @param {object} context - 额外上下文（如 projectName）
+ * @returns {ValidationResult}
+ */
+export function runValidators(stageName, cwd, changeName, context = {}) {
+  const contract = contracts[stageName]
+  if (!contract || contract.validators.length === 0) {
+    return { ok: true, errors: [], warnings: [] }
+  }
+
+  const allErrors = []
+  const allWarnings = []
+
+  for (const validator of contract.validators) {
+    try {
+      const result = validator(cwd, changeName, context)
+      allErrors.push(...(result.errors || []))
+      allWarnings.push(...(result.warnings || []))
+    } catch (e) {
+      allErrors.push(`校验器 ${validator.name || 'unknown'} 异常: ${e.message}`)
+    }
+  }
+
+  return { ok: allErrors.length === 0, errors: allErrors, warnings: allWarnings }
+}
+
+/**
+ * 获取所有主流程阶段
+ */
+export { mainFlowStages, auxiliaryStages }

package/src/stages/archive.js

@@ -124,15 +124,14 @@ module_id: <module-id>
     },
     {
       name: '确认归档',
-      prompt: `确认归档内容并执行目录移动。
+      prompt: `确认归档内容，由 CLI 执行目录移动。
 
 ### 操作
 1. 展示：变更目录名、包含的文件列表（含 module-impact.md）、生成总结
-2. **直接执行归档**（本步骤完成后自动移动）：
-   - 创建 archive 目录：\`mkdir -p .sillyspec/changes/archive\`
-   - 移动变更目录：\`mv .sillyspec/changes/<change-name> .sillyspec/changes/archive/<change-name>\`
-   - 确认移动成功：\`ls .sillyspec/changes/archive/<change-name>/\`
-3. 确保所有 checkbox 都已勾选
+2. 确保所有 checkbox 都已勾选
+3. 让用户确认后，用 \`--confirm\` 完成本步骤：
+   \`sillyspec run archive --done --confirm --output "确认归档"\`
+4. CLI 会创建 \`.sillyspec/changes/archive/\`，并将变更目录移动到 \`.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/\`
 
 ### 输出
 归档完成 + archive 目录路径`,
@@ -147,10 +146,7 @@ module_id: <module-id>
 1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
 2. \`git add .sillyspec/changes/\` — 暂存归档结果（不要 commit，由用户通过统一提交工具处理）
 3. \`git add .sillyspec/docs/\` — 暂存模块文档更新（如有）
-4. 更新 sillyspec.db 中的阶段状态：
-   - 清除当前变更信息（归档后不再活跃）
-   - 如果是主变更（有 MASTER.md），标记所有阶段为 ✅，然后清除
-   - 历史记录追加时间 + 归档完成
+4. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
 
 ### 输出
 归档完成确认 + 累积规范统计`,

package/src/stages/brainstorm.js

@@ -274,7 +274,10 @@ design.md 文件路径 + 自审结果
 ### 注意
 - 自审不通过不要进入下一步
 - 不确定的问题标注「⚠️ 自审存疑」`,
-
+      outputHint: 'design.md 文件路径 + 自审结果',
+      optional: false
+    },
+    {
       name: '用户确认并生成规范文件',
       prompt: `用户确认设计方案，生成规范文件。
 

package/src/stages/doctor.js

@@ -84,7 +84,6 @@ for f in .sillyspec/projects/*.yaml; do
   stack_md="$p/.sillyspec/STACK.md"
   [ -f "$local_yaml" ] && echo "✅ local.yaml ($name)" || echo "⚠️ local.yaml ($name) — 不存在"
   if [ -f "$local_yaml" ]; then
-    grep -q 'build:' "$local_yaml" && echo "  ✅ build 命令已配置" || echo "  ⚠️ 缺少 build 命令"
     grep -q 'test:' "$local_yaml" && echo "  ✅ test 命令已配置" || echo "  ⚠️ 缺少 test 命令"
   fi
   [ -f "$stack_md" ] && echo "✅ STACK.md ($name)" || echo "⚠️ STACK.md ($name) — 不存在"
@@ -346,7 +345,7 @@ timeout 5 which docker 2>/dev/null && echo "✅ Docker 可用" || echo "ℹ️ D
 **常见问题及修复：**
 - CLI 未安装 → \`npm install -g sillyspec\`
 - 缺少 local.yaml → \`sillyspec init\` 重新生成，或手动创建
-- local.yaml 缺少 build/test → 补充对应命令
+- local.yaml 缺少 test 命令 → 补充对应命令
 - 缺少 STACK.md → \`sillyspec run scan\` 重新扫描
 - sillyspec.db 状态不一致 → \`sillyspec run <阶段> --reset\` 重置对应阶段
 - 孤儿目录 → 确认后 \`rm -rf .sillyspec/changes/<目录名>\`

package/src/stages/propose.js

@@ -109,7 +109,10 @@ export const definition = {
 - 表名/字段名/类名必须来自真实代码或标注"新增"
 - 用户场景必须用 Given/When/Then 格式
 - tasks.md 只列任务名，细节在 plan 阶段展开`,
-
+      outputHint: '四个文件路径',
+      optional: false
+    },
+    {
       name: '自检门控',
       prompt: `自检生成的规范文件。
 

package/src/stages/scan.js

@@ -139,16 +139,16 @@ export const definition = {
     },
     {
       name: '生成本地配置',
-      prompt: `自动生成 .sillyspec/.runtime/local.yaml 本地配置文件。
+      prompt: `自动生成 .sillyspec/local.yaml 本地配置文件。
 
 ### 操作
-1. 检查 .sillyspec/.runtime/local.yaml 是否已存在，已存在则跳过（提示"local.yaml 已存在，跳过生成"）
+1. 检查 .sillyspec/local.yaml 是否已存在，已存在则跳过（提示"local.yaml 已存在，跳过生成"）
 2. 根据项目类型生成默认配置：
    - **Node.js**（有 package.json）：build: "npm run build", test: "npm test", lint: "npm run lint", type: nodejs
    - **Maven**（有 pom.xml）：build: "mvn compile", test: "mvn test", lint: "mvn checkstyle:check", type: maven
    - **Gradle**（有 build.gradle）：build: "./gradlew build", test: "./gradlew test", type: gradle
    - **通用项目**：只写注释模板, type: generic
-3. 确保目录存在：mkdir -p .sillyspec/.runtime
+3. 确保目录存在：mkdir -p .sillyspec
 4. 原子写入（先写 tmp 文件再 rename）
 
 ### 文件格式

package/test/check-syntax.mjs

@@ -0,0 +1,26 @@
+import { execFileSync } from 'node:child_process'
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const roots = ['src']
+const files = []
+
+function walk(dir) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry)
+    const st = statSync(full)
+    if (st.isDirectory()) {
+      walk(full)
+      continue
+    }
+    if (/\.(js|cjs|mjs)$/.test(entry)) files.push(full)
+  }
+}
+
+for (const root of roots) walk(root)
+
+for (const file of files.sort()) {
+  execFileSync(process.execPath, ['--check', file], { stdio: 'inherit' })
+}
+
+console.log(`Checked ${files.length} JavaScript files`)

package/test/run-tests.mjs

@@ -0,0 +1,20 @@
+import { readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const testDir = dirname(fileURLToPath(import.meta.url))
+const files = readdirSync(testDir)
+  .filter(file => file.endsWith('.test.mjs'))
+  .sort()
+
+if (files.length === 0) {
+  console.log('No test files found')
+  process.exit(0)
+}
+
+for (const file of files) {
+  console.log(`\nRunning ${file}`)
+  await import(pathToFileURL(join(testDir, file)).href)
+}
+
+console.log(`\nAll ${files.length} test file(s) passed`)

package/test/stage-contract.test.mjs

@@ -0,0 +1,185 @@
+/**
+ * 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', '/tmp/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++
+}
+
+// 无 validator 的阶段应该 pass
+const brainstormResult = runValidators('brainstorm', '.', 'test')
+if (brainstormResult.ok === true) {
+  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 下创建正确的 scan 文档
+const specDocsDir = join(specRoot, '.sillyspec', '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, '.sillyspec', 'docs', projectName, 'modules'), { recursive: true })
+writeFileSync(join(specRoot, '.sillyspec', '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.replace('/tmp/', '')) || errors1.includes(join(sourceRoot, '.sillyspec').slice(-30))) {
+  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 })
+
+// === 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} 项失败`}`)
+process.exit(failed > 0 ? 1 : 0)