sillyspec 3.28.3 → 3.28.4

package/src/index.js

@@ -98,11 +98,13 @@ SillySpec CLI — 规范驱动开发工具包
                                       单 task review.json 命令式写入：verdict/notes 你给，base/head/changedFiles/diffPaths CLI 代算
   sillyspec symbol-impact --change <name>      生成 symbol-impact.md 逐 task <!--TODO--> 骨架（gate 拒绝未替换占位，防骨架直接过门）
   sillyspec design-init --change <name> [--force]  从 decisions.md 生成 design.md 十三章节骨架（决策追踪表预填；已存在不覆盖）
+  sillyspec fourpiece-init --change <name>     生成 proposal/requirements/decisions 骨架（frontmatter+章节+模板占位；已存在不覆盖）
   sillyspec delta --change <name> [--json]   生成变更 delta.md（Before/Delta/After 三段式聚合；幂等覆盖重跑即刷新）
   sillyspec next                            项目状态探测：输出当前状态 + 下一步命令 + 依据（吸收 continue/resume 手工探测表）
   sillyspec commit [--json]                 智能提交建议：收集 QUICKLOG/已勾 task/阶段产出语义，生成建议 message（只建议不执行）
   sillyspec verify-probes --change <name> [--init]  verify 机械探针（TODO 标记/测试覆盖/API 对账/删除对账）；--init 生成 verify-result.md 骨架
   sillyspec module-impact --change <name>       生成 module-impact.md 骨架（文件×模块归属按 module-map 预填 + 未匹配清单）
+  sillyspec module-docs-sync --change <name> [--note ...]  diff 归属模块 → sidecar 追加变更索引行 + 卡 updated_at 戳（幂等）
   sillyspec endpoints extract --change <name> [--task task-NN | --all-tasks] [--dir <dir>|--files <a.py,b.js>]  静态扫描路由装饰器生成 endpoints.json
   sillyspec endpoints baseline --change <name> [--spec-dir <path>] [--json]  拍变更前端点基线（幂等不覆盖；worktree 内跑自动锚主仓；归档 delta 端点增删 before 侧）
   sillyspec scan-fix-headers [--project <名>]   scan 文档补 author/created_at header（幂等）
@@ -117,6 +119,7 @@ SillySpec CLI — 规范驱动开发工具包
     （无子命令）                       跑诊断，列出问题
     --align-execute-progress [--change <名>] [--confirm]   基于 plan.md 对齐 execute 派生戳（默认 dry-run）
     --cleanup-remnant [--confirm]      删除 0 字节空占位 db（默认 dry-run，仅 --confirm 落盘）
+    --gc-unstamped-runs [--confirm]    回收已归档变更留下的无 change 戳 execute-runs（默认 dry-run）
     --dump-db --path <db 路径>         dump 指定 db 内容到文件（取证用）
     --json                             结构化诊断 + 落盘 .sillyspec/.runtime/doctor-diagnosis.json
   sillyspec modules <rebuild | status | migrate>
@@ -942,8 +945,51 @@ async function main() {
           writeFileSync(vpReportPath, generateVerifyResultSkeleton(vpResult));
           console.log(`\n📄 已生成 verify-result.md 骨架: ${vpReportPath}（探针已预填；结论必须写明 PASS/FAIL，留待填会被 gate 判不过）`);
         }
-        writeVerifyFacts(join(vpSpecBase, 'changes', vpChange), vpResult, vpChange); // P3b：facts 底稿随 --init 刷新（骨架已存在也刷新，最近快照语义）
+        writeVerifyFacts(join(vpSpecBase, 'changes', vpChange), vpResult, vpChange); // P3b：facts 底稿随 --init 刷新（骨架已存在也刷新；v2 起分段合并保留固化段）
+        // 2026-09-08-ir-verify-facts R-02：已存在 md 缺证据账/回执槽段时仅追加骨架（幂等二跑
+        // 零改动）；task 行按 verify-required-evidence.json 预填（存在时）。
+        if (existsSync(vpReportPath)) {
+          let vpReqItems = []
+          try {
+            const vpReqPath = join(vpSpecBase, 'changes', vpChange, 'verify-required-evidence.json')
+            if (existsSync(vpReqPath)) {
+              const vpReq = JSON.parse(readFileSync(vpReqPath, 'utf8'))
+              vpReqItems = Array.isArray(vpReq.items) ? vpReq.items.map(it => ({ task: it.task, evidence: it.evidence || [] })) : []
+            }
+          } catch { /* 读取失败 → 空预填，不阻断 */ }
+          const { backfillMissingEvidenceSlots } = await import('./verify-probes.js')
+          const vpAdded = backfillMissingEvidenceSlots(vpReportPath, vpReqItems)
+          if (vpAdded.added.length > 0) {
+            console.log(`📄 已补齐缺失槽段（不触碰既有正文）: ${vpAdded.added.join('、')}`)
+          }
+        }
+      }
+      break;
+    }
+    case 'module-docs-sync': {
+      // 模块文档 sidecar 同步命令化（2026-09-09 刀批）：diff 归属模块 → sidecar 追加变更索引行 +
+      // 卡 updated_at 戳——机械部分 CLI 代算，卡片正文语义更新仍归 agent/归档流程。幂等。
+      const mdsChangeIdx = args.indexOf('--change');
+      const mdsChange = mdsChangeIdx >= 0 && args[mdsChangeIdx + 1] ? args[mdsChangeIdx + 1] : null;
+      const mdsNoteIdx = args.indexOf('--note');
+      const mdsNote = mdsNoteIdx >= 0 && args[mdsNoteIdx + 1] ? args[mdsNoteIdx + 1] : null;
+      if (!mdsChange) {
+        console.error('用法: sillyspec module-docs-sync --change <name> [--note "一句话"] [--json]\n  diff 归属模块 → sidecar 追加变更索引行 + 卡 updated_at 戳（幂等；卡片正文语义更新仍归 agent）');
+        process.exit(2);
+      }
+      const { syncModuleDocSidecars } = await import('./module-impact.js');
+      const mdsResult = syncModuleDocSidecars({ cwd: dir, changeName: mdsChange, note: mdsNote, specDir });
+      if (json) {
+        console.log(JSON.stringify({ command: 'module-docs-sync', change: mdsChange, ...mdsResult }, null, 2));
+        break;
+      }
+      if (mdsResult.reason) console.log(mdsResult.reason);
+      if (mdsResult.synced.length > 0) {
+        console.log(String.fromCharCode(9989) + ' sidecar 已同步 ' + mdsResult.synced.length + ' 个模块: ' + mdsResult.synced.join(', '));
+        console.log('   卡 updated_at 已戳；卡片正文语义更新（如需要）仍归归档流程/agent。');
       }
+      if (mdsResult.skipped.length > 0) console.log(String.fromCharCode(8505) + ' 已含本变更行跳过: ' + mdsResult.skipped.join(', '));
+      if (mdsResult.unmatched.length > 0) console.log(String.fromCharCode(9888) + ' 未匹配模块的文件 ' + mdsResult.unmatched.length + ' 个（不入 sidecar）: ' + mdsResult.unmatched.slice(0, 5).join(', '));
       break;
     }
     case 'plan-adopt-waves': {
@@ -1313,6 +1359,94 @@ async function main() {
       console.log('   逐行替换 <!--TODO--> 为结论（无签名级变更也显式写「无」）；gate 拒绝未替换的占位行。');
       break;
     }
+    case 'fourpiece-init': {
+      // 四件套骨架预生成（2026-09-09 ql-20260909-003，轮次经济学 §3.2）：brainstorm 期 agent
+      // 手写 proposal/requirements/decisions 的 frontmatter/章节骨架是格式返工根源——本命令
+      // 逐文件生成骨架（已存在不覆盖），agent 只填语义。与 design-init 同族（幂等）。
+      const fpChangeIdx = args.indexOf('--change');
+      const fpChange = fpChangeIdx >= 0 && args[fpChangeIdx + 1] ? args[fpChangeIdx + 1] : null;
+      if (!fpChange) {
+        console.error('用法: sillyspec fourpiece-init --change <name> [--json] [--spec-dir <path>]\n  生成 proposal.md/requirements.md/decisions.md 骨架（frontmatter+章节标题+模板占位；已存在不覆盖；design.md 归 design-init）');
+        process.exit(2);
+      }
+      const fpSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const fpDir = join(fpSpecBase, 'changes', fpChange);
+      mkdirSync(fpDir, { recursive: true });
+      const fpNow = new Date();
+      const fpDate = fpNow.toISOString().slice(0, 10);
+      const fpStamp = fpNow.toISOString().slice(0, 19).replace('T', ' ');
+      const generated = [];
+      const mk = (fname, body) => {
+        const p = join(fpDir, fname);
+        if (existsSync(p)) { console.log(`ℹ️  ${fname} 已存在，不覆盖`); return; }
+        writeFileSync(p, body);
+        generated.push(fname);
+        console.log(`✅ 已生成 ${fname} 骨架: ${p}`);
+      };
+      mk('proposal.md', `---
+author: qinyi
+created_at: ${fpStamp}
+---
+# 提案书（Proposal）
+
+## 动机
+<!--TODO: 为什么做、解决什么核心问题-->
+
+## 关键问题
+<!--TODO: 为什么现有方案不够（2-3 个痛点）-->
+
+## 变更范围
+<!--TODO: 本次做什么-->
+
+## 不在范围内（显式清单）
+- <!--TODO: 不做 X-->
+
+## 成功标准（可验证）
+- <!--TODO: 可验证条目-->
+`);
+      mk('requirements.md', `---
+author: qinyi
+created_at: ${fpStamp}
+---
+# 需求规格（Requirements）
+
+## 角色
+| 角色 | 说明 |
+|---|---|
+| <!--TODO--> | <!--TODO--> |
+
+## 功能需求
+
+### FR-01: <!--TODO-->
+Given <!--TODO-->
+When <!--TODO-->
+Then <!--TODO-->
+
+## 非功能需求
+- 兼容性：<!--TODO-->
+
+## 决策覆盖矩阵（如存在 decisions.md）
+| 决策 ID | 覆盖的 FR | 说明 |
+|---|---|---|
+`);
+      mk('decisions.md', `---
+author: qinyi
+created_at: ${fpStamp}
+change: ${fpChange}
+---
+
+# 决策记录（Decisions）
+
+<!-- 增量落盘：每解决一个有实现影响的问题当场追加一条（格式见 brainstorm Step 3 模板）；幂等按 D-xxx@vN 判重 -->
+`);
+      if (json) {
+        console.log(JSON.stringify({ command: 'fourpiece-init', change: fpChange, generated }, null, 2));
+      } else if (generated.length > 0) {
+        console.log(`
+${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语义内容（骨架勿手删章节）；design.md 用 sillyspec design-init。`);
+      }
+      break;
+    }
     case 'design-init': {
       // design.md 十三章节骨架生成（change: 2026-09-07-ir-stage-p3c，task-02，FR-03）：agent 此前
       // 从零手写整份设计文档，章节漏项到 stage-contract/plan 门禁才暴露。本命令从 decisions.md
@@ -1810,9 +1944,10 @@ async function main() {
     // slice(1) 去掉的是 'run' 字面量，这里 command 本身就是 stage 名不能丢。
     case 'doctor': {
       const doctorEffectiveDir = specDir ? dir : resolveEffectiveDir(dir);
-      // 执行流：--cleanup-remnant / --cleanup-ghosts / --dump-db（结构化诊断之外的修复/取证动作）
+      // 执行流：--cleanup-remnant / --cleanup-ghosts / --gc-unstamped-runs / --dump-db（结构化诊断之外的修复/取证动作）
       const cleanupRemnant = filteredArgs.includes('--cleanup-remnant');
       const cleanupGhosts = filteredArgs.includes('--cleanup-ghosts');
+      const gcUnstampedRuns = filteredArgs.includes('--gc-unstamped-runs');
       const dumpDbFlag = filteredArgs.includes('--dump-db');
       const doctorConfirm = filteredArgs.includes('--confirm');
       const pathIdx = filteredArgs.indexOf('--path');
@@ -1918,6 +2053,29 @@ async function main() {
         process.exitCode = r.errors.length > 0 ? 1 : 0;
         break;
       }
+      if (gcUnstampedRuns) {
+        // ql-20260908-006-5f04：无戳 execute-runs 一次性清扫。默认 dry-run，--confirm 才删。
+        // 不进 archive 热路径（pruneArchivedChangeRuntime 故意不猜无戳 run）。
+        const { gcUnstampedExecuteRuns } = await import('./doctor-diagnostics.js');
+        const r = await gcUnstampedExecuteRuns({ cwd: doctorEffectiveDir, specDir, confirm: doctorConfirm });
+        if (json) {
+          console.log(JSON.stringify(r, null, 2));
+        } else {
+          const verb = doctorConfirm ? '已删除' : '待删除（dry-run）';
+          console.log(`🧹 无戳 execute-runs（仅已归档变更、交叉核验通过）${verb}：${r.count} 个  [runtime: ${r.runtime_root || '(无)'}]`);
+          for (const c of r.candidates || []) {
+            console.log(`   ${doctorConfirm ? '✅' : '-'} ${c.runId} ← ${c.owner}（via ${c.via}）`);
+          }
+          for (const s of r.skipped || []) console.log(`   ⏭️  ${s.runId}（${s.reason}）`);
+          for (const e of r.errors || []) console.log(`   ❌ ${e.runId || ''}: ${e.error}`);
+          if (!doctorConfirm && r.count > 0) {
+            console.log(`\n加 --confirm 执行删除（只删上面列出的无戳 run，有 change 戳 / 命中活跃变更 / 归属不明一律不动）。`);
+          }
+          if (r.reason) console.log(`ℹ️ ${r.reason}`);
+        }
+        process.exitCode = (r.errors && r.errors.length > 0) ? 1 : 0;
+        break;
+      }
       if (dumpDbFlag) {
         if (!dbPath) { console.error('❌ --dump-db 需要 --path <db 路径>'); process.exitCode = 2; break; }
         const { dumpDb } = await import('./doctor-diagnostics.js');
@@ -1944,9 +2102,21 @@ async function main() {
         process.exitCode = output.overall_status === 'pass' ? 0 : 1;
         break;
       }
-      // 否则：保持原有 prompt 驱动的 bash 自检流程
-      const { runCommand } = await import('./run.js');
-      await runCommand([command, ...filteredArgs.slice(1)], doctorEffectiveDir, specDir, { json });
+      // 2026-09-09-doctor-noai：--status 拦截（审查 B-03：等价只读渲染——阶段进度视图，
+      // 零副作用）；非 --json 其余形态改道直跑诊断 + renderDoctorSummary（不走
+      // runCommand/initChange/不刷 lastActive——只读零副作用承诺保真）。
+      if (filteredArgs.includes('--status')) {
+        // 等价只读渲染：复用 progress show（cwd 无活跃变更时提示无——与原只读短路视图同语义级）
+        const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
+        pm.show(doctorEffectiveDir);
+        break;
+      }
+      {
+        const { runDoctorDiagnostics, renderDoctorSummary, writeDoctorDiagnosis } = await import('./doctor-diagnostics.js')
+        const diag = await runDoctorDiagnostics({ cwd: doctorEffectiveDir })
+        console.log(renderDoctorSummary(diag))
+        try { writeDoctorDiagnosis(diag, resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec')) } catch { /* fail-soft */ }
+      }
       break;
     }
     case 'scan': {
@@ -2920,7 +3090,12 @@ checkbox 行；depends_on 自动反填行内注解 "(depends_on: task-01,02)"；
 
       const { cmdTaskcard } = await import('./taskcard.js');
       try {
-        const result = cmdTaskcard(tcName, { cwd: dir, specDir, taskIds, title: titleVal, titleZh: titleZhVal, force, sets });
+        // 坑 platform-sync-progress-rollback-and-db-corruption 坑4：taskcard 此前只走
+        // resolveSpecDir（祖先遍历本地 .sillyspec），不感知平台接管指针——平台模式下
+        // 仓库根裸跑报「变更目录不存在」，需显式 --spec-dir（与 run/plan 系列不一致）。
+        // 对齐 endpoints 等命令：先 resolvePlatformSpecDir（指针 fail-closed 语义同源）。
+        const tcPlatformSpecDir = resolvePlatformSpecDir(dir, specDir) || specDir;
+        const result = cmdTaskcard(tcName, { cwd: dir, specDir: tcPlatformSpecDir, taskIds, title: titleVal, titleZh: titleZhVal, force, sets });
         for (const f of result.created) console.log(`✅ 已生成: ${f}`);
         for (const f of result.skipped) console.log(`⏭️  已存在，跳过（--force 覆盖）: ${f}`);
         if (result.created.length > 0) {

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,20 @@ 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) {
+    sourceFileList = sourceFiles.map(f => f.split('\\').join('/')).filter(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 +174,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 +227,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/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,22 @@ 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; }
+  }
+
   getChangeStage(cwd, changeName) {
     const db = this.pm._ensureDB(cwd);
     const sqlDb = db.getDb();

package/src/progress.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,
@@ -613,6 +631,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 +733,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 +897,9 @@ 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); }
+
   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 文件变更清单

package/src/quicklog.js

@@ -294,9 +294,17 @@ export function extractTitleFromResult(result) {
   if (!result) return ''
   const m = String(result).match(/需求：([^\n\r]*?)(?:\s+根因：|$)/)
   if (!m) return ''
-  let t = m[1].replace(/[，。；,;].*$/, '').trim() // 截到首个标点，取核心句
+  // 不再截到首个标点（2026-09-08 用户反馈②）：旧口径迫使 agent 刻意避开标点写标题，
+  // 「A，B」被截成「A」反而降低可读性。--req 的模板指引本就要求一句话短标题，
+  // 标点由写者自主掌控；CLI 只兜底超长截断。
+  let t = m[1].trim()
   if (!t) return ''
-  if (t.length > 80) t = t.slice(0, 80) + '…'
+  if (t.length > 80) {
+    // 超长截断优先在标点/空格处断（标题残句可读），找不到就近边界才硬截。
+    const cut = t.slice(0, 80)
+    const m2 = cut.match(/^[\s\S]*[，。；：,;:]\s*/)
+    t = (m2 && m2[0].length >= 40 ? m2[0] : cut).replace(/[，。；：,;:\s]+$/, '') + '…'
+  }
   return t
 }