sillyspec 3.18.5 → 3.19.0

package/src/task-review.js

@@ -0,0 +1,346 @@
+/**
+ * SillySpec Task Review Gate — execute 阶段任务级评审校验
+ *
+ * execute 阶段每个 task 完成后，controller 必须写入 review.json。
+ * execute --done 时 CLI 硬校验：缺失 review 或 verdict 不通过则阻断。
+ *
+ * 目录结构：
+ *   .sillyspec/.runtime/execute-runs/<runId>/tasks/<taskId>/review.json
+ */
+
+import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync } from 'fs'
+import { join, resolve } from 'path'
+
+// ── review.json schema version ──
+export const REVIEW_SCHEMA_VERSION = 1
+
+// ── 合法 verdict 枚举 ──
+export const VALID_VERDICTS = ['pass', 'fail', 'cannot_verify']
+
+/**
+ * 解析 plan.md 中的 task 列表
+ * @param {string} planContent - plan.md 文件内容
+ * @returns {string[]} task id 列表，如 ['task-01', 'task-02']
+ */
+export function parseTaskIdsFromPlan(planContent) {
+  if (!planContent) return []
+  const ids = new Set()
+  const re = /^\s*[-*]\s*\[[ x]\]\s*task-(\d+)/gim
+  for (const m of planContent.matchAll(re)) {
+    ids.add(`task-${m[1].padStart(2, '0')}`)
+  }
+  return [...ids].sort()
+}
+
+/**
+ * 校验单个 review.json 文件
+ * @param {object} review - 解析后的 JSON 对象
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateReviewSchema(review) {
+  const errors = []
+  if (!review || typeof review !== 'object') {
+    errors.push('review.json 不是有效 JSON 对象')
+    return { ok: false, errors }
+  }
+
+  if (review.schemaVersion !== REVIEW_SCHEMA_VERSION) {
+    errors.push(`schemaVersion 应为 ${REVIEW_SCHEMA_VERSION}，实际为 ${review.schemaVersion}`)
+  }
+
+  if (!review.task || typeof review.task !== 'string') {
+    errors.push('缺少 task 字段（应为 "task-XX" 格式）')
+  }
+
+  if (!VALID_VERDICTS.includes(review.specVerdict)) {
+    errors.push(`specVerdict 无效：${review.specVerdict}（应为 ${VALID_VERDICTS.join('/')})`)
+  }
+
+  if (!VALID_VERDICTS.includes(review.qualityVerdict)) {
+    errors.push(`qualityVerdict 无效：${review.qualityVerdict}（应为 ${VALID_VERDICTS.join('/')})`)
+  }
+
+  // cannot_verify 必须提供 requiredEvidence
+  if (review.specVerdict === 'cannot_verify' || review.qualityVerdict === 'cannot_verify') {
+    if (!Array.isArray(review.requiredEvidence) || review.requiredEvidence.length === 0) {
+      errors.push('cannot_verify 的 verdict 必须提供非空的 requiredEvidence 数组')
+    }
+  }
+
+  // base/head 非空检查
+  if (!review.base || typeof review.base !== 'string') {
+    errors.push('缺少 base 字段（git commit hash）')
+  }
+  if (!review.head || typeof review.head !== 'string') {
+    errors.push('缺少 head 字段（git commit hash）')
+  }
+
+  return { ok: errors.length === 0, errors }
+}
+
+/**
+ * 读取单个 task 的 review.json
+ * @param {string} reviewPath - review.json 文件路径
+ * @returns {{ ok: boolean, review: object|null, errors: string[] }}
+ */
+export function readReview(reviewPath) {
+  if (!existsSync(reviewPath)) {
+    return { ok: false, review: null, errors: ['review.json 不存在'] }
+  }
+
+  let raw
+  try {
+    raw = readFileSync(reviewPath, 'utf8')
+  } catch (e) {
+    return { ok: false, review: null, parseError: true, errors: [`review.json 读取失败: ${e.message}`] }
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (e) {
+    // 文件存在但 JSON 非法：review 设为 null 但标记 parseError=true
+    return { ok: false, review: null, parseError: true, errors: [`review.json 解析失败: ${e.message}`] }
+  }
+
+  const schemaResult = validateReviewSchema(parsed)
+  if (!schemaResult.ok) {
+    return { ok: false, review: parsed, schemaError: true, errors: schemaResult.errors }
+  }
+
+  return { ok: true, review: parsed, errors: [] }
+}
+
+/**
+ * execute --done 时的 task review 总校验
+ *
+ * 规则：
+ *   - 每个 plan task 必须有 review.json
+ *   - specVerdict 或 qualityVerdict 为 fail → 整体 fail
+ *   - specVerdict 或 qualityVerdict 为 cannot_verify → warning（requiredEvidence 非空）
+ *   - cannot_verify + requiredEvidence 为空 → fail（agent 逃避判断）
+ *   - cannot_verify 的 requiredEvidence 汇总到 requiredEvidence 字段，供 verify 阶段消费
+ *
+ * @param {object} opts
+ * @param {string} opts.planContent - plan.md 内容
+ * @param {string} opts.runtimeRoot - .sillyspec/.runtime 的绝对路径
+ * @param {string} opts.executeRunId - execute run id（如 'exec-2026-06-23-131400'）
+ * @param {boolean} [opts.allowCannotVerify=true] - 是否允许 cannot_verify（默认允许，给 warning）
+ * @returns {{ ok: boolean, errors: string[], warnings: string[], requiredEvidence: Array<{task: string, verdict: string, evidence: string[]}> }}
+ */
+export function validateTaskReviews(opts) {
+  const { planContent, runtimeRoot, executeRunId, allowCannotVerify = true } = opts
+
+  const taskIds = parseTaskIdsFromPlan(planContent)
+
+  // 如果 plan 里没有 task，跳过校验（向后兼容）
+  if (taskIds.length === 0) {
+    return { ok: true, errors: [], warnings: [], requiredEvidence: [] }
+  }
+
+  const errors = []
+  const warnings = []
+  const requiredEvidence = []
+
+  for (const taskId of taskIds) {
+    const reviewDir = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', taskId)
+    const reviewPath = join(reviewDir, 'review.json')
+
+    const result = readReview(reviewPath)
+
+    if (!result.ok) {
+      if (result.parseError) {
+        // review.json 存在但 JSON 非法
+        errors.push(`${taskId}: review.json 解析失败 — ${result.errors.join('; ')}`)
+      } else if (result.schemaError) {
+        // review.json 存在且 JSON 合法，但 schema 校验失败
+        errors.push(`${taskId}: review.json 校验失败 — ${result.errors.join('; ')}`)
+      } else {
+        // review.json 不存在
+        errors.push(`${taskId}: 缺少 review.json — task 未经过评审`)
+      }
+      continue
+    }
+
+    const review = result.review
+
+    // 检查 review.task 是否与 plan 中的 taskId 一致
+    if (review.task && review.task !== taskId) {
+      errors.push(`${taskId}: review.json 中的 task 字段为 "${review.task}"，与 plan 不一致（应为 "${taskId}"）— agent 可能复制模板未修改`)
+      continue
+    }
+
+    // 检查 fail verdict
+    if (review.specVerdict === 'fail' || review.qualityVerdict === 'fail') {
+      errors.push(`${taskId}: review 未通过 — spec: ${review.specVerdict}, quality: ${review.qualityVerdict}`)
+      if (review.reviewerNotes) {
+        errors.push(`${taskId}: ${review.reviewerNotes}`)
+      }
+      continue
+    }
+
+    // 检查 cannot_verify
+    if (review.specVerdict === 'cannot_verify' || review.qualityVerdict === 'cannot_verify') {
+      if (!allowCannotVerify) {
+        errors.push(`${taskId}: cannot_verify 不被允许 — 必须提供评审结果`)
+        continue
+      }
+
+      if (review.requiredEvidence && review.requiredEvidence.length > 0) {
+        const verdicts = []
+        if (review.specVerdict === 'cannot_verify') verdicts.push('spec')
+        if (review.qualityVerdict === 'cannot_verify') verdicts.push('quality')
+        warnings.push(`${taskId}: ${verdicts.join('+')}=cannot_verify，requiredEvidence 必须在 verify 阶段满足`)
+        requiredEvidence.push({
+          task: taskId,
+          verdict: verdicts.join('+'),
+          evidence: review.requiredEvidence,
+        })
+      } else {
+        // cannot_verify + 空 requiredEvidence = agent 逃避判断
+        errors.push(`${taskId}: cannot_verify 但 requiredEvidence 为空 — 这是无效评审`)
+      }
+    }
+  }
+
+  // 额外检查：扫描 execute-runs/<runId>/tasks/ 下是否有 plan 里没有的 task review
+  // （agent 可能写错了 task id）
+  try {
+    const tasksDir = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks')
+    if (existsSync(tasksDir)) {
+      const taskDirs = readdirSync(tasksDir, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => e.name)
+      const taskIdSet = new Set(taskIds)
+      for (const dirName of taskDirs) {
+        if (!taskIdSet.has(dirName) && existsSync(join(tasksDir, dirName, 'review.json'))) {
+          warnings.push(`${dirName}: 存在 review.json 但不在 plan.md 的 task 列表中（可能是多余文件）`)
+        }
+      }
+    }
+  } catch (e) {
+    warnings.push(`task review extra-check 异常: ${e.message}`)
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    requiredEvidence,
+  }
+}
+
+/**
+ * 将 cannot_verify 的 requiredEvidence 写入 change 目录
+ * 供 verify 阶段消费
+ *
+ * @param {string} changeDir - 变更目录（.sillyspec/changes/<name>）
+ * @param {Array<{task: string, verdict: string, evidence: string[]}>} requiredEvidence
+ * @returns {string|null} 写入的文件路径，null 表示无需写入
+ */
+export function writeVerifyRequiredEvidence(changeDir, requiredEvidence) {
+  if (!requiredEvidence || requiredEvidence.length === 0) return null
+
+  const filePath = join(changeDir, 'verify-required-evidence.json')
+  const data = {
+    generatedAt: new Date().toISOString(),
+    schemaVersion: 1,
+    items: requiredEvidence,
+  }
+
+  mkdirSync(changeDir, { recursive: true })
+  writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n')
+
+  return filePath
+}
+
+/**
+ * 生成 execute run id
+ * @returns {string} 如 'exec-2026-06-23-131400'
+ */
+export function generateExecuteRunId() {
+  const now = new Date()
+  const pad = (n) => String(n).padStart(2, '0')
+  return `exec-${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`
+}
+
+/**
+ * 获取当前（或最新）execute run id
+ * 从 runtime 目录下查找 execute-runs/ 子目录
+ *
+ * @param {string} runtimeRoot - .sillyspec/.runtime 路径
+ * @returns {string|null} 最新 run id，null 表示无任何 run
+ */
+/**
+ * 获取当前 execute run id
+ * 优先从 current-execute-run-id 标记文件读取（execute 阶段启动时写入），
+ * fallback 到 execute-runs/ 下最新的 exec- 前缀目录。
+ *
+ * @param {string} runtimeRoot - .sillyspec/.runtime 路径
+ * @returns {string|null} 当前 run id，null 表示无任何 run
+ */
+export function getLatestExecuteRunId(runtimeRoot) {
+  // 优先读标记文件（execute 阶段启动时由 run.js 写入，生命周期内不变）
+  const markerPath = join(runtimeRoot, 'current-execute-run-id')
+  try {
+    if (existsSync(markerPath)) {
+      const content = readFileSync(markerPath, 'utf8').trim()
+      if (content) return content
+    }
+  } catch {}
+
+  // fallback：扫描 execute-runs/ 目录
+  const runsDir = join(runtimeRoot, 'execute-runs')
+  if (!existsSync(runsDir)) return null
+
+  try {
+    const entries = readdirSync(runsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name.startsWith('exec-'))
+      .map(e => e.name)
+      .sort()
+      .reverse()
+    return entries[0] || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 确保 task review 目录存在
+ * @param {string} runtimeRoot
+ * @param {string} executeRunId
+ * @param {string} taskId
+ * @returns {string} task review 目录路径
+ */
+export function ensureTaskReviewDir(runtimeRoot, executeRunId, taskId) {
+  const dir = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', taskId)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+/**
+ * 打印校验结果
+ * @param {{ ok: boolean, errors: string[], warnings: string[], requiredEvidence: Array }} result
+ */
+export function printReviewResult(result) {
+  if (result.ok && result.warnings.length === 0) {
+    console.log('\n✅ Task Review Gate — 所有任务评审通过')
+    return
+  }
+
+  if (result.errors.length > 0) {
+    console.error('\n🚫 Task Review Gate — FAILED')
+    for (const err of result.errors) {
+      console.error(`   - ${err}`)
+    }
+    console.error('\n   提示：为缺失/失败的任务补充 review.json，然后重新 --done')
+  }
+
+  if (result.warnings.length > 0) {
+    console.warn('\n⚠️ Task Review Gate — WARNING')
+    for (const w of result.warnings) {
+      console.warn(`   - ${w}`)
+    }
+    console.warn('\n   cannot_verify 的 requiredEvidence 将在 verify 阶段校验')
+  }
+}

package/src/workflow.js

@@ -149,10 +149,13 @@ function replaceProjectPlaceholder(wf, projectName) {
  * @param {string} cwd - 项目根目录
  * @returns {CheckResult}
  */
-function checkOutput(outputDef, projectName, cwd) {
+function checkOutput(outputDef, projectName, cwd, specBase) {
+  // specBase 优先（平台模式 platformOpts.specRoot，已含或不含 .sillyspec 语义）；
+  // 未传时回退 join(cwd, '.sillyspec')，等价于旧行为 resolve(cwd, '.sillyspec/...')
+  const effectiveBase = specBase || join(cwd, '.sillyspec')
   // 将 <project> 替换为实际项目名
   const rawPath = (outputDef.path || '').replace(/<project>/g, projectName)
-  const fullPath = resolve(cwd, rawPath)
+  const fullPath = resolve(effectiveBase, rawPath)
   const checks = outputDef.checks || []
   const results = []
 
@@ -241,7 +244,7 @@ function checkOutput(outputDef, projectName, cwd) {
  *   retry_prompts: [{ role_id, role_name, prompt }]
  * }
  */
-export function runPostCheck(wf, cwd, projectName, placeholders = {}) {
+export function runPostCheck(wf, cwd, projectName, placeholders = {}, specBase) {
   let resolved = replaceProjectPlaceholder(wf, projectName)
   if (Object.keys(placeholders).length > 0) {
     let json = JSON.stringify(resolved)
@@ -250,10 +253,11 @@ export function runPostCheck(wf, cwd, projectName, placeholders = {}) {
     }
     resolved = JSON.parse(json)
   }
-  return _checkWorkflow(resolved, cwd, projectName)
+  return _checkWorkflow(resolved, cwd, projectName, specBase)
 }
 
-function _checkWorkflow(wf, cwd, projectName) {
+function _checkWorkflow(wf, cwd, projectName, specBase) {
+  const effectiveBase = specBase || join(cwd, '.sillyspec')
   const workflowName = wf.name || 'unknown'
   const specVersion = wf.spec_version || wf.version || 0
   const workflowChecks = wf.checks?.workflow_level || []
@@ -270,7 +274,7 @@ function _checkWorkflow(wf, cwd, projectName) {
 
     for (const outputDef of outputDefs) {
       const rawPath = (outputDef.path || '').replace(/<project>/g, projectName)
-      const checkResults = checkOutput(outputDef, projectName, cwd)
+      const checkResults = checkOutput(outputDef, projectName, cwd, effectiveBase)
       const outputPassed = checkResults.every(c => c.passed)
 
       outputs.push({
@@ -309,7 +313,7 @@ function _checkWorkflow(wf, cwd, projectName) {
   for (const check of workflowChecks) {
     switch (check.type) {
       case 'file_count': {
-        const scanDir = join(cwd, '.sillyspec', 'docs', projectName, check.path || 'scan/')
+        const scanDir = join(effectiveBase, 'docs', projectName, check.path || 'scan/')
         if (existsSync(scanDir)) {
           const files = readdirSync(scanDir).filter(f => f.endsWith('.md'))
           const min = check.min || 0
@@ -328,7 +332,7 @@ function _checkWorkflow(wf, cwd, projectName) {
         break
       }
       case 'no_empty_files': {
-        const scanDir = join(cwd, '.sillyspec', 'docs', projectName, check.path || 'scan/')
+        const scanDir = join(effectiveBase, 'docs', projectName, check.path || 'scan/')
         if (existsSync(scanDir)) {
           const files = readdirSync(scanDir).filter(f => f.endsWith('.md'))
           let anyEmpty = false

package/templates/workflows/scan-docs.yaml

@@ -13,7 +13,7 @@ roles:
       hints:
         grep_patterns: ["class ", "export ", "import ", "schema", "CREATE TABLE"]
     outputs:
-      - path: ".sillyspec/docs/<project>/scan/ARCHITECTURE.md"
+      - path: "{SPEC_ROOT}/docs/<project>/scan/ARCHITECTURE.md"
         required: true
         checks:
           - type: file_exists
@@ -33,7 +33,7 @@ roles:
       hints:
         grep_patterns: ["function ", "const ", "async ", "try ", "catch "]
     outputs:
-      - path: ".sillyspec/docs/<project>/scan/CONVENTIONS.md"
+      - path: "{SPEC_ROOT}/docs/<project>/scan/CONVENTIONS.md"
         required: true
         checks:
           - type: file_exists
@@ -53,13 +53,13 @@ roles:
       hints:
         grep_patterns: ["fetch", "http", "WebSocket", "ws", "chokidar"]
     outputs:
-      - path: ".sillyspec/docs/<project>/scan/STRUCTURE.md"
+      - path: "{SPEC_ROOT}/docs/<project>/scan/STRUCTURE.md"
         required: true
         checks:
           - type: file_exists
           - type: min_lines
             min: 15
-      - path: ".sillyspec/docs/<project>/scan/INTEGRATIONS.md"
+      - path: "{SPEC_ROOT}/docs/<project>/scan/INTEGRATIONS.md"
         required: true
         checks:
           - type: file_exists
@@ -77,14 +77,14 @@ roles:
       hints:
         grep_patterns: ["TODO", "FIXME", "deprecated", "test", "describe"]
     outputs:
-      - path: ".sillyspec/docs/<project>/scan/TESTING.md"
+      - path: "{SPEC_ROOT}/docs/<project>/scan/TESTING.md"
         required: true
         checks:
           - type: file_exists
           - type: min_lines
             min: 10
           - type: no_placeholder
-      - path: ".sillyspec/docs/<project>/scan/CONCERNS.md"
+      - path: "{SPEC_ROOT}/docs/<project>/scan/CONCERNS.md"
         required: true
         checks:
           - type: file_exists
@@ -92,7 +92,7 @@ roles:
             min: 10
           - type: contains_sections
             sections: ["代码质量", "依赖风险"]
-      - path: ".sillyspec/docs/<project>/scan/PROJECT.md"
+      - path: "{SPEC_ROOT}/docs/<project>/scan/PROJECT.md"
         required: true
         checks:
           - type: file_exists
@@ -126,7 +126,7 @@ on_check_failure: prompt_retry
 permissions:
   write_mode: direct
   write_scope:
-    - ".sillyspec/docs/<project>/scan/"
+    - "{SPEC_ROOT}/docs/<project>/scan/"
   allow_shell: true
   allow_network: false
   allow_git: false

package/test/cli-top-level-aliases.test.mjs

@@ -0,0 +1,174 @@
+/**
+ * task-10: 顶层命令别名 doctor/scan/status/quick/explore 转发 runCommand
+ *
+ * 设计依据：task-10.md §TDD + §验收标准
+ *   - sillyspec doctor / scan / status / quick / explore 不再落 default 分支报"未知命令"
+ *   - 行为与 sillyspec run <stage> 字节一致
+ *   - sillyspec worktree doctor 仍走 worktree 分支
+ *   - sillyspec foobar 仍报未知命令
+ *
+ * 断言策略：
+ *   stage 在空目录下可能因无 .sillyspec 进度而 exit != 0（这是 stage 自身行为，
+ *   不属于本任务路由范围）。因此测试只验证"路由正确"——即 stderr 不含"未知命令"
+ *   字样（default 分支的特征文案），并且 doctor/scan 两路 stdout 字节一致。
+ */
+
+import { spawnSync } from 'node:child_process'
+import { mkdirSync, rmSync } from 'node:fs'
+import { join, resolve, dirname } from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const cliBin = resolve(__dirname, '..', 'bin', 'sillyspec.js')
+
+let passed = 0
+let failed = 0
+
+function assert(cond, msg) {
+  if (cond) {
+    console.log(`  ✅ PASS: ${msg}`)
+    passed++
+  } else {
+    console.log(`  ❌ FAIL: ${msg}`)
+    failed++
+  }
+}
+
+function runCLI(args, cwd) {
+  const res = spawnSync(process.execPath, [cliBin, ...args], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 15000,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  })
+  return {
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+    status: res.status,
+    combined: (res.stdout || '') + (res.stderr || ''),
+  }
+}
+
+function cleanSillySpec(cwd) {
+  // 清掉 sillyspec 写入 cwd 的进度副作用，保证两路字节级环境一致
+  try { rmSync(join(cwd, '.sillyspec'), { recursive: true, force: true }) } catch {}
+  try { rmSync(join(cwd, '.sillyspec-platform.json'), { force: true }) } catch {}
+}
+
+const tmpRoot = join(tmpdir(), `sillyspec-cli-aliases-${Date.now()}`)
+mkdirSync(tmpRoot, { recursive: true })
+
+try {
+  // ── Red/Green: 5 个顶层命令不再报"未知命令" ──
+  const aliases = ['doctor', 'scan', 'status', 'quick', 'explore']
+  console.log('\n=== Test 1: 顶层命令别名不落 default 分支 ===')
+  for (const stage of aliases) {
+    const res = runCLI([stage], tmpRoot)
+    const hitUnknown =
+      res.combined.includes('未知命令') ||
+      /unknown command/i.test(res.combined)
+    assert(
+      !hitUnknown,
+      `sillyspec ${stage} 不报"未知命令" (exit=${res.status})`
+    )
+  }
+
+  // ── Green: doctor 顶层别名 与 sillyspec run doctor 字节一致 ──
+  // 两路必须在字节级相同环境下运行：同 cwd + 每次跑前清空 .sillyspec
+  // （否则 progress 持久化会让第二次跑读到旧数据触发平台同步检查）
+  console.log('\n=== Test 2: sillyspec doctor 与 sillyspec run doctor 等价 ===')
+  {
+    const cwd = join(tmpRoot, 'doctor-cmp')
+    mkdirSync(cwd, { recursive: true })
+    cleanSillySpec(cwd)
+    const top = runCLI(['doctor'], cwd)
+    cleanSillySpec(cwd)
+    const viaRun = runCLI(['run', 'doctor'], cwd)
+    assert(
+      top.status === viaRun.status,
+      `exit code 一致: doctor=${top.status}, run doctor=${viaRun.status}`
+    )
+    assert(
+      top.stdout === viaRun.stdout,
+      `stdout 字节一致 (len=${top.stdout.length})`
+    )
+    assert(
+      top.stderr === viaRun.stderr,
+      `stderr 字节一致 (len=${top.stderr.length})`
+    )
+  }
+
+  // ── Green: scan 顶层别名 与 sillyspec run scan 字节一致 ──
+  console.log('\n=== Test 3: sillyspec scan 与 sillyspec run scan 等价 ===')
+  {
+    const cwd = join(tmpRoot, 'scan-cmp')
+    mkdirSync(cwd, { recursive: true })
+    cleanSillySpec(cwd)
+    const top = runCLI(['scan'], cwd)
+    cleanSillySpec(cwd)
+    const viaRun = runCLI(['run', 'scan'], cwd)
+    assert(
+      top.status === viaRun.status,
+      `exit code 一致: scan=${top.status}, run scan=${viaRun.status}`
+    )
+    assert(
+      top.stdout === viaRun.stdout,
+      `stdout 字节一致 (len=${top.stdout.length})`
+    )
+  }
+
+  // ── 回归: worktree doctor 走 worktree 分支（与顶层 doctor 不同） ──
+  console.log('\n=== Test 4: sillyspec worktree doctor 走 worktree 分支 ===')
+  {
+    const res = runCLI(['worktree', 'doctor'], tmpRoot)
+    // worktree doctor 不应报顶层 default 的"未知命令"，也不应报"未知阶段"
+    const hitUnknownCmd =
+      res.combined.includes('未知命令') && !/worktree/.test(res.combined)
+    assert(!hitUnknownCmd, `worktree doctor 不报顶层未知命令`)
+    // worktree 子命令 default 分支会输出"未知子命令: worktree"，这里 doctor 合法不应出现
+    assert(
+      !res.combined.includes('未知子命令'),
+      `worktree doctor 不是未知子命令`
+    )
+  }
+
+  // ── 回归: foobar 仍落 default 报未知命令 ──
+  console.log('\n=== Test 5: sillyspec foobar 仍报未知命令 ===')
+  {
+    const res = runCLI(['foobar'], tmpRoot)
+    assert(
+      res.combined.includes('未知命令'),
+      `foobar 命中 default 分支，报"未知命令"`
+    )
+    assert(
+      res.status !== 0,
+      `foobar exit code 非 0 (got ${res.status})`
+    )
+  }
+
+  // ── 选项透传: sillyspec doctor --json 与 sillyspec run doctor --json 等价 ──
+  console.log('\n=== Test 6: doctor --json 选项透传正确 ===')
+  {
+    const top = runCLI(['doctor', '--json'], tmpRoot)
+    const viaRun = runCLI(['run', 'doctor', '--json'], tmpRoot)
+    assert(
+      top.stdout === viaRun.stdout,
+      `doctor --json stdout 与 run doctor --json 一致 (len=${top.stdout.length})`
+    )
+    assert(
+      top.status === viaRun.status,
+      `doctor --json exit 与 run doctor --json 一致`
+    )
+  }
+} finally {
+  try {
+    rmSync(tmpRoot, { recursive: true, force: true })
+  } catch {}
+}
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(`${'='.repeat(50)}`)
+process.exit(failed > 0 ? 1 : 0)