sillyspec 3.25.9 → 3.26.0

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/）
@@ -83,6 +84,8 @@ SillySpec CLI — 规范驱动开发工具包
   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 register-stage-review --change <name> --stage <brainstorm|plan|execute> [--from <review.json>] [--json]
+                                      生成/adopt stage 级 review.json（docHash 自动算 + 写 marker，治 tier=independent marker 死锁）
 
   sillyspec doctor [子命令]            进度库健康检查 + 修复（顶层命令，非 worktree doctor）
     （无子命令）                       跑诊断，列出问题
@@ -228,7 +231,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 +256,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 +270,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 +302,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 +332,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 +359,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 +402,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));
@@ -441,6 +460,41 @@ async function main() {
       }
       break;
     }
+    case 'register-stage-review': {
+      // 手动注册 stage 级 review（brainstorm/plan/execute-acceptance）的确定性 writer ——
+      // 生成 run 目录 + review.json 骨架（cannot_verify，待独立审查子代理填 verdict）或 adopt
+      // agent 草稿（--from，保留 verdict/checklist 重算 docHash）+ 写 marker。治 tier=independent 时
+      // 调度者手动派独立子代理不写 marker 的死锁。docHash 由 CLI computeDocHash 算（部分实现 P6.1b defer）。
+      // 纯新增，不改 gate 语义。与 task 级 backfill-reviews 对称（stage 级等价物）。
+      const rsrChangeIdx = args.indexOf('--change');
+      const rsrChange = rsrChangeIdx >= 0 && args[rsrChangeIdx + 1] ? args[rsrChangeIdx + 1] : null;
+      const rsrStageIdx = args.indexOf('--stage');
+      const rsrStage = rsrStageIdx >= 0 && args[rsrStageIdx + 1] ? args[rsrStageIdx + 1] : null;
+      const rsrFromIdx = args.indexOf('--from');
+      const rsrFrom = rsrFromIdx >= 0 && args[rsrFromIdx + 1] ? args[rsrFromIdx + 1] : null;
+      if (!rsrChange || !rsrStage) {
+        console.error('用法: sillyspec register-stage-review --change <名> --stage <brainstorm|plan|execute> [--from <review.json>] [--spec-dir <path>] [--json]\n  生成/adopt stage 级 review.json（docHash 自动算 + 写 marker），治 tier=independent marker 死锁');
+        process.exit(2);
+      }
+      const { registerStageReview } = await import('./stage-review.js');
+      const rsrPlatformOpts = {};
+      if (specDir) rsrPlatformOpts.specRoot = specDir;
+      try {
+        const result = registerStageReview({ changeName: rsrChange, stage: rsrStage, fromFile: rsrFrom, cwd: dir, platformOpts: rsrPlatformOpts });
+        if (json) {
+          process.stdout.write(JSON.stringify({ ok: true, command: 'register-stage-review', change: rsrChange, stage: rsrStage, ...result }));
+        } else {
+          console.log(`✅ 已注册 ${rsrStage} stage review [${result.reviewRunId}] → ${result.reviewPath}（mode: ${result.mode}）`);
+          console.log(`   marker → ${result.markerPath}`);
+          console.log(`   下一步：独立审查子代理对照 ${result.mainDoc} 填 verdict/checklist 后重跑 --done`);
+        }
+      } catch (e) {
+        if (json) process.stdout.write(JSON.stringify({ ok: false, command: 'register-stage-review', error: e.message }));
+        else console.error('❌ ' + e.message);
+        process.exitCode = 1;
+      }
+      break;
+    }
     case 'docs': {
       const docsSubCmd = filteredArgs[1];
       if (docsSubCmd === 'migrate') {
@@ -513,7 +567,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,6 +649,10 @@ async function main() {
       const { runCommand } = await import('./run.js')
       const stageArgs = [command, ...filteredArgs.slice(1)]
       const effectiveDir = specDir ? dir : resolveEffectiveDir(dir)
+      // 下行 pull：stage 命令（run/--done，含 archive）启动时拉一次（task-10 / D-009 / FR-04）
+      // 不在每步 pull，仅低频边界点；未连接平台静默跳过
+      const { triggerPullActiveChange } = await import('./run/shared.js')
+      await triggerPullActiveChange(effectiveDir)
       await runCommand(stageArgs, effectiveDir, specDir, { json })
       break
     }
@@ -634,9 +692,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 +702,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 +717,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 +750,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);
           }
@@ -716,6 +775,12 @@ SillySpec worktree — git worktree 隔离管理
             for (const err of result.errors) {
               console.error(`   ${err}`);
             }
+            if (result.rescueCommands) {
+              console.error('');
+              console.error(`🆘 Rescue commands (${result.rescueCommands.cpFileCount} safe / ${result.rescueCommands.excludedCount} excluded，旁路 git apply，cp 后需手动 sillyspec worktree cleanup ${wtName}):`);
+              for (const c of result.rescueCommands.commands) console.error(`   ${c}`);
+              for (const w of result.rescueCommands.warnings) console.error(`   ⚠️  ${w}`);
+            }
             process.exit(1);
           }
 
@@ -736,10 +801,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) {
@@ -777,6 +842,12 @@ SillySpec worktree — git worktree 隔离管理
             for (const w of assessment.warnings) console.log(`   ⚠️  ${w}`);
           }
 
+          if (assessment.rescueCommands) {
+            console.log('');
+            console.log(`🆘 Rescue commands (${assessment.rescueCommands.cpFileCount} safe / ${assessment.rescueCommands.excludedCount} excluded，旁路 git apply，cp 后需手动 sillyspec worktree cleanup ${wtName}):`);
+            for (const c of assessment.rescueCommands.commands) console.log(`   ${c}`);
+            for (const w of assessment.rescueCommands.warnings) console.log(`   ⚠️  ${w}`);
+          }
           console.log('');
           if (assessment.decision === 'SAFE' || assessment.decision === 'WARNING') {
             console.log('Action: auto-applying...');
@@ -787,7 +858,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 +889,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 +975,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 +1008,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);
@@ -912,6 +1098,8 @@ SillySpec platform — SillyHub 平台同步
   sillyspec platform disconnect
   sillyspec platform sync [--change <name>]
   sillyspec platform sync-docs [--change <name>]
+  sillyspec platform pull [--change <name>]
+  sillyspec platform resolve <change-name> <--keep-local|--take-platform|--abort>
   sillyspec platform status
   sillyspec platform pointer [--cleanup]
   sillyspec platform approve <change-name>
@@ -1012,15 +1200,108 @@ SillySpec platform — SillyHub 平台同步
           await syncModule.syncDocuments(syncDocsChangeName, dir);
           break;
         }
-        case 'status':
-          await syncModule.status(dir);
+        case 'status': {
+          // task-14 / FR-05：扩展 status（落后标记 + 未决冲突列表）；未连接输出与现状一致
+          const st = await syncModule.collectStatus(dir);
+          if (!st.connected) {
+            console.log('平台: 未连接');
+            break;
+          }
+          console.log(`平台: ${st.url}`);
+          console.log(`上次连接: ${st.lastSync || '未知'}`);
+          if (st.listFailed) {
+            console.log('ℹ️  无法连接平台获取落后状态');
+          } else if (st.behind.length > 0) {
+            console.log(`⚠️ 本地可能落后（${st.behind.length} 个变更平台有更新）:`);
+            for (const b of st.behind) {
+              console.log(`   - ${b.name}: 平台 ${b.platform_pushed_at} > 本地 ${b.local_synced}`);
+            }
+          } else {
+            console.log('✅ 本地与平台进度同步');
+          }
+          if (st.conflicts.length > 0) {
+            console.log(`⚠️ 未决冲突（${st.conflicts.length} 个，请 platform resolve 处理）:`);
+            for (const c of st.conflicts) {
+              console.log(`   - ${c.change}${c.created_at ? ` (创建于 ${c.created_at})` : ''}`);
+            }
+          }
+          break;
+        }
+        case 'pull': {
+          // task-11 / D-006 / D-009 / FR-03：手动下行拉取平台进度到本地。
+          // 与自动 triggerPull 共用 syncModule.pull（SyncManager.pull 实例方法），行为一致。
+          const pullChangeIdx = args.indexOf('--change');
+          const pullChangeName = pullChangeIdx >= 0 && args[pullChangeIdx + 1] ? args[pullChangeIdx + 1] : null;
+          // 未连接明确提示不崩（acceptance：未连接平台输出明确提示）
+          const smForCheck = new syncModule.SyncManager(dir);
+          if (!smForCheck._getPlatform()) {
+            console.error('❌ 未连接平台，请先 sillyspec platform connect');
+            process.exit(1);
+          }
+          if (pullChangeName) {
+            // 单变更完整 pull（两级 pull 第二级）
+            const r = await syncModule.pull(pullChangeName, {}, dir);
+            if (r.conflict) {
+              console.log(`⚠️ ${pullChangeName}: 冲突（已写 sync-conflict 文件），请 sillyspec platform resolve 处理`);
+            } else if (r.imported) {
+              console.log(`✅ ${pullChangeName}: 已拉取并 import`);
+            } else {
+              console.log(`⏭️ ${pullChangeName}: 未 import（${r.reason || '无变更'}）`);
+            }
+          } else {
+            // 无 --change：先拉轻量列表（两级 pull 第一级），再对每个 change 按需完整 pull
+            const list = await syncModule.pullList(dir);
+            if (!list.ok) {
+              console.error(`❌ 拉取变更列表失败: ${list.reason || '未知'}`);
+              process.exit(1);
+            }
+            console.log(`平台变更 ${list.changes.length} 个：`);
+            let importedCount = 0, conflictCount = 0;
+            for (const ch of list.changes) {
+              const name = typeof ch === 'string' ? ch : ch.name;
+              if (!name) continue;
+              const r = await syncModule.pull(name, {}, dir);
+              if (r.imported) { importedCount++; console.log(`  ✅ ${name}: 已 import`); }
+              else if (r.conflict) { conflictCount++; console.log(`  ⚠️ ${name}: 冲突，请 platform resolve`); }
+              else { console.log(`  ⏭️ ${name}: ${r.reason || '未 import'}`); }
+            }
+            console.log(`拉取完成：imported ${importedCount}，冲突 ${conflictCount}`);
+          }
           break;
+        }
+        case 'resolve': {
+          // task-13 / D-002 / D-010 / D-013 / FR-05：冲突解决三选一（绝不字段级 auto-merge）
+          const resolveName = platformArgs[0];
+          if (!resolveName) {
+            console.error('❌ 用法: sillyspec platform resolve <change-name> <--keep-local|--take-platform|--abort>');
+            process.exit(1);
+          }
+          // 解析 mode flag（三选一互斥，多传/不传均报错）
+          const resolveFlags = ['--keep-local', '--take-platform', '--abort'].filter((f) => args.includes(f));
+          if (resolveFlags.length !== 1) {
+            console.error('❌ 必须恰好指定 --keep-local / --take-platform / --abort 之一');
+            process.exit(1);
+          }
+          const modeMap = { '--keep-local': 'keep-local', '--take-platform': 'take-platform', '--abort': 'abort' };
+          const resolveMode = modeMap[resolveFlags[0]];
+          const r = await syncModule.resolve(resolveName, resolveMode, dir);
+          if (r.ok && r.resolved) {
+            console.log(`✅ ${resolveName} [${resolveMode}]: ${r.reason}`);
+          } else {
+            console.error(`❌ ${resolveName}: ${r.reason}`);
+            process.exit(1);
+          }
+          break;
+        }
         case 'approve': {
           const approveName = platformArgs[0];
           if (!approveName) {
             console.error('❌ 用法: sillyspec platform approve <change-name>');
             process.exit(1);
           }
+          // 审批前下行 pull（task-10 / D-009 / FR-06）：拉最新进度避免基于过期状态审批；未连接跳过
+          const { triggerPull } = await import('./run/shared.js');
+          await triggerPull(dir, approveName);
           await syncModule.approve(approveName, dir);
           break;
         }
@@ -1058,7 +1339,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 +1484,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 +1492,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 +1519,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 +1562,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 +1587,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 +1629,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', 'register-stage-review', '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 +1650,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;
 });