sillyspec 3.25.9 → 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,6 +76,7 @@ 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/）
@@ -228,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');
@@ -253,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) {
@@ -267,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);
@@ -299,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 || '📭 无批量进度数据');
@@ -329,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;
@@ -356,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));
@@ -390,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));
@@ -513,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;
@@ -634,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,
@@ -644,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,
           });
@@ -659,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）
@@ -691,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);
           }
@@ -736,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) {
@@ -787,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');
@@ -818,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) {
@@ -868,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 {
@@ -899,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);
@@ -1058,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': {
@@ -1203,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        旧格式模块文档迁移到新格式
 `);
@@ -1211,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);
@@ -1237,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');
 
@@ -1280,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') {
@@ -1305,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 守卫（旧位置）',
@@ -1348,10 +1481,15 @@ SillySpec modules — 模块文档管理
       break;
     }
     default: {
-      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', '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);
     }
@@ -1364,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 '?.?.?';
-  }
-}
 
 // ── 主命令 ──
 

package/src/machine-interface.js

@@ -7,7 +7,7 @@
  * 设计原则（见 change 2026-07-09-machine-interface-v1 design.md §2/§3）：
  *   - 方案 B：独立模块单点封装，不污染既有 run/progress 输出
  *   - 只聚合不新增校验：复用 stage-contract / task-review / verify-postcheck 既有策略引擎
- *   - 只读语义边界（D-002@v1）：只调 ProgressManager 读路径，不写 sillyspec.db / gate-status.json
+ *   - 只读语义边界（D-002@v1）：只调 ProgressManager 读路径，不写 sillyspec.db
  *   - stdout 纯 JSON（D-005@v1）：--json 模式下由 CLI 层（src/index.js 的 withJsonOutput）
  *     在调用 runGate/runDerive 期间劫持 console.log 到 stderr，防被调模块污染机器输出
  *   - 退出码 0/1/2 三段语义（D-004@v1）：0=通过，1=事实阻断，2=无法核验
@@ -18,8 +18,9 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { ProgressManager, resolveSpecDir } from './progress.js';
+import { resolveRuntimeRoot } from './run/shared.js';
 import { runValidators, checkTransition, checkExecuteCodeEvidence } from './stage-contract.js';
-import { validateTaskReviews } from './task-review.js';
+import { validateTaskReviews, resolveLatestExecuteRunId } from './task-review.js';
 import { runVerifyTestCheck } from './verify-postcheck.js';
 
 // ============ 退出码常量（D-004@v1）============
@@ -101,16 +102,35 @@ export function buildEnvelope({
  * @param {object} opts
  * @param {string} opts.cwd - 项目根目录
  * @param {string} [opts.specBase] - .sillyspec（或平台 specRoot）目录；默认 resolveSpecDir(cwd)
- * @param {string} [opts.runtimeRoot] - .runtime 目录；默认 join(specBase, '.runtime')
+ * @param {string} [opts.runtimeRoot] - .runtime 目录；默认 resolveRuntimeRoot 三级优先级解析
+ * @param {string} [opts.specDriftAnchor] - drift 场景主仓 specBase 锚点（坑 execute-runs-isolation）。
+ *   drift 守卫命中时由调用方传入，task-reviews 的 execute-run-id marker 落点经
+ *   resolveRuntimeRoot 锚主仓 .runtime，不读 worktree 副本（与 contract-matrix 调用方同语义）。
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
-export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot } = {}) {
+export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor } = {}) {
   const specRoot = specBase || resolveSpecDir(cwd);
   const pm = new ProgressManager();
 
   try {
+    // ── 只读契约守卫（D-002@v1）：db 不存在时 fail-closed 返回 exit 2，不触发建库落盘 ──
+    // pm.read → _ensureDB → db.init() 在 db 不存在/schema 戳落后时会 _createSchema + _save 落盘
+    // （db.js:init），这会让一个声明只读的查询命令在 spec 目录凭空建 sillyspec.db，违反只读契约。
+    // db 还没建 = 该变更从未跑过流程，无从核验 → 显式返回「无法核验」而非建库。
+    const dbPath = join(resolveSpecDir(cwd), '.runtime', 'sillyspec.db');
+    if (!existsSync(dbPath)) {
+      const envelope = buildEnvelope({
+        command: 'gate',
+        stage,
+        change: changeName,
+        ok: false,
+        errors: [`无法核验：进度库不存在（${dbPath}）——变更 ${changeName} 尚未运行过任何阶段，只读 gate 不会为其建库`],
+      });
+      return { envelope, exitCode: EXIT_UNKNOWN };
+    }
+
     // ── 读进度：变更不存在 → exit 2（D-004@v1）──
-    const progress = await pm.read(cwd, changeName);
+    const progress = pm.read(cwd, changeName);
     if (!progress) {
       const envelope = buildEnvelope({
         command: 'gate',
@@ -181,13 +201,14 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot }
         }
       }
 
-      const rtRoot = runtimeRoot || join(specRoot, '.runtime');
-      const runIdFile = join(rtRoot, `current-execute-run-id-${changeName}`);
+      // drift 场景经 resolveRuntimeRoot 三级优先级解析（runtimeRoot > specDriftAnchor > 本地兜底），
+      // 锚主仓 .runtime，不读 worktree 副本（坑 execute-runs-isolation，与 contract-matrix 调用方同语义）
+      const rtRoot = resolveRuntimeRoot({ runtimeRoot, specDriftAnchor }, specRoot);
+      // marker 缺失/为空时先扫描 execute-runs/ 找回真实 runId（与 gates.js #6 同源），
+      // 避免拿 '' 进 validateTaskReviews 拼出 execute-runs//tasks/... 产出全量误导 errors。
       let executeRunId = '';
       try {
-        if (existsSync(runIdFile)) {
-          executeRunId = readFileSync(runIdFile, 'utf8').trim();
-        }
+        executeRunId = resolveLatestExecuteRunId({ runtimeRoot: rtRoot, changeName }) || '';
       } catch {
         executeRunId = '';
       }
@@ -300,7 +321,7 @@ export const FACETS = ['execute-evidence', 'verify-test', 'task-reviews', 'artif
  * 与 gate 的差异：gate 聚合某阶段所有 check 的综合结论；derive 只返回单一 facet 的结构化 data，
  * daemon 用来做细粒度事实采集（如轮询 execute-evidence 判断代码是否变更）。
  *
- * 只读语义边界同 gate（D-002@v1）：仅调 ProgressManager.read，不写 sillyspec.db / gate-status.json。
+ * 只读语义边界同 gate（D-002@v1）：仅调 ProgressManager.read，不写 sillyspec.db。
  * 唯一例外是 verify-test 会真实执行测试并落盘 test-result.json（产物取证，非状态写入，design §3.3）。
  *
  * 退出码语义（D-004@v1）：0=事实通过，1=事实性阻断，2=无法核验（用法错/变更不存在/内部异常）。
@@ -310,10 +331,12 @@ export const FACETS = ['execute-evidence', 'verify-test', 'task-reviews', 'artif
  * @param {object} opts
  * @param {string} opts.cwd - 项目根目录
  * @param {string} [opts.specBase] - .sillyspec（或平台 specRoot）目录；默认 resolveSpecDir(cwd)
- * @param {string} [opts.runtimeRoot] - .runtime 目录；默认 join(specBase, '.runtime')
+ * @param {string} [opts.runtimeRoot] - .runtime 目录；默认 resolveRuntimeRoot 三级优先级解析
+ * @param {string} [opts.specDriftAnchor] - drift 场景主仓 specBase 锚点（坑 execute-runs-isolation），
+ *   task-reviews facet 的 execute-run-id marker 落点经 resolveRuntimeRoot 锚主仓 .runtime，不读副本。
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
-export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot } = {}) {
+export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor } = {}) {
   // ── 非法 facet：用法错 → exit 2（D-004@v1）──
   if (!FACETS.includes(facet)) {
     const envelope = buildEnvelope({
@@ -330,8 +353,21 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot
   const pm = new ProgressManager();
 
   try {
+    // ── 只读契约守卫（D-002@v1，同 runGate）：db 不存在时 fail-closed 返回 exit 2，不建库落盘 ──
+    const dbPath = join(resolveSpecDir(cwd), '.runtime', 'sillyspec.db');
+    if (!existsSync(dbPath)) {
+      const envelope = buildEnvelope({
+        command: 'derive',
+        facet,
+        change: changeName,
+        ok: false,
+        errors: [`无法核验：进度库不存在（${dbPath}）——变更 ${changeName} 尚未运行过任何阶段，只读 derive 不会为其建库`],
+      });
+      return { envelope, exitCode: EXIT_UNKNOWN };
+    }
+
     // ── 读进度：变更不存在 → exit 2 ──
-    const progress = await pm.read(cwd, changeName);
+    const progress = pm.read(cwd, changeName);
     if (!progress) {
       const envelope = buildEnvelope({
         command: 'derive',
@@ -399,13 +435,12 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot
           }
         }
 
-        const rtRoot = runtimeRoot || join(specRoot, '.runtime');
-        const runIdFile = join(rtRoot, `current-execute-run-id-${changeName}`);
+        // drift 场景经 resolveRuntimeRoot 三级优先级解析（同 runGate execute 段），锚主仓 .runtime 不读副本
+        const rtRoot = resolveRuntimeRoot({ runtimeRoot, specDriftAnchor }, specRoot);
+        // marker 缺失/为空时先扫描 execute-runs/ 找回真实 runId（同 runGate execute 段），避免拿 '' 误导校验
         let executeRunId = '';
         try {
-          if (existsSync(runIdFile)) {
-            executeRunId = readFileSync(runIdFile, 'utf8').trim();
-          }
+          executeRunId = resolveLatestExecuteRunId({ runtimeRoot: rtRoot, changeName }) || '';
         } catch {
           executeRunId = '';
         }

package/src/migrate.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, renameSync, copyFileSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, renameSync, copyFileSync, statSync, cpSync } from 'fs';
 import { basename, join, resolve } from 'path';
 import chalk from 'chalk';
 
@@ -60,9 +60,19 @@ export function migrateDocs(projectDir) {
       const src = join(archiveDir, entry);
       const dest = join(targetDir, entry);
       if (!existsSync(dest)) {
-        copyFileSync(src, dest);
-        console.log(chalk.green('  ✅') + ` archive/${entry}`);
-        migrated++;
+        // 归档变更本身是目录（含 design.md 等），copyFileSync 对目录源抛 EISDIR；
+        // 按类型分发：目录用 cpSync 递归、文件用 copyFileSync，单条失败 try/catch 不中断整体迁移
+        try {
+          if (statSync(src).isDirectory()) {
+            cpSync(src, dest, { recursive: true });
+          } else {
+            copyFileSync(src, dest);
+          }
+          console.log(chalk.green('  ✅') + ` archive/${entry}`);
+          migrated++;
+        } catch (err) {
+          console.log(chalk.yellow('  ⚠️') + ` archive/${entry} 迁移失败: ${err.message}`);
+        }
       } else {
         console.log(chalk.yellow('  ⏭️') + ` archive/${entry} (已存在)`);
       }