sillyspec 3.20.5 → 3.20.7

package/src/hooks/worktree-guard.js

@@ -119,104 +119,104 @@ function readWorktreeMeta(cwd, changeName) {
   }
 }
 
-function isPathInside(child, parent) {
-  if (!child || !parent) return false
-  const absChild = path.resolve(child)
-  const absParent = path.resolve(parent)
-  return absChild === absParent || absChild.startsWith(absParent + path.sep)
-}
-
-function toPosixPath(filePath) {
-  return filePath.replace(/\\/g, '/')
-}
-
-function parseFrontmatter(content) {
-  if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return {}
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/)
-  if (!match) return {}
-  const result = {}
-  for (const line of match[1].split(/\r?\n/)) {
-    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/)
-    if (!m) continue
-    result[m[1]] = m[2].replace(/^['"]|['"]$/g, '').trim()
-  }
-  return result
-}
-
-function parseTimestamp(value) {
-  if (!value) return null
-  const time = Date.parse(value)
-  return Number.isNaN(time) ? null : time
-}
-
-function getScanDocInfo(filePath) {
-  const normalized = toPosixPath(path.resolve(filePath))
-  const match = normalized.match(/^(.*)\/docs\/([^/]+)\/scan\/([^/]+\.md)$/)
-  if (!match) return null
-  return {
-    specRoot: path.resolve(match[1]),
-    projectName: match[2],
-    docName: match[3],
-  }
-}
-
-function readScanGuard(scanDocInfo, projectRoot) {
-  const candidates = [
-    path.join(scanDocInfo.specRoot, '.runtime', 'scan-guard.json'),
-    path.join(projectRoot, '.sillyspec', '.runtime', 'scan-guard.json'),
-  ]
-  for (const p of candidates) {
-    if (!existsSync(p)) continue
-    try {
-      return JSON.parse(readFileSync(p, 'utf8'))
-    } catch {
-      return null
-    }
-  }
-  return null
-}
-
-function shouldBlockScanDocOverwrite(filePath, projectRoot) {
-  const scanDocInfo = getScanDocInfo(filePath)
-  if (!scanDocInfo || !existsSync(filePath)) return { blocked: false }
-
-  const guard = readScanGuard(scanDocInfo, projectRoot)
-  if (!guard || guard.forceRescan) return { blocked: false }
-
-  let frontmatter = {}
-  try {
-    frontmatter = parseFrontmatter(readFileSync(filePath, 'utf8'))
-  } catch {
-    return { blocked: false }
-  }
-
-  const relPath = toPosixPath(path.relative(projectRoot, filePath))
-  if (frontmatter.source_commit && guard.sourceCommit && frontmatter.source_commit !== guard.sourceCommit) {
-    return {
-      blocked: true,
-      reason: [
-        `scan 覆盖保护：${relPath} 的 source_commit=${frontmatter.source_commit} 与当前 scan source_commit=${guard.sourceCommit} 不一致。`,
-        '如确认要重新生成，请重新运行 scan 并添加 --force-rescan。',
-      ].join('\n')
-    }
-  }
-
-  const existingUpdatedAt = parseTimestamp(frontmatter.updated_at)
-  const scanStartedAt = parseTimestamp(guard.startedAt)
-  if (existingUpdatedAt && scanStartedAt && existingUpdatedAt > scanStartedAt) {
-    return {
-      blocked: true,
-      reason: [
-        `scan 覆盖保护：${relPath} 的 updated_at 晚于本次 scan 开始时间，可能包含手工编辑。`,
-        '如确认要覆盖，请重新运行 scan 并添加 --force-rescan。',
-      ].join('\n')
-    }
-  }
-
-  return { blocked: false }
-}
-
-function isInsideWorktreeStorage(filePath, cwd) {
+function isPathInside(child, parent) {
+  if (!child || !parent) return false
+  const absChild = path.resolve(child)
+  const absParent = path.resolve(parent)
+  return absChild === absParent || absChild.startsWith(absParent + path.sep)
+}
+
+function toPosixPath(filePath) {
+  return filePath.replace(/\\/g, '/')
+}
+
+function parseFrontmatter(content) {
+  if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return {}
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/)
+  if (!match) return {}
+  const result = {}
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/)
+    if (!m) continue
+    result[m[1]] = m[2].replace(/^['"]|['"]$/g, '').trim()
+  }
+  return result
+}
+
+function parseTimestamp(value) {
+  if (!value) return null
+  const time = Date.parse(value)
+  return Number.isNaN(time) ? null : time
+}
+
+function getScanDocInfo(filePath) {
+  const normalized = toPosixPath(path.resolve(filePath))
+  const match = normalized.match(/^(.*)\/docs\/([^/]+)\/scan\/([^/]+\.md)$/)
+  if (!match) return null
+  return {
+    specRoot: path.resolve(match[1]),
+    projectName: match[2],
+    docName: match[3],
+  }
+}
+
+function readScanGuard(scanDocInfo, projectRoot) {
+  const candidates = [
+    path.join(scanDocInfo.specRoot, '.runtime', 'scan-guard.json'),
+    path.join(projectRoot, '.sillyspec', '.runtime', 'scan-guard.json'),
+  ]
+  for (const p of candidates) {
+    if (!existsSync(p)) continue
+    try {
+      return JSON.parse(readFileSync(p, 'utf8'))
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+function shouldBlockScanDocOverwrite(filePath, projectRoot) {
+  const scanDocInfo = getScanDocInfo(filePath)
+  if (!scanDocInfo || !existsSync(filePath)) return { blocked: false }
+
+  const guard = readScanGuard(scanDocInfo, projectRoot)
+  if (!guard || guard.forceRescan) return { blocked: false }
+
+  let frontmatter = {}
+  try {
+    frontmatter = parseFrontmatter(readFileSync(filePath, 'utf8'))
+  } catch {
+    return { blocked: false }
+  }
+
+  const relPath = toPosixPath(path.relative(projectRoot, filePath))
+  if (frontmatter.source_commit && guard.sourceCommit && frontmatter.source_commit !== guard.sourceCommit) {
+    return {
+      blocked: true,
+      reason: [
+        `scan 覆盖保护：${relPath} 的 source_commit=${frontmatter.source_commit} 与当前 scan source_commit=${guard.sourceCommit} 不一致。`,
+        '如确认要重新生成，请重新运行 scan 并添加 --force-rescan。',
+      ].join('\n')
+    }
+  }
+
+  const existingUpdatedAt = parseTimestamp(frontmatter.updated_at)
+  const scanStartedAt = parseTimestamp(guard.startedAt)
+  if (existingUpdatedAt && scanStartedAt && existingUpdatedAt > scanStartedAt) {
+    return {
+      blocked: true,
+      reason: [
+        `scan 覆盖保护：${relPath} 的 updated_at 晚于本次 scan 开始时间，可能包含手工编辑。`,
+        '如确认要覆盖，请重新运行 scan 并添加 --force-rescan。',
+      ].join('\n')
+    }
+  }
+
+  return { blocked: false }
+}
+
+function isInsideWorktreeStorage(filePath, cwd) {
   const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd || process.cwd(), filePath)
   return isPathInside(absPath, resolveWorktreeDir(cwd || process.cwd()))
 }
@@ -579,16 +579,16 @@ export function shouldBlockWrite(filePath, cwd) {
   const projectRoot = findProjectRoot(callerCwd)
   const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(callerCwd, filePath)
 
-  // 1. 阶段门禁（使用 fallback 读取）
-  const stage = readCurrentStage(projectRoot) || '(none)'
-
-  const scanGuardResult = shouldBlockScanDocOverwrite(absPath, projectRoot)
-  if (scanGuardResult.blocked) return scanGuardResult
-
-  // 2. 文件门禁：文档类/配置类始终放行，但 worktree 存储区内的源码必须继续走登记校验。
-  if (!isInsideWorktreeStorage(absPath, projectRoot) && matchFileWhitelist(absPath)) return { blocked: false }
-
-  if (!['execute', 'quick'].includes(stage)) {
+  // 1. 阶段门禁（使用 fallback 读取）
+  const stage = readCurrentStage(projectRoot) || '(none)'
+
+  const scanGuardResult = shouldBlockScanDocOverwrite(absPath, projectRoot)
+  if (scanGuardResult.blocked) return scanGuardResult
+
+  // 2. 文件门禁：文档类/配置类始终放行，但 worktree 存储区内的源码必须继续走登记校验。
+  if (!isInsideWorktreeStorage(absPath, projectRoot) && matchFileWhitelist(absPath)) return { blocked: false }
+
+  if (!['execute', 'quick'].includes(stage)) {
     return {
       blocked: true,
       reason: buildStageHint(stage)
@@ -627,9 +627,9 @@ export function shouldBlockWrite(filePath, cwd) {
     return {
       blocked: true,
       reason: [
-        '当前处于 --no-worktree 降级模式，不允许源码写入。',
-        '如需修改源码，请移除 --no-worktree 标志重新执行。',
-        '紧急情况可设置 SILLYSPEC_DISABLE_HOOKS=1 绕过限制。',
+        '当前变更处于无 worktree 隔离模式（changes.no_worktree=1），不允许源码写入。',
+        '如需修改源码，请在 worktree 隔离环境中工作。',
+        '若误入此模式，检查 sillyspec.db 该变更的 no_worktree 字段；紧急情况可设置 SILLYSPEC_DISABLE_HOOKS=1 绕过限制。',
       ].join('\n')
     }
   }

package/src/index.js

@@ -9,7 +9,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join, resolve } from 'path';
 import { cmdInit, getVersion } from './init.js';
-import { ProgressManager } from './progress.js';
+import { ProgressManager, resolvePlatformSpecDir } from './progress.js';
 
 // ── CLI 入口 ──
 
@@ -18,86 +18,91 @@ function printUsage() {
 SillySpec CLI — 规范驱动开发工具包
 
 用法:
-  sillyspec init               初始化（零交互，自动检测工具）
-    [--tool <name>]            只安装指定工具
-    [--interactive]            交互式引导
-    [--dir <path>]             指定目录
-    [--spec-dir <path>]        指定规范目录（默认 <项目>/.sillyspec）
-
-  sillyspec setup [--list]     安装推荐 MCP 工具
-    [--list]                   查看已安装状态
-
-  sillyspec run <stage>        执行阶段步骤（核心命令）
-    --done --output "..."      完成当前步骤
-    --skip                     跳过可选步骤
-    --status                   查看阶段进度
-    --reset                    重置阶段（从头开始）
-    --reopen                   重新打开已完成阶段进入修订模式
-    --from-step <index|name>   配合 --reopen：从指定步骤开始修订
-    --change <name>            设置当前变更名
-    --spec-dir <path>          指定规范目录（默认 <项目>/.sillyspec）
-    --runtime-root <path>       平台模式：运行时产物根路径
-    --workspace-id <id>         平台模式：workspace ID
-    --scan-run-id <id>          平台模式：scan run ID
-    auto                       连续推进 brainstorm→plan→execute→verify
-
-  可选阶段:
-    scan, brainstorm, plan, execute, verify, archive
-    quick, explore, status, doctor
-
-  Revision mode:
-    已完成阶段不能直接重跑。使用 --reopen --from-step 进入受控修订。
-    重开会使下游阶段自动标记为 stale，但不修改已有产物文件。
+  sillyspec init [--tool <name>] [--interactive] [--dir <path>] [--spec-dir <path>]
+                                      初始化（零交互，自动检测工具并安装命令模板）
+  sillyspec setup [--list]            安装推荐 MCP 工具（--list 查看已安装状态）
+
+  sillyspec run <stage> [options]     执行阶段步骤（核心命令）
+  sillyspec <stage> [options]         顶层别名，等同 run <stage>
+    stage: scan | brainstorm | plan | execute | verify | archive |
+           quick | explore | status | doctor | auto
+
+  run 通用参数（所有 stage 适用）:
+    --done --output "摘要" [--input "用户原话"]   完成当前步骤
+    --status                           查看阶段进度
+    --skip                             跳过可选步骤
+    --reset                            重置阶段（从头开始）
+    --reopen --from-step <序号|名称>   重新打开已完成阶段进入修订
+    --wait --reason "..." --options "A,B"          暂停等用户决策
+    --continue --answer "..."                      恢复等待中的步骤
+    --done --answer "..." --output "..."           一步完成 wait+done
+    --change <名>                      指定变更名（多活跃变更必填，单变更可省）
+    --spec-dir <path>                  指定规范目录（默认 <项目>/.sillyspec）
+    --non-interactive                  CI/脚本：禁用交互式 prompt
+    --interactive                      强制交互（即便 stdin 非 TTY）
+    --skip-approval                    跳过审批/校验门控（需明确意图）
+    --json                             输出 JSON（程序化读取）
+
+  阶段特有参数:
+    quick:   --linked-changes none|a,b   显式关联变更（取代 --change，推荐）
+             --files a.js,b.js           显式声明允许修改的文件
+             --allow-new                 允许新增文件（默认禁止）
+             --force-baseline            允许覆盖 baseline 受保护文件
+             --confirm                   完成时确认接受变更审计
+    scan:    --deep                      强制 deep 扫描 profile
+             --force-rescan              覆盖已有 scan 文档保护
+    archive: --confirm                   归档确认（必须）
+    auto:    --mode <模式>               显式指定流程模式
+    平台:    --runtime-root <path> / --workspace-id <id> / --scan-run-id <id>
 
   sillyspec progress <cmd>     进度记录（轻量，不强制顺序）
-    init                       初始化项目数据库
-    show                       查看当前进度
-    set-stage <stage>          设置当前阶段
-    add-step <stage> <name>    添加步骤
-    update-step <s> <n> --status <st> [--output <t>]
-    complete-stage <stage>     标记阶段完成
-    check                      状态一致性检查（只报告，不修复）
-    repair [--apply]           修复状态元数据（默认 dry-run，--apply 才修改）
-    validate                   校验并修复
-    reset [--stage X]          重置进度
-
-  sillyspec docs migrate       迁移旧文档到统一结构
-
-  sillyspec knowledge <cmd>    知识库管理（agent-safe，输出 JSON）
-    search --query "<text>" --limit N  搜索知识库
-    inspect --id "<id>"            读取知识条目详情
-    validate                        校验知识库健康度
-    refresh                         从 scan 文档刷新自动知识（仅写 generated/）
-    propose --title "<title>" --category <name>  提议新知识（写入 proposed/）
-
-  sillyspec platform <cmd>      SillyHub 平台同步
-    connect <url> [--token <t>]  连接平台
-    disconnect                    断开连接
-    sync [--change <name>]        同步变更状态
-    sync-docs [--change <name>]   同步四件套文档
-    status                        查看同步状态
-    approve <change-name>         审批变更
-    reject <change-name> [--reason <r>]  拒绝变更
-
-  sillyspec dashboard          启动 Dashboard Web UI
-    [--port <number>]          指定端口（默认 3456）
-    [--no-open]                不自动打开浏览器
-
-选项:
-  --json                       输出 JSON（给 AI 程序化读取）
-  --dir <path>                 指定项目目录（默认当前目录）
-  --spec-dir <path>            指定规范目录（默认 <项目目录>/.sillyspec）
+    init | show | set-stage <stage> | add-step <stage> <name> |
+    update-step <stage> <name> --status <st> [--output <t>] | complete-stage <stage> |
+    check | repair [--apply] | validate | reset [--stage X] |
+    batch --total N --completed M [--failed F] [--skipped K] | batch --status
+
+  sillyspec worktree <cmd>     git worktree 隔离管理（execute 阶段相关）
+    create <change> [--base <branch>]   创建隔离 worktree
+    apply <change> [--check-only]       校验并应用变更到主工作区
+    assess <change>                     风险审计 + 自动 apply
+    list | meta <change>                列出 / 读取 meta.json
+    cleanup <change> [--force]          清理 worktree
+    doctor [--fix] [--stale-hours N]    健康检查 + 修复
+
+  sillyspec workflow check <name> [--project <p>] [--change <c>] [--json]
+  sillyspec workflow list
+  sillyspec modules <rebuild | status | migrate>
+  sillyspec change-rename <旧变更名> <新变更名>
+  sillyspec knowledge <search --query "..." --limit N
+                        | inspect --id "..."
+                        | validate | refresh
+                        | propose --title "..." --category <name>>
+  sillyspec platform <connect <url> [--token <t>]
+                      | disconnect
+                      | sync [--change <name>] | sync-docs [--change <name>]
+                      | status | pointer [--cleanup]
+                      | approve <change> | reject <change> [--reason <r>]>
+  sillyspec docs migrate
+  sillyspec dashboard [--port <N>] [--no-open]
+
+全局选项:
+  --json              输出 JSON
+  --dir <path>        指定项目目录（默认当前目录）
+  --spec-dir <path>   指定规范目录（默认 <项目目录>/.sillyspec）
+  --tool <name>       指定工具（init 用）
+  --interactive, -i   交互式引导
+  --version, -v       查看版本
 
 示例:
   sillyspec init
-  sillyspec init --spec-dir /data/specs/my-project
-  sillyspec run scan
-  sillyspec run brainstorm
-  sillyspec run quick
-  sillyspec run explore
-  sillyspec run brainstorm --done --output "需求已澄清"
-  sillyspec setup --list
-  sillyspec dashboard --port 8080 --no-open
+  sillyspec run brainstorm --change 2026-07-03-add-login
+  sillyspec run quick --linked-changes none --done --output "修复手机号校验"
+  sillyspec run verify --done --output "验证通过，测试全绿"
+  sillyspec run archive --done --confirm --output "归档完成"
+  sillyspec run plan --reopen --from-step 2          # 修订 plan，从第 2 步重做
+  sillyspec run quick --non-interactive --done --output "CI 内的快修"  # 脚本/CI
+  sillyspec progress show
+  sillyspec worktree apply 2026-07-03-add-login
 `);
 }
 
@@ -188,7 +193,7 @@ async function main() {
       await (await import('./setup.js')).cmdSetup(dir, { json, list: setupList });
       break;
     case 'progress': {
-      const pm = new ProgressManager();
+      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
       const progDir = specDir ? dir : resolveEffectiveDir(dir);
       const subCommand = filteredArgs[1];
       const stageIdx = filteredArgs.indexOf('--stage');
@@ -298,16 +303,75 @@ async function main() {
       await runCommand(filteredArgs.slice(1), effectiveDir, specDir)
       break
     }
-    // task-10: 顶层命令别名，转发 runCommand，与 case 'run': 路径行为一致
-    // help 文本(:44-46)已宣称这些 stage 可直接使用，这里补齐路由避免落 default 分支。
+    // 顶层命令别名：转发 runCommand，与 case 'run': 路径行为一致。
+    // printUsage 宣称所有 stage 都可直接使用，这里补齐全部路由避免落 default 分支。
     // 注意：filteredArgs[0] === command，直接透传 filteredArgs 即可让 runCommand
-    // 从 args[0] 取到 stage 名（run.js:1036）。与 case 'run': 的 filteredArgs.slice(1)
-    // 区别只在于 slice(1) 去掉的是 'run' 字面量，这里 command 本身就是 stage 名不能丢。
-    case 'doctor':
+    // 从 args[0] 取到 stage 名。与 case 'run': 的 filteredArgs.slice(1) 区别只在于
+    // slice(1) 去掉的是 'run' 字面量，这里 command 本身就是 stage 名不能丢。
+    case 'doctor': {
+      const doctorEffectiveDir = specDir ? dir : resolveEffectiveDir(dir);
+      // 执行流：--cleanup-remnant / --dump-db（结构化诊断之外的修复/取证动作）
+      const cleanupRemnant = filteredArgs.includes('--cleanup-remnant');
+      const dumpDbFlag = filteredArgs.includes('--dump-db');
+      const doctorConfirm = filteredArgs.includes('--confirm');
+      const pathIdx = filteredArgs.indexOf('--path');
+      const dbPath = pathIdx >= 0 && filteredArgs[pathIdx + 1] ? filteredArgs[pathIdx + 1] : null;
+
+      if (cleanupRemnant) {
+        const { cleanupRemnantDbs } = await import('./doctor-diagnostics.js');
+        const r = await cleanupRemnantDbs({ cwd: doctorEffectiveDir, confirm: doctorConfirm });
+        if (json) {
+          console.log(JSON.stringify(r, null, 2));
+        } else {
+          const list = doctorConfirm ? r.deleted : r.would_delete.map((x) => x.path);
+          console.log(`🗑️  空占位 db ${doctorConfirm ? '已删除' : '待清理（dry-run）'}：${r.count} 个`);
+          for (const p of list) console.log(`   ${doctorConfirm ? '✅' : '-'} ${p}`);
+          for (const e of r.errors) console.log(`   ❌ ${e.path}: ${e.error}`);
+          if (!doctorConfirm && r.count > 0) console.log(`\n加 --confirm 执行删除（仅删 0 字节占位，不动有内容的 db）。`);
+        }
+        process.exitCode = r.errors.length > 0 ? 1 : 0;
+        break;
+      }
+      if (dumpDbFlag) {
+        if (!dbPath) { console.error('❌ --dump-db 需要 --path <db 路径>'); process.exitCode = 2; break; }
+        const { dumpDb } = await import('./doctor-diagnostics.js');
+        const r = await dumpDb({ dbPath, cwd: doctorEffectiveDir });
+        if (json) {
+          console.log(JSON.stringify(r, null, 2));
+        } else if (r.ok === false && r.error) {
+          console.error(`❌ ${r.error}`);
+        } else {
+          console.log(`📦 dump ${dbPath} (${r.meta?.size}B)：${r.changes?.length || 0} changes, ${r.stages?.length || 0} stages`);
+          if (r.written_to) console.log(`   写入：${r.written_to}`);
+        }
+        process.exitCode = r.ok === false ? 1 : 0;
+        break;
+      }
+      // --json：走结构化诊断（doctor-diagnostics.js），输出 JSON + 落盘 doctor-diagnosis.json
+      if (json) {
+        const { runDoctorDiagnostics, formatDoctorJson, writeDoctorDiagnosis } = await import('./doctor-diagnostics.js');
+        const result = await runDoctorDiagnostics({ cwd: doctorEffectiveDir });
+        const output = formatDoctorJson(result, { source_root: dir });
+        const written = writeDoctorDiagnosis(output, result.authoritySpecDir);
+        if (written) console.error(`📁 诊断结果已写入: ${written}`);
+        console.log(JSON.stringify(output, null, 2));
+        process.exitCode = output.overall_status === 'pass' ? 0 : 1;
+        break;
+      }
+      // 否则：保持原有 prompt 驱动的 bash 自检流程
+      const { runCommand } = await import('./run.js');
+      await runCommand([command, ...filteredArgs.slice(1)], doctorEffectiveDir, specDir);
+      break;
+    }
     case 'scan':
     case 'status':
     case 'quick':
-    case 'explore': {
+    case 'explore':
+    case 'brainstorm':
+    case 'plan':
+    case 'execute':
+    case 'verify':
+    case 'archive': {
       const { runCommand } = await import('./run.js')
       const stageArgs = [command, ...filteredArgs.slice(1)]
       const effectiveDir = specDir ? dir : resolveEffectiveDir(dir)
@@ -347,7 +411,7 @@ async function main() {
       const wtSubCmd = filteredArgs[1];
       const wtName = filteredArgs.slice(2).find(a => !a.startsWith('-'));
       const wm = new WorktreeManager({ cwd: dir });
-      const pm = new ProgressManager({ specDir });
+      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
 
       // isolation 写入 DB 的辅助函数
       async function _writeIsolationToDB(cwd, changeName, info) {
@@ -749,7 +813,7 @@ SillySpec platform — SillyHub 平台同步
         console.error('❌ 用法: sillyspec change-rename <旧变更名> <新变更名>');
         process.exit(1);
       }
-      const pm = new ProgressManager({ specDir });
+      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
       await pm.renameChange(dir, oldName, newName);
       break;
     }
@@ -919,4 +983,12 @@ SillySpec modules — 模块文档管理
   }
 }
 
-main();
+main().catch((err) => {
+  // 平台指针失效：fail-closed，打印修复引导而非静默回退/stack trace
+  if (err?.name === 'PointerUnreachableError') {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+  console.error(err);
+  process.exit(1);
+});

package/src/progress.js

@@ -34,6 +34,74 @@ export function resolveSpecDir(startDir) {
   }
   return join(resolve(startDir), SPEC_DIR_NAME);
 }
+
+/**
+ * 平台指针不可达错误。pointer 存在但失效时抛出，阻止静默回退到本地孤儿 db。
+ * 逃生口：显式 --spec-dir 绕过 pointer 校验。
+ */
+export class PointerUnreachableError extends Error {
+  constructor({ pointerPath, specRoot, reason, hint }) {
+    super(
+      `平台指针不可用：${reason}\n` +
+      `  pointer: ${pointerPath}\n` +
+      `  specRoot: ${specRoot || '(缺失)'}\n` +
+      `修复：${hint}`
+    );
+    this.name = 'PointerUnreachableError';
+    this.pointerPath = pointerPath;
+    this.specRoot = specRoot || null;
+  }
+}
+
+/**
+ * 平台感知的 specDir 解析（fail-closed，所有 CLI 子命令统一入口）。
+ *
+ * 优先级：显式 --spec-dir > pointer.specRoot（可达）> resolveSpecDir(cwd)。
+ *
+ * fail-closed 语义（修复"状态穿越"定时炸弹）：
+ *   一旦项目进入过平台模式（pointer 文件存在），pointer 失效（specRoot 不可达 /
+ *   损坏 / 缺字段）不再静默回退到本地——否则会读到切平台前的过期本地 db。
+ *   此时抛 PointerUnreachableError，由 CLI 顶层捕获并打印修复引导。
+ *
+ *   无 pointer = 纯本地项目（从未平台 scan），正常走本地解析，不受影响。
+ */
+export function resolvePlatformSpecDir(cwd, explicitSpecDir = null) {
+  if (explicitSpecDir) return resolve(explicitSpecDir);
+  const pointerPath = join(resolve(cwd), '.sillyspec-platform.json');
+  if (!existsSync(pointerPath)) {
+    return resolveSpecDir(cwd);
+  }
+  // pointer 存在 = 进过平台模式，严格校验，不静默回退
+  let ptr;
+  try {
+    ptr = JSON.parse(readFileSync(pointerPath, 'utf8'));
+  } catch (e) {
+    throw new PointerUnreachableError({
+      pointerPath,
+      specRoot: null,
+      reason: `pointer 文件损坏（${e.message}）`,
+      hint: `sillyspec platform pointer --cleanup 删除后重跑平台 scan`,
+    });
+  }
+  if (!ptr.specRoot) {
+    throw new PointerUnreachableError({
+      pointerPath,
+      specRoot: null,
+      reason: 'pointer 缺少 specRoot 字段',
+      hint: `sillyspec platform pointer --cleanup 删除后重跑平台 scan`,
+    });
+  }
+  if (!existsSync(ptr.specRoot)) {
+    throw new PointerUnreachableError({
+      pointerPath,
+      specRoot: ptr.specRoot,
+      reason: 'pointer.specRoot 路径不存在（daemon 未起？已迁移？）',
+      hint: `启动 SillyHub daemon；或 sillyspec doctor --json 诊断；或显式 --spec-dir <本地路径> 临时走本地`,
+    });
+  }
+  return ptr.specRoot;
+}
+
 const CHANGES_SUBDIR = 'changes';
 const GLOBAL_FILE = 'global.json';
 const CURRENT_VERSION = 3;