sillyspec 3.28.3 → 3.28.5

package/src/mcp-server.js

@@ -0,0 +1,144 @@
+/**
+ * mcp-server.js（P2-g = MCP Phase 2，noai-ir-roadmap §5）：SillySpec 最小 stdio MCP server。
+ *
+ * 动机：agent 此前靠 shell 调 CLI + 解析人类可读文本，flag 幻觉与文本解析漂移是真实痛点
+ * （铁律里专门有一条「不确定命令时停下问用户」）。MCP tools 的 schema 化参数把 flag 面锁死；
+ * machine-interface 的 JSON envelope（gate/derive/progress）与 next 的 JSON 输出是现成地基。
+ *
+ * 形态：`sillyspec mcp` 启动（hosts 配 command=sillyspec args=[mcp]）。stdio 上跑 JSON-RPC 2.0
+ * 行协议（每行一个请求/响应）。**只读 tools**（Phase 2 边界：--done 等状态推进不暴露——
+ * Phase 3 另计；工具全部经子进程 `--json` 执行，stdout 纪律天然隔离，不 import 重模块）：
+ *   - sillyspec_next：状态探测与下一步建议（detectNextStep）
+ *   - sillyspec_gate：阶段完成门控聚合（machine-interface runGate envelope）
+ *   - sillyspec_derive：单项事实核验（runDerive envelope）
+ *   - sillyspec_progress：全局进度总览（progress show --json envelope）
+ */
+import { createInterface } from 'node:readline'
+import { spawn } from 'node:child_process'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const CLI_ENTRY = join(__dirname, 'index.js')
+const PROTOCOL_VERSION = '2025-06-18'
+const SERVER_INFO = { name: 'sillyspec', version: '3.28.4' }
+
+const TOOLS = [
+  {
+    name: 'sillyspec_next',
+    description: '项目状态探测：状态 + 下一步命令 + 依据 + 活跃变更列表（只读；无活跃进度时从产物反推）',
+    inputSchema: { type: 'object', properties: { spec_dir: { type: 'string', description: '规范目录（缺省 <cwd>/.sillyspec）' } } },
+  },
+  {
+    name: 'sillyspec_gate',
+    description: '阶段完成门控聚合：变更的 <stage> 阶段此刻能否标记完成（envelope：ok/errors/warnings/checks；exit 0/1/2）',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        stage: { type: 'string', enum: ['brainstorm', 'plan', 'execute', 'verify', 'archive'], description: '目标阶段' },
+        change: { type: 'string', description: '变更名（必填）' },
+        spec_dir: { type: 'string' },
+      },
+      required: ['stage', 'change'],
+    },
+  },
+  {
+    name: 'sillyspec_derive',
+    description: '单项事实核验（facet：execute-evidence / verify-test / task-reviews / artifacts）',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        facet: { type: 'string', enum: ['execute-evidence', 'verify-test', 'task-reviews', 'artifacts'] },
+        change: { type: 'string' },
+        spec_dir: { type: 'string' },
+      },
+      required: ['facet', 'change'],
+    },
+  },
+  {
+    name: 'sillyspec_progress',
+    description: '全局进度总览（活跃变更 × 阶段 × 步骤态，envelope JSON；只读）',
+    inputSchema: { type: 'object', properties: { spec_dir: { type: 'string' } } },
+  },
+]
+
+/** tools/call 路由：子进程 --json（stdout 纪律隔离；CLI 的 stderr 透传进 text 供诊断） */
+async function callTool(name, args) {
+  const argv = ['--meta'] // 占位防误配：--meta 是 run 的 flag，工具不走 run
+  argv.length = 0
+  const specDir = args && typeof args.spec_dir === 'string' && args.spec_dir ? ['--spec-dir', args.spec_dir] : []
+  switch (name) {
+    case 'sillyspec_next':
+      return await runCli(['next', '--json', ...specDir])
+    case 'sillyspec_gate':
+      return await runCli(['gate', String(args.stage), '--change', String(args.change), '--json', ...specDir])
+    case 'sillyspec_derive':
+      return await runCli(['derive', String(args.facet), '--change', String(args.change), '--json', ...specDir])
+    case 'sillyspec_progress':
+      return await runCli(['progress', 'show', '--json', ...specDir])
+    default:
+      return { text: `未知工具: ${name}`, isError: true }
+  }
+}
+
+function runCli(cliArgs) {
+  return new Promise((resolve) => {
+    const p = spawn(process.execPath, [CLI_ENTRY, ...cliArgs], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let out = ''
+    let err = ''
+    p.stdout.on('data', (d) => { out += String(d) })
+    p.stderr.on('data', (d) => { err += String(d) })
+    p.on('close', (code) => {
+      // envelope 原样透传（text = stdout JSON 全文；machine 侧自解）；stderr 仅失败时附诊断
+      const text = (out.trim() || err.trim().slice(-2000) || `（exit ${code}，无输出）`)
+      resolve({ text, isError: code !== null && code !== 0 && code !== 1, exitCode: code })
+    })
+    p.on('error', (e) => resolve({ text: `CLI 子进程失败: ${e.message}`, isError: true }))
+  })
+}
+
+/** 单请求分发。返回 result 对象（或抛 {code, message} 形态错误由上层包 error）。 */
+async function handleMessage(msg) {
+  const { id, method, params } = msg
+  switch (method) {
+    case 'initialize':
+      return { protocolVersion: (params && params.protocolVersion) || PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO }
+    case 'ping':
+      return {}
+    case 'tools/list':
+      return { tools: TOOLS }
+    case 'tools/call': {
+      const name = params && params.name
+      const args = (params && params.arguments) || {}
+      const r = await callTool(name, args)
+      return { content: [{ type: 'text', text: r.text }], ...(r.isError ? { isError: true } : {}) }
+    }
+    default:
+      throw { code: -32601, message: `Method not found: ${method}` }
+  }
+}
+
+/** stdio 行协议主循环（readline 逐行 JSON；通知无 id 不回包）。导出供测试与 `sillyspec mcp` 接线。 */
+export function startMcpServer({ input = process.stdin, output = process.stdout } = {}) {
+  const rl = createInterface({ input })
+  rl.on('line', async (line) => {
+    const trimmed = line.trim()
+    if (!trimmed) return
+    let msg
+    try { msg = JSON.parse(trimmed) } catch { return /* 非 JSON 行静默忽略（协议健壮性） */ }
+    if (msg === null || typeof msg !== 'object' || !msg.method) return
+    if (msg.id === undefined || msg.id === null) return // notification（如 notifications/initialized）
+    try {
+      const result = await handleMessage(msg)
+      output.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result }) + '\n')
+    } catch (e) {
+      const err = e && typeof e === 'object' && e.code !== undefined ? e : { code: -32603, message: (e && e.message) || String(e) }
+      output.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, error: err }) + '\n')
+    }
+  })
+  return new Promise((resolve) => rl.on('close', () => resolve()))
+}

package/src/module-impact.js

@@ -10,8 +10,10 @@
  * diff 源：resolveVerifyChangedFiles（worktree-aware，与 task-review 同源）；
  * module-map：.sillyspec/docs/<p>/modules/_module-map.yaml 的 modules.<id>.paths
  * （目录条目以 / 结尾按前缀匹配，与模块上下文索引读侧口径一致）。
+ * 声明源（plan --done 首版，2026-09-08 刀②）：design 文件变更清单——代码未写、无 diff，
+ * 归属分类同一套 module-map 前缀匹配，仅输入来源不同。
  */
-import { existsSync, readFileSync, readdirSync } from 'fs'
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { resolveVerifyChangedFiles } from './verify-postcheck.js'
 import { resolveSpecDir } from './run/shared.js'
@@ -68,11 +70,67 @@ function classifyFile(posixPath, modulePaths) {
 
 /**
  * 生成 module-impact.md 骨架。
- * @param {{ cwd: string, changeName: string, specDir?: string|null }} opts
+ * @param {{ cwd: string, changeName: string, specDir?: string|null, sourceFiles?: string[]|null, origin?: string|null }} opts
+ *   sourceFiles：声明来源（plan --done 首版用 design 文件变更清单——此时代码未写、无 diff 可取）；
+ *     缺省走 diff 来源（resolveVerifyChangedFiles，archive/execute 后的真实改动）。
+ *   origin：骨架首行的生成方说明（区分 plan 首版与 CLI 命令生成，追溯来源用）。
  * @returns {{ markdown: string, matchedCount: number, unmatchedCount: number }|null}
- *   无 module-map / 无 diff → null（无可归类输入，agent 全手写）
+ *   无 module-map / 无可归类文件 → null（无可归类输入，agent 全手写）
  */
-export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null }) {
+/**
+ * 模块文档 sidecar 同步命令化（2026-09-09 刀批，轮次经济学 §3.1 模块文档同步项）：
+ * quick/archive 两处 prompt 让 agent 手写 sidecar 追加行——机械部分（变更归属模块、
+ * sidecar 追加、卡 updated_at 戳）CLI 代算，agent 只留卡片正文语义更新。
+ * 幂等：sidecar 已含 `- <change> |` 行则跳过该模块；卡不存在只建 sidecar 不建卡（卡内容是语义）。
+ * @returns {{ synced: string[], unmatched: string[], skipped: string[] }}
+ */
+export function syncModuleDocSidecars({ cwd, changeName, note, specDir = null }) {
+  const specBase = resolveSpecDir(cwd, { specDir })
+  // 复用 generateModuleImpactSkeleton 的 map 发现 + 归类（diff 来源）
+  const skel = generateModuleImpactSkeleton({ cwd, changeName, specDir })
+  if (!skel) return { synced: [], unmatched: [], skipped: [], reason: '无 module-map 或无 diff 可归类' }
+  const modulesDir = findModulesDir(specBase)
+  if (!modulesDir) return { synced: [], unmatched: [], skipped: [], reason: 'modules 目录不存在' }
+  // 从骨架 markdown 反解归类结果（命中模块集合 + 未匹配清单）
+  const hitModules = [...skel.markdown.matchAll(/^\| (\S+) \| `([^`]+)`/gm)].map(m => m[1])
+  const unmatched = [...skel.markdown.matchAll(/^- `([^`]+)` /gm)].map(m => m[1])
+  const synced = []
+  const skipped = []
+  for (const mod of [...new Set(hitModules)]) {
+    const sidecarPath = join(modulesDir, `${mod}.changelog.md`)
+    let sidecar = ''
+    try { sidecar = readFileSync(sidecarPath, 'utf8') } catch { sidecar = '' }
+    if (sidecar.includes(`- ${changeName} |`)) { skipped.push(mod); continue }
+    const NL = String.fromCharCode(10)
+    const line = `- ${changeName} | ${note || '(见该变更 quicklog/归档)'}`
+    const base = sidecar
+      ? sidecar.replace(/\n*$/, NL)
+      : `# ${mod} 变更索引` + NL + NL
+    writeFileSync(sidecarPath, base + line + NL)
+    // 卡 updated_at 戳（存在才戳）
+    const cardPath = join(modulesDir, `${mod}.md`)
+    try {
+      const card = readFileSync(cardPath, 'utf8')
+      const stamped = card.replace(/^updated_at:.*$/m, `updated_at: ${new Date().toISOString().slice(0, 19) + '+08:00'}`)
+      if (stamped !== card) writeFileSync(cardPath, stamped)
+    } catch { /* 卡不存在——sidecar 照写，卡内容留给 agent */ }
+    synced.push(mod)
+  }
+  return { synced, unmatched, skipped }
+}
+
+function findModulesDir(specBase) {
+  try {
+    for (const p of readdirSync(join(specBase, 'docs'), { withFileTypes: true })) {
+      if (!p.isDirectory()) continue
+      const cand = join(specBase, 'docs', p.name, 'modules')
+      if (existsSync(join(cand, '_module-map.yaml'))) return cand
+    }
+  } catch { /* 无 docs/ */ }
+  return null
+}
+
+export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null, sourceFiles = null, origin = null }) {
   const specBase = resolveSpecDir(cwd, { specDir })
 
   // 找 _module-map.yaml（docs/<p>/modules/；多项目取首个含 modules 索引的）
@@ -92,15 +150,27 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null }
   const modulePaths = parseModuleMapPaths(readFileSync(moduleMapPath, 'utf8'))
   if (modulePaths.size === 0) return null
 
-  // includeWorkingTree 同 verify module 子集（坑 module-subset-zero-hit-uncommitted）：
-  // worktree 未提交改动也计入模块影响面（module-impact 按实际 diff 归属模块）
-  const diffFiles = resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true, specBase }) || []
-  const sourceFiles = diffFiles.map(f => f.split('\\').join('/')).filter(f => !f.startsWith('.sillyspec/'))
-  if (sourceFiles.length === 0) return null
+  let sourceFileList
+  if (sourceFiles) {
+    // NEW: 前缀剥离（坑 module-impact-new-prefix-mismatch，2026-09-10 驾驭小结③，用户实锤）：
+    // design 清单待建文件带 NEW: 标记，pathMatches 比对侧早已剥（坑
+    // platform-sync-progress-rollback-and-db-corruption 坑3「仅在比对处剥」），本归类是同
+    // 语义比对（目标文件 × module-map paths）却漏剥——前缀不剥则 classifyFile 前缀匹配必
+    // 失配，NEW 文件全部落「未匹配文件」逼手动回填。剥后与裸路径去重（NEW: a.js 与 a.js 同文件）。
+    sourceFileList = [...new Set(sourceFiles
+      .map(f => String(f).replace(/^NEW:\s*/, '').split('\\').join('/').trim())
+      .filter(f => f && !f.startsWith('.sillyspec/')))]
+  } else {
+    // includeWorkingTree 同 verify module 子集（坑 module-subset-zero-hit-uncommitted）：
+    // worktree 未提交改动也计入模块影响面（module-impact 按实际 diff 归属模块）
+    const diffFiles = resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true, specBase }) || []
+    sourceFileList = diffFiles.map(f => f.split('\\').join('/')).filter(f => !f.startsWith('.sillyspec/'))
+  }
+  if (sourceFileList.length === 0) return null
 
   const byModule = new Map()
   const unmatched = []
-  for (const f of sourceFiles) {
+  for (const f of sourceFileList) {
     const mod = classifyFile(f, modulePaths)
     if (mod) {
       if (!byModule.has(mod)) byModule.set(mod, [])
@@ -111,7 +181,9 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null }
   }
 
   const L = [
-    '# 模块影响分析（骨架由 `sillyspec module-impact --change <变更名>` 生成）',
+    origin
+      ? `# 模块影响分析（骨架由 ${origin} 生成）`
+      : '# 模块影响分析（骨架由 `sillyspec module-impact --change <变更名>` 生成）',
     '',
     '> 文件×模块归属由 CLI 按 _module-map.yaml paths 前缀匹配预填；',
     '> **影响类型**（逻辑变更/数据结构变更/接口变更/调用关系变更/配置变更/新增）与 review 标记是语义判断，',
@@ -162,5 +234,5 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null }
   L.push('规则：execute/verify 完成文档同步后把对应行回填 done；确定不同步的行改 skipped 并在操作列写明原因。')
   L.push('')
 
-  return { markdown: L.join('\n'), matchedCount: sourceFiles.length - unmatched.length, unmatchedCount: unmatched.length }
+  return { markdown: L.join('\n'), matchedCount: sourceFileList.length - unmatched.length, unmatchedCount: unmatched.length }
 }

package/src/modules.js

@@ -87,18 +87,16 @@ export async function rebuildModuleMap(cwd, { force = false } = {}) {
     }
   }
 
-  // 解析现有 _module-map.yaml 保留已有字段（复用 parseModuleMapSimple：原内置解析只收模块名、
-  // 从不收集列表项 → existingPaths 恒空 → --force 重建后 core_files 全丢，scan-diff scope 退化
-  // 为全量、module-impact classifyFile 全 unmatched——注释声称的「从已有 map 保留」名存实亡）
+  // 解析现有 _module-map.yaml（复用 parseModuleMapSimple canonical 解析）。P2-c
+  //（noai-ir-roadmap §5 字段分离）：existing 条目**全字段**整体保留——merge 语义下
+  // rebuild 只做「补缺 + 增新卡」，--force 不再可能清空 tags/main_symbols/depends_on/
+  // used_by/status/needs_review 等人工维护字段（旧版只保 3 个列表字段，实例 map 文件头
+  // 常年挂着「勿跑 rebuild --force 会清空手动维护」的警告——该警告随本变更退役）。
   let existingModules = {};
   if (existingMap) {
     const parsed = parseModuleMapSimple(existingMap);
     for (const [id, fields] of Object.entries(parsed || {})) {
-      existingModules[id] = {
-        core_files: Array.isArray(fields.core_files) ? fields.core_files : [],
-        test_files: Array.isArray(fields.test_files) ? fields.test_files : [],
-        entrypoints: Array.isArray(fields.entrypoints) ? fields.entrypoints : [],
-      };
+      existingModules[id] = { ...(fields || {}) };
     }
   }
 
@@ -132,53 +130,67 @@ export async function rebuildModuleMap(cwd, { force = false } = {}) {
     ...cards.map(c => c.moduleId)
   ]);
 
+  // ── P2-c merge 语义发射：existing 全字段优先（人工维护不丢）→ 卡片补缺 → 骨架默认垫底 ──
+  const stripQuotes = (v) => String(v).replace(/^"|"$/g, '')
   for (const moduleId of allModuleIds) {
     const card = cards.find(c => c.moduleId === moduleId);
     const cardContent = card?.content || '';
 
     // 从模块卡片提取 context index 字段
     const role = extractSection(cardContent, '定位') || '';
-    const contract = extractSection(cardContent, '契约摘要') || '';
-    const logic = extractSection(cardContent, '关键逻辑') || '';
-    const notes = extractSection(cardContent, '注意事项') || '';
 
-    yaml += `  ${moduleId}:\n`;
-    yaml += `    status: active\n`;
-    if (card) yaml += `    doc: modules/${card.filename}\n`;
-    else yaml += `    doc: modules/${moduleId}.md\n`;
-    yaml += `    needs_review: false\n`;
-    yaml += `    review_reasons: []\n`;
-    // context index 字段（v2）
-    if (role) yaml += `    role: "${escapeYamlString(role)}"\n`;
-    // core_files / test_files / entrypoints 从已有 _module-map.yaml 全量保留（列表项级保真）
     const existing = existingModules[moduleId] || {};
-    for (const [field, items] of [['core_files', existing.core_files], ['test_files', existing.test_files], ['entrypoints', existing.entrypoints]]) {
-      if (Array.isArray(items) && items.length > 0) {
-        yaml += `    ${field}:\n`;
-        for (const p of items) yaml += `      - ${p}\n`;
-      }
+    const merged = {
+      // 骨架默认（垫底）
+      status: 'active',
+      doc: `modules/${(card && card.filename) || moduleId + '.md'}`,
+      needs_review: false,
+      review_reasons: [],
+      risk_level: 'low',
+      verify_commands: [],
+      related_docs: [],
+      // existing 全字段覆盖（人工维护优先）
+      ...existing,
+    }
+    // 卡片补缺：role 仅当 existing 没有时从卡片取；doc 在卡片在场时以卡片文件名为准
+    //（existing.doc 可能指向已改名的旧文件）；卡片不在场则保留 existing.doc
+    if (!merged.role && role) merged.role = role
+    if (card) merged.doc = `modules/${card.filename}`
+
+    yaml += `  ${moduleId}:\n`;
+    for (const k of ['status', 'doc', 'needs_review']) {
+      if (merged[k] !== undefined) yaml += `    ${k}: ${typeof merged[k] === 'boolean' ? merged[k] : merged[k]}\n`;
+    }
+    if (merged.role) yaml += `    role: "${escapeYamlString(stripQuotes(merged.role))}"\n`;
+    // 列表字段全量保真（existing 用什么字段名就保什么——paths/core_files 双形态兼容读者）
+    for (const k of ['paths', 'core_files', 'test_files', 'entrypoints', 'main_symbols', 'tags', 'aliases', 'depends_on', 'used_by', 'review_reasons', 'related_docs', 'verify_commands']) {
+      const items = merged[k];
+      if (items === undefined) continue;
+      if (Array.isArray(items) && items.length === 0) { yaml += `    ${k}: []\n`; continue }
+      if (!Array.isArray(items) || items.length === 0) continue;
+      yaml += `    ${k}:\n`;
+      for (const p of items) yaml += `      - ${p}\n`;
     }
-    if (card) yaml += `    verify_commands: []\n`;
-    yaml += `    risk_level: low\n`;
-    if (contract || logic) yaml += `    related_docs: []\n`;
+    if (merged.risk_level !== undefined) yaml += `    risk_level: ${merged.risk_level}\n`;
     yaml += `\n`;
   }
 
-  // 破坏性保护（multi-agent-platform 坑 modules-rebuild-destructive）：默认 dry-run 只预览不写，--force 才覆盖。
+  // 写入保护（multi-agent-platform 坑 modules-rebuild-destructive）：默认 dry-run 只预览不写。
+  // P2-c 后 --force 为 merge 语义（手动字段全量保留），但重写仍会刷新 generated_at/source_commit
+  // 与排版——dry-run 预览默认保留，确认写入用 --force。
   if (!force && existingMap) {
-    console.log('⚠️  rebuild 默认不写入（破坏性保护）：该命令会覆盖 _module-map.yaml，清空 tags/entrypoints/main_symbols/depends_on/used_by 等手动维护字段');
-    console.log('    本次为预览，未写入磁盘。确认覆盖请运行：sillyspec modules rebuild --force');
+    console.log('⚠️  rebuild 默认不写入（预览保护）。--force 为 merge 语义：existing 全字段保留（tags/main_symbols/depends_on/used_by/status/needs_review 等手动维护字段不丢），只补缺 + 增新卡');
+    console.log('    本次为预览，未写入磁盘。确认写入请运行：sillyspec modules rebuild --force');
     return { dryRun: true, path: mapPath }
   }
 
   writeFileSync(mapPath, yaml, 'utf8');
-  console.log(`✅ _module-map.yaml 已重建：${mapPath}`);
+  console.log(`✅ _module-map.yaml 已重建（merge 语义）：${mapPath}`);
   console.log(`   模块数量：${allModuleIds.size}`);
   for (const id of allModuleIds) {
     console.log(`   - ${id}`);
   }
-  console.log(`\n⚠️  注意：rebuild 只重建骨架。tags/entrypoints/main_symbols/depends_on/used_by 需要重新运行 scan 或手动补充。`);
-  console.log(`ℹ️  schema 已升级到 v2，支持 role/core_files/test_files/entrypoints/depends_on/risk_level/verify_commands 等字段。`);
+  console.log(`\nℹ️  手动维护字段（tags/entrypoints/main_symbols/depends_on/used_by/status/needs_review 等）已全量保留；rebuild 只补缺与增新卡。`);
   return { dryRun: false, path: mapPath, modules: allModuleIds.size }
 }
 

package/src/plan-adopt-waves.js

@@ -60,12 +60,17 @@ function updateSummaryWaveColumn(lines, waveOf) {
 }
 
 /**
- * @param {{ changeDir: string, dryRun?: boolean }} opts
+ * @param {{ changeDir: string, dryRun?: boolean, mode?: 'write'|'proposal' }} opts
+ *   mode='proposal'（2026-09-09-plan-derived）：只读产拓扑布局提案——渲染 Wave 段草稿与
+ *   W 列同步结果但不落盘，供 postcheck「提案-验证-落盘」自动修复（FR-01）验证后决断写否。
  * @returns {{ ok: boolean, error?: string, waves?: string[][], planPath: string, dryRun: boolean,
  *             waveBlock?: string[], tableRowsUpdated?: number, tableRowsSkipped?: number,
+ *             planMdDraft?: string, rewritten?: boolean,
  *             postcheck?: { errors: string[], warnings: string[] } }}
+ *   planMdDraft：proposal 档下的完整 plan.md 草稿文本；rewritten：与原文比较是否有实际变更
+ *   （幂等重排零变更 → false，调用方静默）；write 档沿用既有 postcheck 字段。
  */
-export function adoptPlanWaves({ changeDir, dryRun = false }) {
+export function adoptPlanWaves({ changeDir, dryRun = false, mode = 'write' }) {
   const planPath = join(changeDir, 'plan.md')
   if (!existsSync(planPath)) return { ok: false, error: `plan.md 不存在: ${planPath}`, planPath, dryRun }
   const tasksDir = join(changeDir, 'tasks')
@@ -108,9 +113,11 @@ export function adoptPlanWaves({ changeDir, dryRun = false }) {
 
   const { updated, skipped } = updateSummaryWaveColumn(lines, waveOf)
   const content = lines.join('\n').replace(/\n*$/, '\n')
+  const rewritten = content !== original.replace(/\r\n/g, '\n').replace(/\n*$/, '\n')
 
-  if (dryRun) {
-    return { ok: true, waves, planPath, dryRun: true, waveBlock, tableRowsUpdated: updated, tableRowsSkipped: skipped }
+  if (dryRun || mode === 'proposal') {
+    return { ok: true, waves, planPath, dryRun: true, waveBlock, tableRowsUpdated: updated, tableRowsSkipped: skipped,
+      planMdDraft: content, rewritten }
   }
 
   writeFileSync(planPath, content, 'utf8')
@@ -122,5 +129,6 @@ export function adoptPlanWaves({ changeDir, dryRun = false }) {
   } catch (e) {
     postcheck = { errors: [`复跑校验异常: ${e?.message || e}`], warnings: [] }
   }
-  return { ok: true, waves, planPath, dryRun: false, waveBlock, tableRowsUpdated: updated, tableRowsSkipped: skipped, postcheck }
+  return { ok: true, waves, planPath, dryRun: false, waveBlock, tableRowsUpdated: updated, tableRowsSkipped: skipped,
+    rewritten, postcheck }
 }

package/src/progress/change-registry.js

@@ -46,6 +46,40 @@ export class ChangeRegistry {
    * @param {string} changeName - 变更名
    * @returns {{ current_stage: string, status: string }|null} 无该行返回 null（未注册目录桩）
    */
+  /**
+   * 读某变更某阶段的 completed_at（2026-09-08-ir-verify-facts FR-02：verifyStartAt 基准——
+   * evidence 分类核验的 mtime 窗口下界，取 execute 行 completed_at）。只读不抛：无行/读失败
+   * 返回 null（调用方走 R-05 fallback，与 getChangeCreatedAt 同容错风格）。
+   */
+  getStageCompletedAt(cwd, changeName, stage) {
+    try {
+      const db = this.pm._ensureDB(cwd);
+      const row = db.getDb().prepare(
+        `SELECT s.completed_at FROM stages s JOIN changes c ON s.change_id = c.id
+         WHERE c.name = ? AND s.stage = ? ORDER BY s.completed_at DESC LIMIT 1`
+      ).get(changeName, stage);
+      return row && row.completed_at ? row.completed_at : null;
+    } catch { return null; }
+  }
+
+  /**
+   * 读某变更某阶段的 started_at（2026-09-10 用户反馈②：evidence mtime 窗口锚点从
+   * execute completed_at 放宽到 started_at——证据合法产自 execute 或 verify 两窗口，
+   * 锚「完成时刻」会把 execute 期间产的证据判旧，逼出「先提交则 diff 空、不提交则
+   * mtime 旧」的时序两难）。只读不抛：无行/列空/读失败返回 null（调用方退
+   * getStageCompletedAt → R-05 fallback，与 getStageCompletedAt 同族容错）。
+   */
+  getStageStartedAt(cwd, changeName, stage) {
+    try {
+      const db = this.pm._ensureDB(cwd);
+      const row = db.getDb().prepare(
+        `SELECT s.started_at FROM stages s JOIN changes c ON s.change_id = c.id
+         WHERE c.name = ? AND s.stage = ? ORDER BY s.started_at DESC LIMIT 1`
+      ).get(changeName, stage);
+      return row && row.started_at ? row.started_at : null;
+    } catch { return null; }
+  }
+
   getChangeStage(cwd, changeName) {
     const db = this.pm._ensureDB(cwd);
     const sqlDb = db.getDb();

package/src/progress.js

@@ -10,7 +10,7 @@
  * worktree-guard hook 直读 sillyspec.db，不再有 gate-status.json 缓存双源（task-10 废除）。
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync, readdirSync, statSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync, readdirSync, statSync, realpathSync } from 'fs';
 import { join, basename, dirname, resolve, sep } from 'path';
 import { tmpdir } from 'os';
 import { writeAtomicSync } from './fs-atomic.js';
@@ -25,13 +25,19 @@ import { STAGE_ORDER, MAIN_FLOW_ORDER, VALID_STAGES, STAGE_LABELS, SPEC_DIR_NAME
 // resolveSpecDir 单一真相源在 src/run/shared.js（含 home 拒绝守卫，坑 cwd-correction-home-collision
 // 根治：home 下 .sillyspec 恒不命中，防 smoke/临时目录污染自我延续）。此处 re-export 保持
 // 既有 import 路径兼容；run/shared.js 对 progress.js 只有动态 import，无静态循环。
-import { resolveSpecDir, checkPlatformManaged, PLATFORM_MANAGED_FILENAME, isSelfReferentialSpecRoot } from './run/shared.js';
+import { resolveSpecDir, checkPlatformManaged, PLATFORM_MANAGED_FILENAME, isSelfReferentialSpecRoot, isTempResidueSpecRoot } from './run/shared.js';
 export { resolveSpecDir };
 
 // 默认规范目录名（相对于 cwd）
 // SPEC_DIR_NAME → ./progress/shared.js（W6 Step9d）
 const RUNTIME_SUBDIR = '.runtime';
 
+// import() 的 pre-import 快照保留份数。这类快照只服务「刚 pull 完发现平台盖错、要退回
+// pull 前」这一个场景，最新一份即可覆盖；越旧的快照 schema 可能已 bump，恢复价值随时间衰减。
+// 可用 SILLYSPEC_PREIMPORT_BAK_KEEP 覆盖（灾难排查期想多留几份时）。
+const PRE_IMPORT_BAK_KEEP_DEFAULT = 1;
+const PRE_IMPORT_BAK_RE = /^sillyspec\.db\.pre-import-.*\.bak$/;
+
 /**
  * 向上查找含 .sillyspec 目录的祖先目录——实现已收敛至 src/run/shared.js（单一真相源，
  * 含 home 拒绝守卫），此处 re-export。见顶部 import 说明。
@@ -95,6 +101,18 @@ export function resolvePlatformSpecDir(cwd, explicitSpecDir = null) {
     // 指针丢失不该静默当纯本地项目处理（会建本地进度库 → 状态分裂）。
     const decl = checkPlatformManaged(cwd);
     if (decl) {
+      // temp 残留降级（2026-09-08 temp 投毒治理）：声明 specRoot 在系统 temp 且 cwd 不在
+      // temp → 可证伪的测试/联调残留（真实平台 spec 根永不在 temp），与指针路径的 temp
+      // 警告（下方 resolvedTmp 分支）及自指声明降级（run/command.js 恢复链）同类。warn +
+      // 自动清理声明后按本地模式继续——不清理则每次命令重复 warn，且 disconnect 会连带
+      // 清 local.yaml platform 段误伤真实平台连接，不适合作为残留清理手段。
+      // 删除失败仍按本地继续（best effort；下次命令重复 warn 提示手动清理）。
+      if (isTempResidueSpecRoot(cwd, decl.specRoot)) {
+        const declarationPath = join(resolve(cwd), PLATFORM_MANAGED_FILENAME);
+        console.warn(`⚠️ 检测到 temp 残留平台接管声明（specRoot 指向系统 temp 目录：${decl.specRoot}，测试/联调投毒特征），已自动清理并按本地模式运行: ${declarationPath}`);
+        try { unlinkSync(declarationPath) } catch { /* best effort */ }
+        return resolveSpecDir(cwd);
+      }
       throw new PlatformManagedError({
         declarationPath: join(resolve(cwd), PLATFORM_MANAGED_FILENAME),
         specRoot: decl.specRoot,
@@ -141,6 +159,14 @@ export function resolvePlatformSpecDir(cwd, explicitSpecDir = null) {
       `   修复：sillyspec platform pointer --cleanup（删除 ${pointerPath}），或删除该 pointer 文件后回到项目目录重跑。`
     );
   }
+  // junction 规范化（2026-09-10 驾驭小结第五批①，用户实锤「design-init/endpoints 落盘路径
+  // 偶发锚到 daemon junction 副本」）：daemon 写入的 pointer specRoot 可能是通向真实 spec 根的
+  // junction/symlink 路径——经 junction 读写与真实路径同文件（无害）但路径呈现与比对漂移、
+  // junction 随 daemon 生命周期可能蒸发。realpath 坍缩为真实路径（失败回退原值，保守不干预）。
+  try {
+    const canonical = realpathSync(ptr.specRoot)
+    if (canonical && canonical !== ptr.specRoot) return canonical
+  } catch { /* realpath 失败（权限/竞态删除）→ 原值（上方已过存在性检查） */ }
   return ptr.specRoot;
 }
 
@@ -613,6 +639,14 @@ export class ProgressManager {
     if (existsSync(walSidecar)) {
       try { copyFileSync(walSidecar, `${bakPath}-wal`); } catch { /* 侧车消失=已 checkpoint，无碍 */ }
     }
+    // 写完即回收旧快照：每次 pull / resolve --take-platform 都新增一份全库快照，无上限时
+    // 按同步次数无限累积（实证单仓 292 份 / 317MB）。裁剪放在写入侧而非独立 GC 命令——
+    // 靠人工记得跑 GC 等于没有回收。fail-open：卫生动作不能阻断 import 主流程。
+    try {
+      this._pruneImportBaks(cwd, bakPath);
+    } catch (e) {
+      console.warn(`⚠️  pre-import 快照裁剪失败（不阻断 import）: ${e.message}`);
+    }
 
     const pushedAt = progressObj.pushed_at ?? null;
     const now = new Date().toISOString();
@@ -707,6 +741,38 @@ export class ProgressManager {
     return { ok: true, imported: cn, reason: undefined, bakPath };
   }
 
+  /**
+   * 滚动裁剪 .runtime/ 下的 pre-import 快照，只留最新 N 份（含各自 -wal 侧车）。
+   *
+   * 排序依据：文件名内嵌 ISO 时间戳（冒号/点已替换为 '-'，见 import() 的 bakTs），
+   * 定宽且无进位歧义，字典序 == 时间序，无需 statSync（mtime 会被 copy/同步工具改写）。
+   *
+   * @param {string} cwd
+   * @param {string|null} keepPath - 本次刚写的快照路径，绝不裁（并发 import 互删护栏）
+   * @returns {number} 实际删除的快照份数
+   */
+  _pruneImportBaks(cwd, keepPath) {
+    let keep = Number(process.env.SILLYSPEC_PREIMPORT_BAK_KEEP);
+    if (!Number.isInteger(keep) || keep < 1) keep = PRE_IMPORT_BAK_KEEP_DEFAULT;
+
+    const runtimeDir = this._runtimePath(cwd);
+    const baks = readdirSync(runtimeDir).filter(f => PRE_IMPORT_BAK_RE.test(f)).sort();
+    const keepName = keepPath ? basename(keepPath) : null;
+    const doomed = baks.slice(0, Math.max(0, baks.length - keep)).filter(f => f !== keepName);
+
+    let removed = 0;
+    for (const f of doomed) {
+      // 单份删除失败（他进程持句柄 / 权限）不连坐其余份：跳过即可，下次 import 再收。
+      try { unlinkSync(join(runtimeDir, f)); } catch { continue; }
+      removed++;
+      const wal = join(runtimeDir, `${f}-wal`);
+      if (existsSync(wal)) {
+        try { unlinkSync(wal); } catch { /* 侧车残留无害：不参与恢复链，下次裁剪再收 */ }
+      }
+    }
+    return removed;
+  }
+
   /**
    * 本地脏度标记（D-013 / task-04）：写入路径末尾更新 changes.last_local_modified_ts。
    * 在写方法的事务内调用则属于该事务（原子，失败整体回滚）；import 是例外不调本方法
@@ -839,6 +905,13 @@ export class ProgressManager {
   // 单变更阶段查询（quick 轻量归档阶段闸）：无行 null，读失败抛（调用方 fail-closed）
   getChangeStage(cwd, changeName) { return this._changeRegistry.getChangeStage(cwd, changeName); }
 
+  // verifyStartAt 基准只读（2026-09-08-ir-verify-facts）：execute 行 completed_at；无行 null 走 R-05 fallback
+  getStageCompletedAt(cwd, changeName, stage) { return this._changeRegistry.getStageCompletedAt(cwd, changeName, stage); }
+
+  // evidence mtime 窗口锚点（2026-09-10 用户反馈②）：execute 行 started_at——证据合法产自 execute
+  // 或 verify 两窗口，锚「完成时刻」会把 execute 期间产的证据判旧（时序两难）；无行 null 走 completed_at → R-05
+  getStageStartedAt(cwd, changeName, stage) { return this._changeRegistry.getStageStartedAt(cwd, changeName, stage); }
+
   registerChange(cwd, changeName) { return this._changeRegistry.registerChange(cwd, changeName); }
 
   updateChangeIsolation(cwd, changeName, isolation) { return this._changeRegistry.updateChangeIsolation(cwd, changeName, isolation); }

package/src/quick-recommend.js

@@ -84,12 +84,17 @@ export function recommendChanges({
   taskDescription = '',
 }) {
   if (!activeChanges || activeChanges.length === 0) return []
+  // 活跃 quick 会话过滤（2026-09-09 §7-3）：quick-<hex8> 是会话不是完整流程变更——无
+  // design/proposal 语义可关联（冒烟实证：新 quick 被自动挂上另一活跃 quick 当关联变更）。
+  // 形态单源 QUICK_SID_RE（run/shared.js）；此处不 import 防把 fs 纯函数拖进 shared 依赖链。
+  const QUICK_SESSION_ID_RE = /^quick-[0-9a-f]{8}$/
+  const candidateChanges = activeChanges.filter((name) => !QUICK_SESSION_ID_RE.test(name))
 
   const dirtyFiles = [...new Set([...baselineFiles, ...quickFiles])]
     .filter(f => f && !f.startsWith('.sillyspec/'))
   const descTokens = [...new Set(tokenizeDescription(taskDescription))]
 
-  const results = activeChanges.map(name => {
+  const results = candidateChanges.map(name => {
     const reasons = []
 
     // 信号 1：脏文件命中 design.md 文件变更清单