sillyspec 3.28.0 → 3.28.3

package/src/run/command.js

@@ -23,7 +23,7 @@ import { basename, join, resolve, dirname } from 'node:path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } 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, 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, 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'
@@ -107,6 +107,38 @@ function warnMsysMangledFlag(flag, value) {
   console.error('   非本意 → 去掉前导 / 或改写表述后重发本命令；确需原样 → 命令前加 MSYS_NO_PATHCONV=1。')
 }
 
+/**
+ * done-like 步骤动作（--done/--skip/--wait/--continue/--reset/--reopen）的目标 change 在当前
+ * 库是否已「物化」（坑 done-phantom-change-silent-create，2026-09-04 事故元凶①）。
+ *
+ * 背景：接管指针切换/重建进度库后，--change 常指向旧库的变更名；新库里既无 DB 行也无
+ * changes/<name>/ 目录，runCommand 的 !progress 分支却无条件 initChange 静默新建——幻影
+ * 变更零进度起步，--done 被记到幻影上，原变更进度停滞（本次事故直接元凶）。
+ *
+ * 物化口径（progress 已知为 null，只查磁盘标记）：
+ *   - 普通变更：changes/<name>/ 存在（archive 已归档目录也算——归档后 DB 行仍可读，
+ *     但行被清理的恢复场景认 archive 目录物化，走 initChange 自愈是合法路径）；
+ *   - quick-<8hex> 会话：无 changes/ 目录，物化标记 = 会话 guard（per-session 目录或
+ *     legacy 单文件——legacy 无法归属会话，保守认物化，宁可漏拦不误杀真会话）。
+ *
+ * 纯函数：只读磁盘，供 command.js 守卫 + 单测复用。
+ * @param {object} opts
+ * @param {string|null} opts.target - 目标 change 名（--change 值或 changes/ 目录唯一推导）
+ * @param {string} opts.specBase - 当前进度库根（平台 specRoot 或 cwd/.sillyspec）
+ * @param {string|null} [opts.quickSessionsDir] - quick 会话 guard 目录（缺省按 specBase/.runtime 推导）
+ * @returns {boolean} true = 目标已物化（可走既有 initChange 自愈），false = 幻影（应拒绝新建）
+ */
+export function doneLikeTargetMaterialized({ target, specBase, quickSessionsDir = null }) {
+  if (!target || !specBase) return false
+  if (/^quick-[0-9a-f]{8}$/.test(target)) {
+    const rt = quickSessionsDir || join(specBase, '.runtime', 'quick-sessions')
+    return existsSync(join(rt, target, 'guard.json'))
+      || existsSync(join(specBase, '.runtime', 'quick-guard.json'))
+  }
+  return existsSync(join(specBase, 'changes', target))
+    || existsSync(join(specBase, 'changes', 'archive', target))
+}
+
 /**
  * 从 progress 或变更目录推导变更名
  */
@@ -951,6 +983,43 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   }
 
   if (!progress) {
+    // ── done-like 存在性守卫（坑 done-phantom-change-silent-create，2026-09-04 事故元凶①）──
+    // --done/--skip/--wait/--continue/--reset/--reopen 都预设「目标 change 已存在于当前进度库」。
+    // 此前 !progress 时无条件 initChange 静默新建——接管指针切库/换库后 --change 指向旧库的
+    // 变更名，新库里凭空建幻影变更再把动作记上去。目标已物化（changes/ 目录或 quick 会话
+    // guard 存在）仍放行走下方 initChange 自愈（DB 重建/迁移后从目录物化是合法恢复路径）。
+    if (isDone || isSkip || isWait || isContinue || isReset || isReopen) {
+      const actionFlag = isDone ? '--done' : isSkip ? '--skip' : isWait ? '--wait'
+        : isContinue ? '--continue' : isReset ? '--reset' : '--reopen'
+      const guardTarget = changeName || resolveChangeNameAuto(cwd, specRoot)
+      if (!doneLikeTargetMaterialized({
+        target: guardTarget,
+        specBase,
+        quickSessionsDir: resolveQuickSessionsDir(platformOpts, specBase),
+      })) {
+        const pointerPath = join(cwd, '.sillyspec-platform.json')
+        const pointerMode = existsSync(pointerPath)
+        let activeList = []
+        try { activeList = pm.listChanges(cwd) } catch { /* 列举失败不掩盖主报错 */ }
+        console.error(`❌ ${actionFlag} 找不到目标变更的进度，拒绝静默新建（防幻影变更）。`)
+        console.error(`   目标变更: ${guardTarget || '(未指定 --change，且当前库无唯一活跃变更)'}`)
+        console.error(`   当前进度库: ${specBase}${pointerMode ? `（平台接管指针 ${pointerPath} 指向此库）` : '（本地模式）'}`)
+        console.error(`   本库活跃变更: ${activeList.length > 0 ? activeList.join('、') : '(无)'}`)
+        console.error('   排查：')
+        console.error(`   ① 变更名是否打错——从上面活跃列表选，或 sillyspec progress show 查看各变更进度`)
+        if (pointerMode) {
+          console.error(`   ② 最近是否切换/重建过平台接管指针（重跑平台 scan 会换库）——原变更可能留在旧库：检查 ${pointerPath} 的 specRoot，或用 --spec-dir 显式指回旧库`)
+        } else {
+          console.error(`   ② cwd 是否漂移/切库——用 --spec-dir <路径>/.sillyspec 显式指定正确的进度库`)
+        }
+        if (stageName === 'quick' || /^quick-[0-9a-f]{8}$/.test(guardTarget || '')) {
+          console.error(`   ③ quick 会话跨进程恢复须带 --change <quick-session-id>；本库无该会话 guard——会话可能属于旧库`)
+        } else {
+          console.error(`   ③ 确要新建变更：先 sillyspec run brainstorm --change <名>（不带 ${actionFlag}）`)
+        }
+        process.exit(2) // 用法/环境错（目标变更不在当前库）→ exit 2
+      }
+    }
     // 如果指定了变更名或有变更目录，自动初始化变更的 progress
     const autoChange = changeName || resolveChangeNameAuto(cwd, specRoot)
     if (autoChange) {
@@ -1018,6 +1087,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 时
@@ -1477,8 +1562,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') {
@@ -1499,6 +1591,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 = {
@@ -1544,6 +1640,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
   }
@@ -1587,7 +1685,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 阶段启动前检查审批
@@ -1608,7 +1710,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
   }
 
@@ -1648,13 +1752,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
   }
 
@@ -1726,7 +1832,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}`)
+  }
+}

package/src/run/complete-handlers.js

@@ -31,7 +31,7 @@ import { detectConcurrentChanges, formatConcurrentWarning, resolveConcurrentAnch
 import { stageRegistry } from '../stages/index.js'
 import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
 import { printQuickAuditReview, runQuickTestLintGate, printQuickTestLintGate } from './quick-audit.js'
-import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult } from '../quicklog.js'
+import { validateQuickResult, allocateQuicklogEntry, appendQuicklogEntryWithId, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
 import { archiveDestDirName } from '../stage-contract.js'
 
@@ -432,6 +432,34 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
     console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
     return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
   }
+  // ── 归档前 delta.md 自动生成（P3d task-02，fail-soft 零阻断）──
+  // 目录移走前在 changes/<name>/ 落一份 Before/Delta/After 三段式快照（四源采集容缺，
+  // buildDeltaReport 见 ../archive-delta.js），随归档包留存。失败只 console.error 留痕、
+  // 提示 sillyspec delta --change 手动补，绝不抛出——归档主流程既有失败面（rename/git/清理）
+  // 一个不叠加。specRoot 同 complete.js :87 口径（specBase 已含 platform specRoot）；
+  // runtimeRoot 同本文件 archiveWorktreeCleanup 既有用法 resolveRuntimeRoot(platformOpts, specBase)。
+  const deltaChangeName = progress.currentChange || changeName
+  if (deltaChangeName) {
+    try {
+      const { buildDeltaReport, writeLastDeltaSidecar } = await import('../archive-delta.js')
+      const deltaChangeDir = join(specBase, 'changes', deltaChangeName)
+      const deltaResult = buildDeltaReport({
+        changeDir: deltaChangeDir,
+        specRoot: specBase,
+        // project 缺参可 null（loadModuleMap null 降级路径已支持，报告内逐段降级注记）
+        project: progress?.project || null,
+        runtimeRoot: resolveRuntimeRoot(platformOpts, specBase),
+        // IR 回灌 sidecar（2026-09-07-ir-hardening D-006）：与手动补跑同源数据
+        withSummary: true,
+      })
+      writeFileSync(join(deltaChangeDir, 'delta.md'), deltaResult.markdown)
+      writeLastDeltaSidecar(resolveRuntimeRoot(platformOpts, specBase), deltaResult)
+      console.log(`📊 归档前已生成 delta.md: ${join(deltaChangeDir, 'delta.md')}`)
+    } catch (e) {
+      console.error(`⚠️  归档前 delta.md 自动生成失败（不阻断归档）: ${e.message}`)
+      console.error(`   可手动补: sillyspec delta --change ${deltaChangeName} --spec-dir ${specBase}`)
+    }
+  }
   // 主仓互斥锁（坑 main-repo-no-mutex 二批）：archiveChangeDirectory 改主仓共享状态（目录
   // rename + 共享 index 的 git add + marker 删除 + worktree 清理），与并行会话的 apply/cleanup
   // 互踩。exit 钩子兜底：其内部 guard 失败 exit(1) 时锁也会被清（见 withMainRepoLock）。
@@ -907,10 +935,14 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
       // P0-2（2026-09-02 跨 agent 工单）：触及 src/test 的 quick --done 内置 test+lint
       // 实测门禁——把 CLAUDE.md 规则 8 从 agent 自律下沉为 CLI 卡点（fail → step 回
       // pending + exit 1，重跑不丢进度；纯 doc/配置与未配置命令自动跳过不阻断）。
+      // declaredFiles 兜底（2026-09-07）：倒推 B 模式（代码先行 --done 收尾）的文件全部
+      // 早于会话启动被基线吸收 → 审计 changedFiles 空 → 此前静默 skip；声明边界触及
+      // src/test 时实测仍应跑（quick-f9138c2f 实证）。
       const gate = await runQuickTestLintGate({
         cwd,
         specBase,
         changedFiles: review.changedFiles,
+        declaredFiles: Array.isArray(mergedGuard?.allowedFiles) ? mergedGuard.allowedFiles : [],
         changeName,
       })
       printQuickTestLintGate(gate)
@@ -988,7 +1020,27 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
     }
 
     if (!qlId) {
-      // 无 ql-ID（guard 缺失或 brownfield 无 quicklogId）：补分配后立即完成，不阻断。
+      // 坑 platform-takeover-phantom-progress-db 同日变体：guard 缺失时兜底**优先复用启动
+      // 分配的 ql-ID**（进度库 changes.quicklog_id，quick 启动时 stage.js 回填）——落码
+      // 注释/模块文档的 ql-ID 是启动时就给出的，补分配新号必然制造引用劈叉（同一次会话
+      // 两个 ID、两份 QUICKLOG 各半）。ID 的条目不在当前 specBase（启动/完成分裂库形态）
+      // → 用原 ID 补建骨架，完成态落在同一 ID 上。库中也无（真 brownfield/极老会话）才
+      // 补分配。
+      try {
+        const dbQlId = pm.getQuicklogId(cwd, changeName)
+        if (dbQlId) {
+          const re = await appendQuicklogEntryWithId(specBase, gitUser, dbQlId, {
+            description: guard?.taskDescription || '(guard 缺失补建)',
+            linkedChanges,
+            allowedFiles: Array.isArray(guard?.allowedFiles) ? guard.allowedFiles : [],
+          })
+          qlId = dbQlId
+          console.log(`📝 QUICKLOG 兜底补写复用启动 ql-ID: ${qlId}（guard 缺失，ID 取自进度库 quicklog_id${re.existed ? '' : '，条目已补建'}）`)
+        }
+      } catch { /* 读取/补建失败退回补分配，不阻断 */ }
+    }
+    if (!qlId) {
+      // 无 ql-ID（库中也未回填，真 brownfield）：补分配后立即完成，不阻断。
       try {
         const alloc = await allocateQuicklogEntry(specBase, gitUser, {
           description: guard?.taskDescription || '(补分配)',
@@ -1530,7 +1582,9 @@ export async function handleScanStageCompleted({ stageName, currentIdx, cwd, pro
       try { unlinkSync(platformOptsFile) } catch {}
 
       // CLI 层 post-check（替代旧的简单检查）
-      const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult } = await import('../scan-postcheck.js')
+      const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult, stampScanDocHeaders } = await import('../scan-postcheck.js')
+      // ② frontmatter CLI 盖章（2026-09-05，幂等兜底——正常已在 scanFinalize / quick postcheck 盖过）
+      stampScanDocHeaders({ cwd, specDir: platformOpts.specRoot, mode: stageData.scanProfile?.mode })
       const postResult = runScanPostCheck({
         cwd,
         specDir: platformOpts.specRoot,
@@ -1613,7 +1667,9 @@ export async function handleScanStageCompleted({ stageName, currentIdx, cwd, pro
 
   // 非 platform 模式 scan 也做轻量 post-check + 结构化输出
   if (stageName === 'scan' && !platformOpts.specRoot && !platformOpts.runtimeRoot) {
-    const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult } = await import('../scan-postcheck.js')
+    const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult, stampScanDocHeaders } = await import('../scan-postcheck.js')
+    // ② frontmatter CLI 盖章（2026-09-05，幂等兜底）
+    stampScanDocHeaders({ cwd, specDir: null, mode: stageData.scanProfile?.mode })
     const postResult = runScanPostCheck({ cwd, specDir: null, outputText, scanProfile: stageData.scanProfile || null })
     printScanPostCheckResult(postResult)
     // 结构化结果写入 .sillyspec/.runtime/

package/src/run/complete.js

@@ -21,12 +21,31 @@ import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync } fr
 import { writeAtomicSync } from '../fs-atomic.js'
 import { withFileLock } from '../quicklog.js'
 import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir } from './shared.js'
-import { executeScanPreflight, executeScanPostcheck, computeScanProfile } from './scan-profile.js'
+
+// auto 模式 brainstorm 步骤表感知解析（2026-09-08 E2E 实证 bug：--done/--wait 推进主模式 8 步表，
+// 与 runAutoMode getAutoSteps 的 4 步 auto 表双轨互踩——ensureAutoStage 判非 auto 表重种清零，
+// 进度永远回 step1）。DB 现存 brainstorm 表为 auto 形态（4 步+首名「进度确认与上下文加载」）时，
+// complete 路径与渲染路径同源用 brainstormAutoDef.steps。
+async function getStageStepsAutoAware(stageName, cwd, progress, specDir) {
+  const steps = await getStageSteps(stageName, cwd, progress, specDir)
+  if (stageName !== 'brainstorm') return steps
+  const existing = progress?.stages?.brainstorm?.steps
+  const isAutoTable = Array.isArray(existing) && existing.length === 4
+    && existing[0]?.name === '进度确认与上下文加载'
+  if (!isAutoTable) return steps
+  const { definition: brainstormAutoDef } = await import('../stages/brainstorm-auto.js')
+  return brainstormAutoDef.steps
+}
+
+import { executeScanPreflight, executeScanPostcheck, computeScanProfile, executeScanDetectProjects, executeScanResumeCheck, executeScanFinalize } from './scan-profile.js'
+import { executeProgressConfirm } from './progress-confirm.js'
+import { AUXILIARY_STAGES } from '../constants.js'
 import { executePlanPostcheck as runPlanPostcheckLib } from '../stages/plan-postcheck.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { enforceDepsGate, enforceReviewJsonGate, enforceSymbolImpactGate, warnMissingUiPrototype, completeStageGates, readDesignScale } from './gates.js'
 import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact } from './complete-handlers.js'
 import { formatExecuteSummary } from '../worktree-apply.js'
+import { validateDecisionModuleRefs } from '../design-facts.js'
 import { isEndToEndTaskText } from '../change-risk-profile.js'
 import { deriveTitleFromLinkedChange } from '../quicklog.js'
 import { gitQuiet } from '../git-helper.js'
@@ -219,7 +238,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   }
 
   // ── requiresWait 硬门控 ──
-  const defStepsForCurrent = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const defStepsForCurrent = await getStageStepsAutoAware(stageName, cwd, progress, platformOpts?.specRoot || null)
   // def↔DB 一致性守卫（坑 execute-step-table-drift，2026-08-20 实证）：runCommand 入口已按名
   // 重播种（ensureStageSteps），但同一命令进程内 plan.md 若再次被改（或绕过 runCommand 直调
   // completeStep 的路径），def 与 DB 步数错位会让 currentIdx 的门控/prompt 施加到错误的步骤上
@@ -279,6 +298,60 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   await enforceSymbolImpactGate(stageName, changeName, steps[currentIdx]?.name, specBase)
   // UI 原型软提醒（非阻断）：brainstorm 收尾步 design.md 命中前端文件但无 prototype → 提示用户可否决
   warnMissingUiPrototype(stageName, changeName, steps[currentIdx]?.name, specBase)
+  // 决策模块域核验硬门（task-02 接线 design-facts，FR-02/D-002）：brainstorm「生成规范文件」步
+  // --done 时核验 decisions.md 模块域引用。ERROR（decision_module_ref_invalid，消息已内嵌前缀）
+  // = 模块幻觉/书写错误 → fail-closed exit 1（进度不推进，步骤保持 pending）；WARNING
+  // （decision_module_domain_gap 声明×实改差异）→ warn 放行留人工裁量；skipped（无决策文件/
+  // 无 _module-map.yaml 索引）→ 单行 info 放行（无索引不误拦）。fail-soft：核验自身异常 →
+  // fail-open（warn 留痕后放行——门禁代码缺陷不应误拦真实完成，与「无索引跳过」同向）。
+  // project 解析与 handleWorkflowPostCheck 同链：progress.project（平台模式真实项目名）>
+  // steps[idx].project > null（brainstorm 非 perProject 展开，后两位常规为空）。
+  if (stageName === 'brainstorm' && steps[currentIdx]?.name?.includes('生成规范文件') && changeName) {
+    try {
+      const _dmProject = progress?.project || steps[currentIdx]?.project || null
+      const _dmResult = validateDecisionModuleRefs({
+        changeDir: join(specBase, 'changes', changeName),
+        specRoot: specBase,
+        project: _dmProject,
+      })
+      if ((_dmResult.errors || []).length > 0) {
+        console.error(`❌ ── 决策模块域核验阻断（本次 --done 未完成，进度未推进）──`)
+        for (const _dmErr of _dmResult.errors) console.error(`   • ${_dmErr}`)
+        console.error(`   修复：更正 decisions.md 对应条目的「模块域」字段（模块 ID 取自 docs/${_dmProject || '<项目>'}/modules/_module-map.yaml），或以 NEW:<名> 前缀声明新模块后重跑：`)
+        console.error(`   sillyspec run brainstorm --done${changeName ? ` --change ${changeName}` : ''} --output "修复说明"`)
+        process.exit(1)
+      }
+      for (const _dmWarn of (_dmResult.warnings || [])) console.warn(`   ⚠️ ${_dmWarn}`)
+      if (_dmResult.skipped) {
+        console.log(`ℹ️  [decision_module_check_skipped] ${_dmResult.skipped}`)
+      }
+    } catch (_dmEx) {
+      console.warn(`   ⚠️ 决策模块域核验自身异常，fail-open 放行（不误拦本次完成）：${_dmEx && _dmEx.message ? _dmEx.message : _dmEx}`)
+    }
+  }
+
+  // ── design.md 文件清单行级核验（2026-09-07-ir-hardening D-004@v1，FR-02）──
+  // 幻觉路径 ERROR（design_file_ref_invalid，与 plan 侧 validateTargetFiles 同语义先例）；
+  // NEW: 前缀豁免 / glob 跳过 / 清单缺失 WARNING。挂点与决策模块域核验同点位（brainstorm 末步）。
+  if (stageName === 'brainstorm' && steps[currentIdx]?.name?.includes('生成规范文件') && changeName) {
+    try {
+      const { validateDesignFileList } = await import('../design-facts.js')
+      const _dflResult = validateDesignFileList({
+        changeDir: join(specBase, 'changes', changeName),
+        cwd,
+      })
+      if ((_dflResult.errors || []).length > 0) {
+        console.error(`❌ ── design 文件清单核验阻断（本次 --done 未完成，进度未推进）──`)
+        for (const _dflErr of _dflResult.errors) console.error(`   • ${_dflErr.message}`)
+        console.error(`   修复：更正 design.md「文件变更清单」对应行路径，或计划新建文件加 NEW: 前缀后重跑：`)
+        console.error(`   sillyspec run brainstorm --done${changeName ? ` --change ${changeName}` : ''} --output "修复说明"`)
+        process.exit(1)
+      }
+      for (const _dflWarn of (_dflResult.warnings || [])) console.warn(`   ⚠️ ${_dflWarn}`)
+    } catch (_dflEx) {
+      console.warn(`   ⚠️ design 清单核验自身异常，fail-open 放行（不误拦本次完成）：${_dflEx && _dflEx.message ? _dflEx.message : _dflEx}`)
+    }
+  }
 
   // ── noAI 步骤硬门（坑 noai-done-bypass）：noAI 步骤的确定性校验不可被 --done 绕过 ──
   // 正常路径 agent 跑 `run <stage>` 推进到 noAI step 时，runStage 自动执行 _cliAction
@@ -296,8 +369,17 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       await executeScanPreflight(cwd, platformOpts, stageData.scanProfile || computeScanProfile(cwd, platformOpts))
     } else if (_cliAction === 'scanPostcheck') {
       await executeScanPostcheck(cwd, platformOpts, stageData.scanProfile || computeScanProfile(cwd, platformOpts))
+    } else if (_cliAction === 'scanDetectProjects') {
+      await executeScanDetectProjects(cwd, platformOpts)
+    } else if (_cliAction === 'scanResumeCheck') {
+      await executeScanResumeCheck(cwd, platformOpts)
+    } else if (_cliAction === 'scanFinalize') {
+      await executeScanFinalize(cwd, platformOpts)
     } else if (_cliAction === 'planPostcheck') {
       await runPlanPostcheckLib({ cwd, specRoot: platformOpts?.specRoot, resolveChangeDir, progress })
+    } else if (_cliAction === 'progressConfirm') {
+      // 与 stage.js noAI 分支同语义（brainstorm/execute/verify step1 进度确认）
+      executeProgressConfirm({ stageName, cwd, stageData, changeName, pm })
     } else {
       throw new Error(`noAI 步骤 ${steps[currentIdx].name} 的未知 _cliAction: ${_cliAction}——请在 complete.js 注册对应分支`)
     }
@@ -445,6 +527,11 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       }
     }
 
+    // 主阶段完成钉 currentStage（troubleshooting #56 根因修复，2026-09-08）：
+    // `run <stage> --done` 直达完成不经过裸 run 入口（唯一写点 stage.js:227），
+    // currentStage 停留旧阶段 → 下游 checkTransition 用 stale prevStage 误拦
+    // （实证：verify 全 --done 完成后归档报 execute→archive）。与入口写点同语义：辅助阶段不写。
+    if (!AUXILIARY_STAGES.includes(stageName)) progress.currentStage = stageName
     stageData.status = 'completed'
     stageData.completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
     progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
@@ -507,6 +594,13 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
         console.log(`\n👉 下一步：sillyspec run verify${changeName ? ` --change ${changeName}` : ''}（验证通过后才能归档）`)
       }
     } else if (stageName === 'archive') {
+      // 机械暂存 CLI 化（2026-09-05 全流程审计）：原步骤 6 的 3 条固定路径 git add agent 指令
+      // 改为完成时 CLI 直做（未变更路径 git add 是无害 no-op）。平台模式跳过（specRoot 在源码仓外）。
+      if (!platformOpts?.specRoot && !platformOpts?.runtimeRoot) {
+        const { stageArchiveArtifacts } = await import('../git-helper.js')
+        const r = stageArchiveArtifacts(cwd)
+        if (r.staged.length > 0) console.log(`  📦 已暂存归档产物（${r.staged.length} 个路径，未提交，由统一提交工具处理）`)
+      }
       console.log('\n👉 归档完成！现在可以提交了：git commit -m "..."')
     } else if (stageName === 'verify') {
       // verify 的"验证通过"提示延后到下方 validator 通过后才打印，
@@ -561,7 +655,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     }
   }
 
-  const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const defSteps = await getStageStepsAutoAware(stageName, cwd, progress, platformOpts?.specRoot || null)
   console.log(`✅ Step ${currentIdx + 1}/${steps.length} 完成：${steps[currentIdx].name}\n`)
 
   // Workflow post_check（W6 Step6 抽至 complete-handlers.js handleWorkflowPostCheck）
@@ -962,7 +1056,7 @@ export async function waitStep(pm, progress, stageName, cwd, outputText, waitRea
 
   // maxWaitRounds 硬上限：达到后拒绝继续 --wait
   const currentStep = stageData.steps[currentIdx]
-  const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const defSteps = await getStageStepsAutoAware(stageName, cwd, progress, platformOpts?.specRoot || null)
   const stepDef = defSteps?.[currentIdx] || {}
   const maxWaitRounds = currentStep.maxWaitRounds ?? stepDef.maxWaitRounds
   const currentWaitRound = currentStep.waitRound || 0
@@ -1076,7 +1170,7 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
   } else {
     currentIdx = waitingSteps[0].idx
   }
-  const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const defSteps = await getStageStepsAutoAware(stageName, cwd, progress, platformOpts?.specRoot || null)
   const currentStepDef = defSteps?.[currentIdx] || {}
   const currentStep = stageData.steps[currentIdx]
   const isRepeatableWait = currentStepDef.repeatableWait === true || currentStep.repeatableWait === true
@@ -1174,6 +1268,11 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
   if (nextPendingIdx === -1 && nextWaitingIdx === -1) {
     stageData.status = 'completed'
     stageData.completedAt = now
+    // 主阶段完成钉 currentStage（troubleshooting #56 根因修复，2026-09-08）：
+    // `run <stage> --done` 直达完成不经过裸 run 入口（唯一写点 stage.js:227），
+    // currentStage 停留旧阶段 → 下游 checkTransition 用 stale prevStage 误拦
+    // （实证：verify 全 --done 完成后归档报 execute→archive）。与入口写点同语义：辅助阶段不写。
+    if (!AUXILIARY_STAGES.includes(stageName)) progress.currentStage = stageName
     // persist _write 移到 completeStageGates 成功之后（task-03 / review-2026-08-09 #2）：gate 异常/失败 → rollback 回 in-progress 落盘，此处未到 _write，DB 不留假 completed。
     // 阶段完成收尾共享管线（含 execute worktree cleanup），消除 continueStep 完成分支绕过 gate 的 S2（task-01 抽出）。
     // gate 失败已 rollback，early-return 跳过下方"阶段已完成/下一步"提示（与 completeStep 同语义）。
@@ -1258,7 +1357,7 @@ export async function skipStep(pm, progress, stageName, cwd, changeName, platfor
     process.exit(1)
   }
 
-  const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const defSteps = await getStageStepsAutoAware(stageName, cwd, progress, platformOpts?.specRoot || null)
   const stepDef = defSteps ? defSteps[currentIdx] : null
   if (stepDef && !stepDef.optional) {
     console.error(`❌ 步骤 "${steps[currentIdx].name}" 不可跳过`)