sillyspec 3.25.8 → 3.25.11

package/src/index.js

@@ -10,14 +10,14 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync,
 import { writeAtomicSync } from './fs-atomic.js';
 import { join, resolve } from 'path';
 import { execSync } from 'child_process';
-import { cmdInit, getVersion } from './init.js';
+import { git } from './git-helper.js';
+import { getVersion } from './version.js';
 import { ProgressManager, resolvePlatformSpecDir } from './progress.js';
-import { detectLocalYaml } from './local-detect.js';
 
 // ── CLI 入口 ──
 
 // did-you-mean 从 ./run/shared.js 复用（命令级 + flag 级 typo 建议）。
-import { didYouMean, assertSafeChangeName } from './run/shared.js'
+import { didYouMean, assertSafeChangeName, resolveSpecDir, detectWorktreeSpecDrift } from './run/shared.js'
 function printUsage() {
   console.log(`
 SillySpec CLI — 规范驱动开发工具包
@@ -76,12 +76,14 @@ SillySpec CLI — 规范驱动开发工具包
 
   sillyspec local detect [--dir <path>]   生成本地配置 local.yaml（纯 fs 嗅探，零 token、不跑 scan）
   sillyspec runtime list [--json]         枚举 .sillyspec/.runtime/ 运行时产物（只读，看手上有哪些证据/状态文件）
+  sillyspec dispatch <probe | hint>       SillyHub 派发能力探测 + 策略生成（agent 调用桥，仅渲染不执行 tool）
 
   sillyspec workflow check <name> [--project <p>] [--change <c>] [--json] [--save]
                                       全局 workflow 校验（--save 归档到 .sillyspec/.runtime/workflow-runs/）
   sillyspec workflow list
   sillyspec gate <stage> --change <name> [--json]      机器门控：阶段能否标记完成（只读）
   sillyspec derive <facet> --change <name> [--json]    单项事实核验（facet: execute-evidence|verify-test|task-reviews|artifacts）
+  sillyspec backfill-reviews --change <name> [--json]  为手动补的 task 生成 review.json 草稿（cannot_verify，解 archive 客观完成度阻断）
 
   sillyspec doctor [子命令]            进度库健康检查 + 修复（顶层命令，非 worktree doctor）
     （无子命令）                       跑诊断，列出问题
@@ -227,7 +229,7 @@ async function main() {
 
   switch (command) {
     case 'init':
-      await cmdInit(dir, { tool, interactive, specDir });
+      await (await import('./init.js')).cmdInit(dir, { tool, interactive, specDir });
       break;
     case 'setup':
       const setupList = filteredArgs.includes('--list') || filteredArgs.includes('-l');
@@ -252,7 +254,7 @@ async function main() {
           pm.show(progDir, progChangeName);
           break;
         case 'check': {
-          const result = await pm.checkConsistency(progDir, progChangeName);
+          const result = pm.checkConsistency(progDir, progChangeName);
           // checkConsistency 只返回 {ok, issues, warnings}，不打印——必须在此输出，
           // 否则 agent 跑只读健康检查得到一片寂静，无法分辨「正常」还是「已损坏」。
           if (!result || result.ok) {
@@ -266,11 +268,11 @@ async function main() {
         }
         case 'repair': {
           const repairApply = filteredArgs.includes('--apply');
-          await pm.repairConsistency(progDir, { apply: repairApply, changeName: progChangeName });
+          pm.repairConsistency(progDir, { apply: repairApply, changeName: progChangeName });
           break;
         }
         case 'validate':
-          await pm.validate(dir, progChangeName);
+          pm.validate(dir, progChangeName);
           break;
         case 'reset':
           pm.reset(dir, stage, progChangeName);
@@ -298,18 +300,18 @@ async function main() {
             if (args[ai] === '--output' && args[ai + 1]) { updOutput = args[ai + 1]; ai++; }
           }
           const updForce = args.includes('--force');
-          await pm.updateStep(dir, updStepStage, updStepName, { status: updStatus, output: updOutput, force: updForce }, progChangeName);
+          pm.updateStep(dir, updStepStage, updStepName, { status: updStatus, output: updOutput, force: updForce }, progChangeName);
           break;
         }
         case 'complete-stage': {
           const compStageName = filteredArgs[2];
           if (!compStageName) { console.log('❌ 用法: sillyspec progress complete-stage <stage> [--force]'); break; }
-          await pm.completeStage(dir, compStageName, progChangeName, { force: args.includes('--force') });
+          pm.completeStage(dir, compStageName, progChangeName, { force: args.includes('--force') });
           break;
         }
         case 'batch': {
           if (filteredArgs.includes('--status')) {
-            const bp = await pm.readBatchProgress(dir, progChangeName);
+            const bp = pm.readBatchProgress(dir, progChangeName);
             if (!bp) { console.log('📭 无批量进度数据'); break; }
             const line = pm._renderBatchProgress(bp);
             console.log(line || '📭 无批量进度数据');
@@ -328,7 +330,7 @@ async function main() {
               console.log('     sillyspec progress batch --status');
               break;
             }
-            await pm.updateBatchProgress(dir, batchData, progChangeName);
+            pm.updateBatchProgress(dir, batchData, progChangeName);
             console.log('✅ 批量进度已更新');
           }
           break;
@@ -355,6 +357,15 @@ async function main() {
       // resolveSpecDir(cwd)，向后兼容。
       const gateOpts = { cwd: dir };
       if (specDir) gateOpts.specBase = specDir;
+      // drift 锚定（坑 execute-runs-isolation，对齐 command.js execute drift 守卫 + machine-interface
+      // runGate 已扩展的 specDriftAnchor 入参）：gate 是顶层命令不走 runCommand/drift 守卫，worktree cwd
+      // 下 execute 段 marker 读取会落副本 .runtime。仅在未显式 --spec-dir 时算（对齐守卫条件 !specDir），
+      // 命中则 specDriftAnchor 锚主仓——runGate execute 段的 resolveRuntimeRoot 读主仓
+      // current-execute-run-id marker，不读 worktree 副本（副本随 cleanup 整目录删消失）。
+      if (!specDir) {
+        const wt = detectWorktreeSpecDrift(resolveSpecDir(dir));
+        if (wt) gateOpts.specDriftAnchor = wt.mainSpecBase;
+      }
       const { envelope, exitCode } = await withJsonOutput(json, () => runGate(gateStage, gateChange, gateOpts));
       if (json) {
         process.stdout.write(JSON.stringify(envelope));
@@ -389,6 +400,13 @@ async function main() {
       // 下需透传；不传 --spec-dir 时走默认 resolveSpecDir(cwd)，向后兼容。
       const deriveOpts = { cwd: dir };
       if (specDir) deriveOpts.specBase = specDir;
+      // drift 锚定（同 gate case，对齐 command.js drift 守卫 + machine-interface runDerive 的 specDriftAnchor
+      // 入参）：derive 顶层命令不走 drift 守卫，worktree cwd 下 task-reviews facet 的 execute-run-id marker
+      // 读取会落副本。未显式 --spec-dir 时算 anchor，runDerive task-reviews 的 resolveRuntimeRoot 读主仓 marker。
+      if (!specDir) {
+        const wt = detectWorktreeSpecDrift(resolveSpecDir(dir));
+        if (wt) deriveOpts.specDriftAnchor = wt.mainSpecBase;
+      }
       const { envelope, exitCode } = await withJsonOutput(json, () => runDerive(facet, deriveChange, deriveOpts));
       if (json) {
         process.stdout.write(JSON.stringify(envelope));
@@ -402,6 +420,44 @@ async function main() {
       process.exitCode = exitCode;
       break;
     }
+    case 'backfill-reviews': {
+      // 手动补 task（reopen execute / 直接实现）缺 review.json 的官方入口（坑 verify-archive-flow-pitfalls 坑2）。
+      // 复用 generateTaskReviewDrafts（execute --done 同源兜底，幂等、fail-open）：据 git diff base..head + working-tree
+      // 按 task allowed_paths 归属生成 cannot_verify 草稿，agent 复核后升级 pass/fail。execute 完成后手动补的 task
+      // 无子代理 review 落盘 → archive step1 客观完成度（真相源=review.json verdict）判缺 → 阻断归档；本命令补齐
+      // 缺失草稿，独立可随时跑（不必再 execute --done）。缺数据（无 tasks/ 目录 / 改动未 commit / 无 worktree meta）
+      // 时 generateTaskReviewDrafts 提前返回 reason，如实打印不报错。
+      const brChangeIdx = args.indexOf('--change');
+      const brChange = brChangeIdx >= 0 && args[brChangeIdx + 1] ? args[brChangeIdx + 1] : null;
+      if (!brChange) {
+        console.error('用法: sillyspec backfill-reviews --change <name> [--json] [--spec-dir <path>]\n  为手动补的 task 生成 review.json 草稿（cannot_verify），解 archive 客观完成度阻断');
+        process.exit(2);
+      }
+      const { generateTaskReviewDrafts } = await import('./task-review.js');
+      // --spec-dir 透传 platformOpts.specRoot（与 gate/derive 对称）；不传走默认 join(cwd,'.sillyspec')。
+      const brPlatformOpts = {};
+      if (specDir) brPlatformOpts.specRoot = specDir;
+      const result = await generateTaskReviewDrafts({ changeName: brChange, cwd: dir, platformOpts: brPlatformOpts });
+      if (json) {
+        process.stdout.write(JSON.stringify({ ok: true, command: 'backfill-reviews', change: brChange, ...result }));
+      } else {
+        if (result.generated > 0) {
+          console.log('📄 已补写 ' + result.generated + ' 个 per-task review.json 草稿（cannot_verify，需 agent 复核后升级 pass/fail） [' + brChange + ']');
+        } else {
+          console.log('ℹ️ 无草稿可补 [' + brChange + ']' + (result.reason ? '：' + result.reason : ''));
+        }
+        if (result.skipped > 0) {
+          console.log('   跳过 ' + result.skipped + ' 个 task（review.json 已存在 / 空 diff 无从归属）');
+        }
+        if (result.unattributed && result.unattributed.length > 0) {
+          console.warn('   ⚠️ ' + result.unattributed.length + ' 个变更文件未归属任何 task（顺带修复/非源码），草稿未覆盖：' + result.unattributed.join(', '));
+        }
+        if (result.executeRunId) {
+          console.log('   execute run id: ' + result.executeRunId);
+        }
+      }
+      break;
+    }
     case 'docs': {
       const docsSubCmd = filteredArgs[1];
       if (docsSubCmd === 'migrate') {
@@ -474,7 +530,7 @@ async function main() {
         const specBase = resolvePlatformSpecDir(doctorEffectiveDir, specDir) || join(doctorEffectiveDir, '.sillyspec');
         let r;
         try {
-          r = await pm.alignExecuteToPlan(doctorEffectiveDir, alignChange, specBase, { confirm: doctorConfirm });
+          r = pm.alignExecuteToPlan(doctorEffectiveDir, alignChange, specBase, { confirm: doctorConfirm });
         } catch (e) {
           console.error(`❌ 对齐失败：${e.message}`);
           process.exitCode = 1;
@@ -595,9 +651,9 @@ async function main() {
       const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
 
       // isolation 写入 DB 的辅助函数
-      async function _writeIsolationToDB(cwd, changeName, info) {
+      function _writeIsolationToDB(cwd, changeName, info) {
         if (info.blocked) {
-          await pm.updateChangeIsolation(cwd, changeName, {
+          pm.updateChangeIsolation(cwd, changeName, {
             status: 'blocked',
             mode: null,
             reason: info.reason,
@@ -605,7 +661,7 @@ async function main() {
         } else {
           const mode = info.mode || 'worktree';
           const statusMap = { 'worktree': 'verified', 'native-worktree': 'verified', 'in-place-fallback': 'degraded' };
-          await pm.updateChangeIsolation(cwd, changeName, {
+          pm.updateChangeIsolation(cwd, changeName, {
             status: statusMap[mode] || 'verified',
             mode,
           });
@@ -620,10 +676,11 @@ SillySpec worktree — git worktree 隔离管理
   sillyspec worktree create <change-name> [--base <branch>]   创建隔离 worktree
   sillyspec worktree apply <change-name> [--check-only]        校验并应用变更到主工作区
   sillyspec worktree assess <change-name>                     风险审计 + 自动 apply
+  sillyspec worktree diff <change-name> [--base <commit>]      查看 worktree 相对 base 的变更
   sillyspec worktree list                                      列出所有活跃 worktree
   sillyspec worktree meta <change-name>                        读取 worktree meta.json
   sillyspec worktree cleanup <change-name> [--force]           强制清理 worktree
-  sillyspec worktree doctor [--fix] [--stale-hours N]          健康检查 + 修复
+  sillyspec worktree doctor [--fix] [--stale-hours N] [--change <name>]   健康检查 + 修复（--change 仅扫指定 change）
 
 选项:
   --base <branch>       create: 指定基础分支（默认当前 HEAD）
@@ -652,11 +709,11 @@ SillySpec worktree — git worktree 隔离管理
             if (info.mode) {
               console.log(`   模式: ${info.mode}`);
             }
-            // 写入 isolation 信息到 gate-status.json
+            // 写入 isolation 信息到 sillyspec.db（_writeIsolationToDB）
             await _writeIsolationToDB(dir, wtName, info);
           } catch (e) {
             console.error(`❌ ${e.message}`);
-            // 写入 blocked 状态到 gate-status.json
+            // 写入 blocked 状态到 sillyspec.db（_writeIsolationToDB）
             await _writeIsolationToDB(dir, wtName, { blocked: true, reason: e.message });
             process.exit(1);
           }
@@ -697,10 +754,10 @@ SillySpec worktree — git worktree 隔离管理
             for (const f of result.changedFiles) {
               console.log(`   ${f}`);
             }
-            // filterDeliverableFiles 一刀切排除 .sillyspec/ + meta.json：
-            // 模块文档/变更文档等不会 auto-apply 到主工作区。须告知 agent，
-            // 否则它期望这些文件落地却找不到（memory: worktree-apply-excludes-module-docs）。
-            console.log(`   ℹ️  注：.sillyspec/ 下的文件（模块文档/变更文档等）按规则不自动 apply，如需请手动从 worktree 分支或 dangling commit 取（git show sillyspec/${wtName}:<path>）。`);
+            // filterDeliverableFiles 精细化排除（保留 .sillyspec/docs/，排 changes/+.runtime/+quicklog/ + meta.json）：
+            // 模块文档（.sillyspec/docs/）= 交付物，会 auto-apply 到主工作区；变更文档/运行时/quicklog 不 apply。
+            // 须告知 agent 哪些未落地，否则它期望这些文件落地却找不到（memory: worktree-apply-excludes-module-docs）。
+            console.log(`   ℹ️  注：.sillyspec/changes、.sillyspec/.runtime、.sillyspec/quicklog 下的文件按规则不自动 apply（模块文档 .sillyspec/docs/ 会自动 apply），如需请手动从 worktree 分支或 dangling commit 取（git show sillyspec/${wtName}:<path>）。`);
           }
           if (result.warnings && result.warnings.length > 0) {
             for (const w of result.warnings) {
@@ -748,7 +805,7 @@ SillySpec worktree — git worktree 隔离管理
             } else {
               console.log(`✅ 已自动应用 ${applyResult.changedFiles.length} 个文件变更：`);
               for (const f of applyResult.changedFiles) console.log(`   ${f}`);
-              console.log(`   ℹ️  注：.sillyspec/ 下的文件按规则不自动 apply，如需请手动从分支取（git show sillyspec/${wtName}:<path>）。`);
+              console.log(`   ℹ️  注：.sillyspec/changes、.sillyspec/.runtime、.sillyspec/quicklog 下的文件按规则不自动 apply（模块文档 .sillyspec/docs/ 会自动 apply），如需请手动从分支取（git show sillyspec/${wtName}:<path>）。`);
             }
           } else {
             console.log('Action: blocked');
@@ -779,6 +836,42 @@ SillySpec worktree — git worktree 隔离管理
           console.log(JSON.stringify(meta, null, 2));
           break;
         }
+        case 'diff': {
+          if (!wtName) {
+            console.error('❌ 用法: sillyspec worktree diff <change-name> [--base <commit>]');
+            process.exit(1);
+          }
+          const meta = wm.getMeta(wtName);
+          if (!meta) {
+            console.error(`❌ 未找到 worktree meta: ${wtName}（可能未创建或已被清理）`);
+            process.exit(1);
+          }
+          if (!meta.worktreePath || !existsSync(meta.worktreePath)) {
+            console.error(`❌ worktree 目录不存在: ${meta.worktreePath || '(未设置)'}（可能已被清理，可跑 sillyspec worktree doctor）`);
+            process.exit(1);
+          }
+          // base 优先级：显式 --base > meta.baseHash（create 时锚的主仓 HEAD）> 当前 HEAD。
+          // diff 比较 worktree 工作区（含未提交）vs base，与 _changesAlreadyOnMain 同口径。
+          const baseIdx = filteredArgs.indexOf('--base');
+          const explicitBase = baseIdx >= 0 ? filteredArgs[baseIdx + 1] : null;
+          const base = explicitBase || meta.baseHash || 'HEAD';
+          let out = '';
+          try {
+            // base 作为独立 argv 元素传入，不经 shell 拆词/注入；worktreePath 经 cwd，不插值。
+            // trim:false 保留 git diff 原始输出（含尾换行）供 stdout.write；空检查靠临时 .trim()。
+            // timeout 30s：diff 属潜在长操作（对齐 design R3 与 verify-postcheck 口径）。
+            out = git(meta.worktreePath, ['--no-pager', 'diff', '--no-renames', base], { trim: false, timeout: 30000 });
+          } catch (e) {
+            console.error(`❌ git diff 失败（base=${String(base).slice(0, 8)}）: ${e.message}`);
+            process.exit(1);
+          }
+          if (!out.trim()) {
+            console.log(`（无变更：worktree 工作区与 base ${String(base).slice(0, 8)} 一致）`);
+          } else {
+            process.stdout.write(out);
+          }
+          break;
+        }
         case 'list': {
           const items = wm.list();
           if (items.length === 0) {
@@ -829,7 +922,9 @@ SillySpec worktree — git worktree 隔离管理
           const fixFlag = args.includes('--fix');
           const staleIdx = args.indexOf('--stale-hours');
           const staleHours = staleIdx !== -1 && args[staleIdx + 1] ? parseInt(args[staleIdx + 1], 10) : 24;
-          const diag = wm.doctor({ fix: fixFlag, staleHours });
+          const changeIdx = args.indexOf('--change');
+          const changeName = changeIdx !== -1 && args[changeIdx + 1] ? args[changeIdx + 1] : null;
+          const diag = wm.doctor({ fix: fixFlag, staleHours, changeName });
           if (diag.issues.length === 0) {
             console.log('✅ worktree 健康检查通过，无异常');
           } else {
@@ -860,6 +955,83 @@ SillySpec worktree — git worktree 隔离管理
       }
       break;
     }
+    case 'dispatch': {
+      // SillyHub 派发抽象层的 agent 调用桥（design.md §Phase2 / D-007@v1）：
+      // 仅做能力探测（probe）与派发策略生成（hint），**不执行任何 tool 调用**——
+      // 实际 tool 调用（本机 Agent tool / SillyHub MCP tool）由 agent 据指令执行。
+      // 仿 worktree 子命令的参数解析（filteredArgs[1] 取子命令）与错误处理模式。
+      const dispatchSubCmd = filteredArgs[1];
+      const dispatchSubs = ['probe', 'hint'];
+
+      if (!dispatchSubCmd || dispatchSubCmd === 'help' || dispatchSubCmd === '--help' || dispatchSubCmd === '-h') {
+        console.log(`
+SillySpec dispatch — SillyHub 派发能力探测与策略生成（agent 调用桥，仅渲染与探测）
+
+用法:
+  sillyspec dispatch probe [--json]                   能力探测，输出 ProbeResult
+  sillyspec dispatch hint --contract <json> [--json]  派发策略，输出 {instruction, backend}
+
+子命令:
+  probe   探测 SillyHub MCP 是否可用（无配置返回 available=false，正常降级不报错）
+  hint    据 contract + probe 结果生成派发指令文本（agent 拿指令后执行实际 tool 调用）
+
+选项:
+  --contract <json>   hint 必填：DispatchContract（brief/worktreePath/branch/allowedPaths/readOnly/...）
+  --json              程序化输出（probe → ProbeResult；hint → {backend, instruction}）
+`);
+        break;
+      }
+
+      if (dispatchSubCmd === 'probe') {
+        const { probeSillyHub } = await import('./dispatch/probe.js');
+        const result = await probeSillyHub();
+        // result = { available, reason? }；无配置时 {available:false,reason:'no-config'} 不报错（正常降级）
+        if (json) {
+          process.stdout.write(JSON.stringify(result));
+        } else if (result.available) {
+          console.log('✅ SillyHub 可用');
+        } else {
+          console.log(`⚠️ SillyHub 不可用：${result.reason || 'unknown'}`);
+        }
+        break;
+      }
+
+      if (dispatchSubCmd === 'hint') {
+        // 解析 --contract <json>（仿 worktree 用 args.indexOf 取 flag 后一个值）
+        const contractIdx = args.indexOf('--contract');
+        const contractRaw = contractIdx >= 0 && args[contractIdx + 1] ? args[contractIdx + 1] : null;
+        if (!contractRaw) {
+          console.error('用法: sillyspec dispatch hint --contract <json> [--json]\n  生成派发指令（DispatchContract：brief/worktreePath/branch/allowedPaths/readOnly/...）');
+          process.exit(2);
+        }
+        let contract;
+        try {
+          contract = JSON.parse(contractRaw);
+        } catch (e) {
+          console.error(`❌ --contract JSON 解析失败: ${e.message}`);
+          process.exit(2);
+        }
+        const { probeSillyHub } = await import('./dispatch/probe.js');
+        const { renderDispatchInstruction } = await import('./dispatch/strategy.js');
+        const probe = await probeSillyHub();
+        const { instruction, backend } = renderDispatchInstruction(contract, probe);
+        if (json) {
+          process.stdout.write(JSON.stringify({ backend, instruction }));
+        } else {
+          console.log(`Backend: ${backend}`);
+          console.log(instruction);
+        }
+        break;
+      }
+
+      // 未知子命令 → did-you-mean 建议 + 退出 1（仿 worktree default）
+      const sug = didYouMean(dispatchSubCmd, dispatchSubs);
+      console.error(`❌ 未知子命令: dispatch ${dispatchSubCmd}`);
+      if (sug) console.error(`   你是想输入「dispatch ${sug}」吗？`);
+      console.error(`   可用子命令：${dispatchSubs.join(' | ')}（运行 sillyspec dispatch 查看用法）`);
+      process.exit(1);
+      break;
+    }
     case 'platform': {
       const platformSub = filteredArgs[1];
       const platformArgs = filteredArgs.slice(2);
@@ -1019,7 +1191,7 @@ SillySpec platform — SillyHub 平台同步
         process.exit(2);
       }
       const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
-      await pm.renameChange(dir, oldName, newName);
+      pm.renameChange(dir, oldName, newName);
       break;
     }
     case 'workflow': {
@@ -1164,7 +1336,7 @@ SillySpec workflow — 工作流管理
 SillySpec modules — 模块文档管理
 
 用法:
-  sillyspec modules rebuild        从模块卡片 + 源码重建 _module-map.yaml
+  sillyspec modules rebuild [--force]  从模块卡片 + 源码重建 _module-map.yaml（默认 dry-run 预览，--force 才覆盖）
   sillyspec modules status         显示模块索引状态
   sillyspec modules migrate        旧格式模块文档迁移到新格式
 `);
@@ -1172,7 +1344,8 @@ SillySpec modules — 模块文档管理
       }
       if (modulesSub === 'rebuild') {
         const { rebuildModuleMap } = await import('./modules.js');
-        await rebuildModuleMap(dir);
+        const isForce = filteredArgs.includes('--force');
+        await rebuildModuleMap(dir, { force: isForce });
       } else if (modulesSub === 'status') {
         const { showModuleStatus } = await import('./modules.js');
         await showModuleStatus(dir);
@@ -1198,7 +1371,7 @@ SillySpec modules — 模块文档管理
         process.exit(2);
       }
 
-      const detected = detectLocalYaml(dir);
+      const detected = (await import('./local-detect.js')).detectLocalYaml(dir);
       const specRoot = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
       const localYamlPath = join(specRoot, 'local.yaml');
 
@@ -1241,7 +1414,7 @@ SillySpec modules — 模块文档管理
     }
     case 'runtime': {
       // D2：.runtime/ 产物索引。CLI 往 .runtime/ 写各种证据/状态文件（db、doctor-diagnosis、
-      // workflow-runs、gate-status、user-inputs…），却没有命令让 agent 一眼看到「我手上有哪些产物」。
+      // workflow-runs、user-inputs…），却没有命令让 agent 一眼看到「我手上有哪些产物」。
       // 多会话/压缩后尤其痛：上轮写的证据文件，下轮不知去哪找。纯只读枚举，不写盘。
       const runtimeSubCmd = filteredArgs[1];
       if (runtimeSubCmd && runtimeSubCmd !== 'list') {
@@ -1266,7 +1439,6 @@ SillySpec modules — 模块文档管理
         'doctor-diagnosis.json': 'doctor --json 结构化诊断快照',
         'doctor-dumps': 'doctor --dump-db 取证输出目录',
         'workflow-runs': 'workflow check --save 归档目录',
-        'gate-status.json': '门控结果缓存',
         'scan-guard.json': 'scan 覆盖保护记录',
         'quick-sessions': 'quick 会话记录目录',
         'quick-guard.json': 'quick baseline 守卫（旧位置）',
@@ -1309,10 +1481,15 @@ SillySpec modules — 模块文档管理
       break;
     }
     default: {
-      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'local', 'workflow', 'gate', 'derive', 'modules', 'change-rename', 'knowledge', 'platform', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime'];
+      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'modules', 'change-rename', 'knowledge', 'platform', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime'];
       const suggestion = didYouMean(command, topCommands);
       console.error(`❌ 未知命令: ${command}`);
-      if (suggestion) console.error(`   你是想输入「${suggestion}」吗？`);
+      if (command === '--status') {
+        // --status 是阶段内 flag（sillyspec run <stage> --status），裸用会落到 default
+        console.error('   --status 是阶段内 flag。查看进度请用：sillyspec status 或 sillyspec progress show');
+      } else if (suggestion) {
+        console.error(`   你是想输入「${suggestion}」吗？`);
+      }
       printUsage();
       process.exit(1);
     }
@@ -1325,6 +1502,10 @@ main().catch((err) => {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
-  console.error(err);
-  process.exit(1);
+  // message 提首行（Agent 可直接解析 stderr 首行判断成败），堆栈降级为附件；
+  // 用 exitCode 而非 exit(1) 让事件循环自然 drain，缓解 Windows libuv teardown
+  // 把退出码污染成 127（与 shell "command not found" 撞码）的问题。
+  console.error(`❌ SillySpec 发生错误：${err?.message || err}`);
+  if (err?.stack) console.error(err.stack);
+  process.exitCode = 1;
 });

package/src/init.js

@@ -4,6 +4,10 @@ import { fileURLToPath } from 'url';
 import { checkbox, confirm, input } from '@inquirer/prompts';
 import { ProgressManager } from './progress.js';
 import chalk from 'chalk';
+import { getVersion } from './version.js';
+// 向后兼容：getVersion 已抽到轻量 version.js（避免 index.js 为 --version 静态加载 init.js 的 inquirer 税），
+// 此处 re-export 保持 init.js 既有导出 API 不破坏（如 test/init-claude-injection.test.mjs）。
+export { getVersion };
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -12,7 +16,7 @@ const __dirname = dirname(__filename);
 // 平台模式（specRoot 指向外部）下，源码目录的 .sillyspec/.runtime/ 是旧残留，
 // 应让 specRoot 成为唯一运行时根。但若源码目录的 .sillyspec/ 本身就是该项目
 // 的 specDir（含真实资产），其 .runtime/ 里的 worktrees/、sillyspec.db、
-// global.json、gate-status.json 是真实工作状态，整删会摧毁 worktree meta、
+// global.json 是真实工作状态，整删会摧毁 worktree meta、
 // 导致 depsStatus 恒为 unknown、branch already exists 死循环。
 // 详见 docs/sillyspec/runtime-cleanup-destroys-worktree-meta.md
 //
@@ -21,7 +25,6 @@ const RUNTIME_KEEP = new Set([
   'worktrees',          // worktree 目录 + meta.json（worktree.js:17）
   'sillyspec.db',       // SQLite 进度库（权威状态源，progress.js:7）
   'global.json',        // 项目名/活跃变更缓存（progress.js:8）
-  'gate-status.json',   // worktree-guard 门禁状态（progress.js:9）
   'contract-artifacts', // execute endpoint 契约（verify 阶段读取）
   'execute-runs',       // task review 结果（task-review.js）
 ]);
@@ -209,7 +212,7 @@ function isTTY() {
 
 // ── 核心安装逻辑 ──
 
-async function doInstall(projectDir, tools, subprojects = [], specDir = null) {
+function doInstall(projectDir, tools, subprojects = [], specDir = null) {
   // specDir: 规范目录（默认 projectDir/.sillyspec）
   // projectDir: 源码项目根目录（用于工具检测、指令注入、.gitignore）
   const spec = specDir || join(projectDir, '.sillyspec');
@@ -308,7 +311,7 @@ async function doInstall(projectDir, tools, subprojects = [], specDir = null) {
 
   // 初始化 SQLite 数据库
   const pm = new ProgressManager({ specDir: spec });
-  await pm.init(projectDir);
+  pm.init(projectDir);
 
   // .gitignore 只在 specDir 在项目内时才修改
   const isExternalSpec = specDir && resolve(spec) !== resolve(projectDir, '.sillyspec');
@@ -389,16 +392,6 @@ function showSummary(version, tools, specDir) {
   console.log('');
 }
 
-// ── 读取版本号 ──
-
-export function getVersion() {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'));
-    return pkg.version;
-  } catch {
-    return '?.?.?';
-  }
-}
 
 // ── 主命令 ──