sillyspec 3.28.2 → 3.28.4

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

@@ -19,6 +19,25 @@ export class ChangeRegistry {
     return rows.map(r => r.name);
   }
 
+  /**
+   * 读变更创建时间（IR 严格模式闸门判别源，change: 2026-09-07-ir-hardening D-001@v1）。
+   * 只读不抛（与 listChanges 同款 DB 访问）：变更不存在 / db 异常 → null——调用方
+   * （isStrictChange）按 fail-open 落存量豁免，不误伤。
+   * @param {string} cwd
+   * @param {string} changeName
+   * @returns {string|null} ISO 时间字符串或 null
+   */
+  getChangeCreatedAt(cwd, changeName) {
+    if (!changeName || typeof changeName !== 'string') return null;
+    try {
+      const db = this.pm._ensureDB(cwd);
+      const row = db.getDb().prepare('SELECT created_at FROM changes WHERE name = ?').get(changeName);
+      return row && typeof row.created_at === 'string' ? row.created_at : null;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * 查询单个变更的流程阶段与状态（quick 轻量归档阶段闸用）。
    * 与 readChangeIsolation 不同（展示读，catch → null 宽容）：本方法服务权限判定，读失败
@@ -27,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 是例外不调本方法
@@ -833,10 +891,15 @@ export class ProgressManager {
   // ── 变更管理 ──
 
   listChanges(cwd) { return this._changeRegistry.listChanges(cwd); }
+  /** 读变更创建时间（IR 严格模式闸门判别源，2026-09-07-ir-hardening D-001）——只读不抛，缺行/异常 → null */
+  getChangeCreatedAt(cwd, changeName) { return this._changeRegistry.getChangeCreatedAt(cwd, changeName); }
 
   // 单变更阶段查询（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
 }
 

package/src/run/command.js

@@ -20,10 +20,10 @@
  *     './run/stage.js' → './shared.js' 等同级
  */
 import { basename, join, resolve, dirname } from 'node:path'
-import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
+import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync, unlinkSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, countAncestorSpecDirs, ancestorSpecDirs, resolveAncestorCeiling, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, resolveQuickSessionsDir, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, ancestorSpecDirs, resolveAncestorCeiling, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, resolveQuickSessionsDir, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, isTempResidueSpecRoot, PLATFORM_MANAGED_FILENAME } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
@@ -100,11 +100,18 @@ export function looksLikeMsysMangledPath(v) {
 /**
  * MSYS 污染告警出口：命中嗅探时向 stderr 打 flag 名 + 值前缀 + 修复指引（不阻断）。
  */
-function warnMsysMangledFlag(flag, value) {
+function warnMsysMangledFlag(flag, value, { block = false } = {}) {
   if (!looksLikeMsysMangledPath(value)) return
-  console.error(`⚠️ ${flag} 的值疑似被 Git Bash(MSYS) 路径转换污染：「${value.slice(0, 60)}${value.length > 60 ? '…' : ''}」`)
-  console.error('   以 / 开头的文案在 Git Bash 下会被展开成 <Git 安装目录>/… 绝对路径后才传入 CLI。')
-  console.error('   非本意 → 去掉前导 / 或改写表述后重发本命令；确需原样 → 命令前加 MSYS_NO_PATHCONV=1。')
+  const head = `⚠️ ${flag} 的值疑似被 Git Bash(MSYS) 路径转换污染：「${value.slice(0, 60)}${value.length > 60 ? '…' : ''}」`
+  const fix = '   以 / 开头的文案在 Git Bash 下会被展开成 <Git 安装目录>/… 绝对路径后才传入 CLI。\n   非本意 → 去掉前导 / 或改写表述后重发本命令；确需原样 → 命令前加 MSYS_NO_PATHCONV=1。'
+  // 2026-09-09 ql-20260909-003（轮次经济学 §3.4）：--output/--input 携带落盘语义（标题/正文
+  // 会写进 QUICKLOG），warn 会被忽略继续落脏标题——升 exit 2 阻断；其余调用点维持 warn。
+  if (block) {
+    console.error(head + '\n' + fix + '\n   已阻断：修复后重发本命令（进度未推进，无重跑代价）。')
+    process.exit(2)
+  }
+  console.error(head)
+  console.error(fix)
 }
 
 /**
@@ -427,6 +434,15 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       // .sillyspec，无跨库状态分裂风险；非自指声明维持 fail-closed 原样（状态保护阻断）。
       if (isSelfReferentialSpecRoot(cwd, decl.specRoot)) {
         console.warn(`⚠️ 检测到陈旧的自指平台接管声明（repo-native junction 回环，原 specRoot 指回本地 .sillyspec），已降级并按本地模式运行；可 sillyspec platform disconnect 清理残留声明: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
+      } else if (isTempResidueSpecRoot(cwd, decl.specRoot)) {
+        // temp 残留降级（2026-09-08 temp 投毒治理，与入口一 resolvePlatformSpecDir 同源
+        // 判定）：声明 specRoot 在系统 temp 且 cwd 不在 temp → 可证伪的测试/联调残留。
+        // 与自指降级不同点：直接自动清理声明（自指场景 specRoot 指回本地 .sillyspec 有
+        // 真实数据面，留待 disconnect 是保守正确；temp 场景声明描述的 specRoot 物理上
+        // 就是临时产物，清理无损失，且不清理则每次命令重复 warn）。不用 disconnect——
+        // 它会连带清 local.yaml platform 段，误伤真实平台连接。删除失败仍按本地继续。
+        console.warn(`⚠️ 检测到 temp 残留平台接管声明（specRoot 指向系统 temp 目录：${decl.specRoot}，测试/联调投毒特征），已自动清理并按本地模式运行: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
+        try { unlinkSync(join(cwd, PLATFORM_MANAGED_FILENAME)) } catch { /* best effort */ }
       } else {
         console.error(`❌ 平台接管声明生效：本项目已由平台托管（原 specRoot: ${decl.specRoot || '(未记录)'}），但恢复指针缺失，拒绝静默回退本地模式。`)
         console.error(`   声明文件: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
@@ -537,7 +553,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   let outputText = null
   const outputValue = getFlagValue('--output')
   if (outputValue !== null) outputText = outputValue
-  warnMsysMangledFlag('--output', outputValue)
+  warnMsysMangledFlag('--output', outputValue, { block: true })
 
   // 解析 quick 末步四字段参数（2026-08-21 agent-手工产出审计第二批 F6）：--req/--cause/
   // --solution/--result 各传一项，CLI 合成单行四字段 outputText（quicklog 落盘侧
@@ -580,7 +596,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       break
     }
   }
-  warnMsysMangledFlag('--input', inputText)
+  warnMsysMangledFlag('--input', inputText, { block: true })
 
   // 解析 --linked-changes <a,b|none>（quick 专用：显式声明关联变更，CI/脚本友好）
   // 与 --change 解耦：--linked-changes 语义清晰（关联变更），不与「指定变更名」混淆。
@@ -1087,6 +1103,22 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         // brainstorm 自动创建变更也写 title（--input 需求描述优先 / 自动名兜底），proposal 落盘后刷新。
         progress = pm.initChange(cwd, autoName, { title: inputText ? sanitizeDesc(inputText) : autoName })
         changeName = autoName
+      } else if (stageName === 'auto') {
+        // auto 零活跃建变更（2026-09-08-auto-driver D-003@v1，Grill P1-②）：SKILL 启动命令即
+        // run auto --input——此前此处 exit 2 是断头路。复用 brainstorm 命名（date-new-change-hex）。
+        // pm.read 对零/多活跃都返 null——先分流：多活跃报错列候选（不隐式选择），零活跃才建。
+        const activeCount = pm.listChanges(cwd)
+        if (activeCount.length > 1) {
+          console.error(`❌ 已存在 ${activeCount.length} 个活跃变更，run auto 无法自动定位目标。`)
+          console.error('   活跃变更：' + activeCount.join('、'))
+          console.error('   请用 --change <变更名> 显式指定，或先归档/收尾现有变更。')
+          process.exit(2)
+        }
+        const date = new Date().toISOString().slice(0, 10)
+        const autoName = `${date}-new-change-${randomBytes(4).toString('hex')}`
+        console.log(`🔄 auto 模式自动创建变更：${autoName}（可用 --change 指定名称，或事后 change-rename）`)
+        progress = pm.initChange(cwd, autoName, { title: inputText ? sanitizeDesc(inputText) : autoName })
+        changeName = autoName
       } else {
         console.error('❌ 未找到进度数据，请先运行 sillyspec init 或指定 --change <变更名>')
         // 自愈引导（坑 suggestion-command-missing-change 同族）：多活跃变更仓不带 --change 时
@@ -1234,7 +1266,12 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     if (!qlId) {
       const guardPath = join(specBase, '.runtime', 'quick-sessions', cancelSessionRaw, 'guard.json')
       try {
-        if (existsSync(guardPath)) qlId = JSON.parse(readFileSync(guardPath, 'utf8')).qlId
+        if (existsSync(guardPath)) {
+          // 字段名 bug 修复（2026-09-09 §7-5，会话实证：guard 在场仍报「缺失/损坏」）：
+          // guard 写侧字段是 quicklogId（run/stage.js quickGuard），旧读侧读 .qlId 恒 undefined
+          const g = JSON.parse(readFileSync(guardPath, 'utf8'))
+          qlId = g.quicklogId || g.qlId
+        }
       } catch { /* guard 损坏 → 下面按找不到报错 */ }
     }
     if (!qlId) {
@@ -1546,8 +1583,15 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
   const inputText = autoFlagValue('--input')
   const skipApproval = flags.includes('--skip-approval')
   const explicitMode = autoFlagValue('--mode')
+  // --wait-interactive（2026-09-08-auto-driver D-004@v1，FR-03）：TTY 下 requiresUser 步 readline 直收
+  const waitInteractive = autoFlagValue('--wait-interactive') === 'true'
+  globalThis.__ssWaitInteractive = waitInteractive  // maybeWaitInteractive 消费（同进程直通）
   const specBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
 
+  // 单活跃自动选中为既有行为（入口 pm.read(cwd,null)）——此处仅回显（D-003@v1；
+  // 零活跃建变更已上移入口守卫层，多活跃 exit 2 由入口守卫处理）。
+  if (changeName) console.log(`🎯 auto 目标变更（单活跃自动选中或显式指定）：${changeName}`)
+
   // Helper: 在 auto 模式下获取步骤定义
   const getAutoSteps = async (stage) => {
     if (stage === 'brainstorm') {
@@ -1568,6 +1612,10 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     if (stage === 'brainstorm') {
       const existingSteps = progress.stages?.brainstorm?.steps
       const isAutoModeSteps = existingSteps?.length === 4 && existingSteps?.[0]?.name === '进度确认与上下文加载'
+      // auto 表在位即早退（2026-09-08 E2E 实证 bug：此前仅 !isAutoModeSteps 重种后 return，
+      // auto 表存在时掉进下方通用 ensureStageSteps——主模式 8 步定义判 4 步 auto 表「漂移」
+      // 重种主模式表，与 getAutoSteps 渲染双轨互踩，进度永远回 step1）
+      if (isAutoModeSteps) return progress
       if (!isAutoModeSteps) {
         if (!progress.stages) progress.stages = {}
         progress.stages.brainstorm = {
@@ -1613,6 +1661,8 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     currentStage = firstOpenStage()
   }
   if (!currentStage) {
+      // 重进入且已全完成：复用收尾总结 helper（FR-04）
+      if (changeName) printAutoCompletionSummary(pm, cwd, changeName, flowStages, specBase)
     console.log('All auto flow stages are complete.')
     return
   }
@@ -1656,7 +1706,11 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
       }
       const next = nextInFlow(currentStage)
       if (next) console.log(`${currentStage} is complete. Run: sillyspec run auto --done --output "${currentStage} complete"`)
-      else console.log('All auto flow stages are complete.')
+      else {
+        console.log('All auto flow stages are complete.')
+        // 展示路径全完成（阶段已关但用户重进）——复用收尾总结（FR-04）
+        printAutoCompletionSummary(pm, cwd, changeName, flowStages, specBase)
+      }
       return
     }
     // execute 阶段启动前检查审批
@@ -1677,7 +1731,9 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
         }
       }
     }
-    await outputStep(currentStage, pendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, currentStage))
+    await outputStep(currentStage, pendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, currentStage), { changeName })
+    // wait 直通（FR-03）：requiresUser 且 TTY 且旗标开 → readline 直收，等价 --continue --answer
+    await maybeWaitInteractive(defSteps[pendingIdx], changeName, currentStage)
     return
   }
 
@@ -1717,13 +1773,15 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
         }
       }
     }
-    await outputStep(currentStage, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, currentStage))
+    await outputStep(currentStage, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, currentStage), { changeName })
     return
   }
 
   const next = nextInFlow(currentStage)
   if (!next) {
     console.log('\nAll auto flow stages are complete.')
+    // 自然收尾点（--done 后 next==null，FR-04）：打印收尾总结
+    printAutoCompletionSummary(pm, cwd, changeName, flowStages, specBase)
     return
   }
 
@@ -1795,7 +1853,95 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
         }
       }
     }
-    await outputStep(next, firstPending, nextSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, next))
+    await outputStep(next, firstPending, nextSteps, cwd, changeName, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, next), { changeName })
   }
 }
 
+
+/**
+ * maybeWaitInteractive —— auto 模式 wait 用户输入直通（change: 2026-09-08-auto-driver，D-004@v1，FR-03）。
+ *
+ * 时序：outputStep 渲染返回后调用。条件全满足（旗标开 + requiresUser 四源 + stdin TTY）→
+ * readline 直收一行，等价自动 `--continue --answer <输入>`（复用 completeStep wait→continue 状态机，
+ * 无新状态）；任一不满足/异常 → 静默或提示回三段式（fail-open，Grill P2-①时序）。
+ * 仅 runAutoMode 的首渲染点消费（--done 推进路径不重收）。
+ */
+export async function maybeWaitInteractive(stepDef, changeName, stageName, { rlFactory = null } = {}) {
+  try {
+    if (!globalThis.__ssWaitInteractive) return
+    if (!stepDef) return
+    const { requiresUser } = await import('./prompt.js')
+    // prompt 正文在此不可得——四源三键优先（WAIT_MARKER_RE 源由 SS-META 渲染时已并入，直通用三键近似：
+    // 真需 wait 的步必有标记，纯正文标记步三段式照旧）
+    const needsUser = stepDef.requiresWait === true || stepDef.conditionalWait === true || stepDef.requiresConfirm === true
+    if (!needsUser) return
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      console.log('ℹ️  --wait-interactive 需要 TTY（当前非交互环境）——按 prompt 的 wait 指令走三段式')
+      return
+    }
+    // rlFactory 为测试缝（注入伪 readline）；生产路径用 node:readline/promises 真实 TTY
+    const rl = rlFactory
+      ? rlFactory()
+      : (await import('node:readline/promises')).createInterface({ input: process.stdin, output: process.stdout })
+    console.log('')
+    const answer = await rl.question('⌨️  本步需要你的输入（直通模式，回答后将自动 --continue --answer）：')
+    rl.close()
+    if (answer && answer.trim()) {
+      console.log(`📩 已接收，自动续行：sillyspec run auto --continue --answer "${answer.trim().slice(0, 60)}${answer.trim().length > 60 ? '…' : ''}" ...`)
+      // 复用既有 continue 路径：与 runCommand 的 --continue 同源（子进程自调避免递归锁）
+      const { execFileSync } = await import('node:child_process')
+      const binSelf = new URL('../bin/sillyspec.js', import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1')
+      try {
+        execFileSync(process.execPath, [binSelf, 'run', 'auto', '--continue', '--answer', answer.trim(), '--change', changeName], { stdio: 'inherit', cwd: process.cwd() })
+      } catch { /* continue 失败（非 waiting 态等）静默——回三段式由 agent 走 */ }
+    }
+  } catch (e) {
+    console.log(`ℹ️  wait 直通异常回退三段式：${e && e.message ? e.message : e}`)
+  }
+}
+
+
+/**
+ * printAutoCompletionSummary —— auto 流程收尾总结（change: 2026-09-08-auto-driver，D-005@v1，FR-04）。
+ * 挂点：--done 后 next==null 的自然收尾（:1726 区）+ :1616 重进入分支复用。纯 console 无新文件：
+ * 变更名/各阶段状态/tasks 勾选（readPlanCheckboxStatus）/产物存在清单/last-delta 模块清单（缺失跳过）。
+ */
+function printAutoCompletionSummary(pm, cwd, changeName, flowStages, specBase) {
+  try {
+    if (!changeName) return
+    const progress = pm.read(cwd, changeName)
+    console.log('')
+    console.log('═'.repeat(56))
+    console.log(`🏁 auto 流程收尾总结 — ${changeName}`)
+    for (const s of flowStages) {
+      const st = progress.stages?.[s]?.status || '未开始'
+      const icon = st === 'completed' ? '✅' : st === 'in-progress' ? '🔄' : '⬜'
+      console.log(`   ${icon} ${s}: ${st}`)
+    }
+    // tasks 勾选
+    try {
+      const changeDirCk = join((specBase || join(cwd, '.sillyspec')), 'changes', changeName)
+      const plan = pm.readPlanCheckboxStatus(changeDirCk)
+      if (plan && plan.total > 0) console.log(`   📋 任务勾选：${plan.checked}/${plan.total}`)
+    } catch { /* 勾选读取 fail-soft */ }
+    // 产物存在清单
+    const changeDirArt = join((specBase || join(cwd, '.sillyspec')), 'changes', changeName)
+    const artifacts = ['proposal.md', 'design.md', 'tasks.md', 'plan.md', 'verify-result.md', 'delta.md']
+    const found = artifacts.filter(a => existsSync(join(changeDirArt, a)))
+    if (found.length > 0) console.log(`   📁 产物：${found.join('、')}`)
+    // last-delta 模块清单（sidecar 缺失跳过）
+    try {
+      const runtimeRoot = join((specBase || join(cwd, '.sillyspec')), '.runtime')
+      const sidecarPath = join(runtimeRoot, 'last-delta.json')
+      if (existsSync(sidecarPath)) {
+        const sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8'))
+        if (Array.isArray(sidecar.affectedModules) && sidecar.affectedModules.length > 0) {
+          console.log(`   🔁 涉及模块（最近 delta）：${sidecar.affectedModules.join('、')}`)
+        }
+      }
+    } catch { /* sidecar 读取 fail-soft */ }
+    console.log('═'.repeat(56))
+  } catch (e) {
+    console.log(`ℹ️  收尾总结渲染降级：${e && e.message ? e.message : e}`)
+  }
+}