sillyspec 3.28.2 → 3.28.4

package/src/run/complete-handlers.js

@@ -26,12 +26,12 @@ import { basename, join, resolve, relative, isAbsolute } from 'node:path'
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync } from 'node:fs'
 import { renameSyncRetry, writeAtomicSync } from '../fs-atomic.js'
 import { gitQuiet } from '../git-helper.js'
-import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, resolveRuntimeRoot, collectOtherQuickSessionDeclarations, mergeQuickBoundaryFiles } from './shared.js'
+import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, isQuicklogFileLineNoise, resolveRuntimeRoot, collectOtherQuickSessionDeclarations, mergeQuickBoundaryFiles } from './shared.js'
 import { detectConcurrentChanges, formatConcurrentWarning, resolveConcurrentAnchor } from './concurrent-detect.js'
 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, appendQuicklogEntryWithId, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult } from '../quicklog.js'
+import { validateQuickResult, allocateQuicklogEntry, appendQuicklogEntryWithId, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult, parseFileNotes, getQuickFileNotes } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
 import { archiveDestDirName } from '../stage-contract.js'
 
@@ -121,11 +121,115 @@ export function findAlreadyArchivedDir(archiveDir, changeName) {
   return null
 }
 
+/**
+ * reviewedFiles[0] → 归属变更名。契约为 `changes/<change>/<doc>`（stage-review.js
+ * getLatestStageReviewRunId）。取 `changes/` 后第一路径段精确相等——`includes('changes/'+name+'/')`
+ * 会让短名 login 命中 2026-08-01-login（坑 marker-suffix-overmatch 同类）。
+ * @returns {string|null}
+ */
+function ownerFromReviewedFiles(reviewedFiles) {
+  const r0 = Array.isArray(reviewedFiles) ? String(reviewedFiles[0] || '') : ''
+  const m = r0.replace(/\\/g, '/').match(/(?:^|\/)changes\/([^/]+)\//)
+  return m ? m[1] : null
+}
+
+/**
+ * 归档后按 change 精确回收 .runtime 取证（ql-20260908-005-7549）。
+ *
+ * 调用时点：handleArchiveConfirmStep 已把 reconcile/apply-pathspec 吃进 delta.md 之后
+ * （fail-soft 生成失败也不阻断——变更已终态，runtime 取证无读者）。自愈归档 / quick 轻量
+ * 归档 / change-delete 无 delta 同样可删。
+ *
+ * 归属 fail-closed（禁 mtime 猜、禁后缀匹配）：
+ *   apply-pathspec-<change>.txt 精确文件名
+ *   execute-runs/<runId>/ 仅当 `change` 戳全等（无戳旧 run 留下，不按覆盖度启发式删）
+ *   stage-reviews/<dir>/ 仅当 review.json reviewedFiles 首段 === changeName
+ *   verify-runs/<ts>/ 仅当目录内 JSON 的 change 字段集合 size=1 且等于本变更
+ * 本轮不扩 endpoint-baselines / contract-artifacts / last-delta.json。
+ *
+ * fail-open：卫生动作失败不抛，返回 { ok:true }。
+ *
+ * @param {string} runtimeRoot
+ * @param {string} changeName
+ * @returns {{ ok: true, removed: number }}
+ */
+export function pruneArchivedChangeRuntime(runtimeRoot, changeName) {
+  if (!runtimeRoot || !changeName || !existsSync(runtimeRoot)) return { ok: true, removed: 0 }
+  let removed = 0
+  const gone = (p, recursive = false) => {
+    try {
+      if (recursive) rmSync(p, { recursive: true, force: true })
+      else unlinkSync(p)
+      removed++
+    } catch { /* 单份失败不连坐，下次归档/删变更再收 */ }
+  }
+
+  try {
+    const pathspec = join(runtimeRoot, `apply-pathspec-${changeName}.txt`)
+    if (existsSync(pathspec)) gone(pathspec)
+  } catch {}
+
+  try {
+    const execDir = join(runtimeRoot, 'execute-runs')
+    if (existsSync(execDir)) {
+      for (const runId of readdirSync(execDir)) {
+        const stampFile = join(execDir, runId, 'change')
+        if (!existsSync(stampFile)) continue
+        let stamp = ''
+        try { stamp = readFileSync(stampFile, 'utf8').trim() } catch { continue }
+        if (stamp !== changeName) continue
+        gone(join(execDir, runId), true)
+      }
+    }
+  } catch {}
+
+  try {
+    const srDir = join(runtimeRoot, 'stage-reviews')
+    if (existsSync(srDir)) {
+      for (const entry of readdirSync(srDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue
+        const rjPath = join(srDir, entry.name, 'review.json')
+        if (!existsSync(rjPath)) continue
+        let owner = null
+        try {
+          const rj = JSON.parse(readFileSync(rjPath, 'utf8'))
+          owner = ownerFromReviewedFiles(rj.reviewedFiles)
+        } catch { continue }
+        if (owner !== changeName) continue
+        gone(join(srDir, entry.name), true)
+      }
+    }
+  } catch {}
+
+  try {
+    const vrDir = join(runtimeRoot, 'verify-runs')
+    if (existsSync(vrDir)) {
+      for (const entry of readdirSync(vrDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue
+        const dir = join(vrDir, entry.name)
+        let files = []
+        try { files = readdirSync(dir).filter(f => f.endsWith('.json')) } catch { continue }
+        const owners = new Set()
+        for (const f of files) {
+          try {
+            const data = JSON.parse(readFileSync(join(dir, f), 'utf8'))
+            if (data && typeof data.change === 'string' && data.change) owners.add(data.change)
+          } catch { /* 单文件坏 JSON 跳过，不据此猜归属 */ }
+        }
+        if (owners.size === 1 && owners.has(changeName)) gone(dir, true)
+      }
+    }
+  } catch {}
+
+  return { ok: true, removed }
+}
+
 /**
  * 归档时清理可能残留的 worktree（execute 自动清理未走到 / 有未 apply 变更被遗弃）。
  * 安全策略：有未 apply 变更时保留 worktree 并警告，避免误删用户未应用的代码。
  * 同时清理该变更的 execute / stage-review runId marker（只写不删的累积物，
- * 见 stage.js execute 启动固定 executeRunId / stage-review.js stageReviewMarkerPath）。
+ * 见 stage.js execute 启动固定 executeRunId / stage-review.js stageReviewMarkerPath）
+ * 以及归档后无读者的 runtime 取证（pruneArchivedChangeRuntime）。
  * 从 archiveChangeDirectory 抽出，供正常归档 + 自愈归档复用。
  */
 export async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts = {}) {
@@ -151,6 +255,12 @@ export async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, p
       if (markers.length > 0) {
         console.log(`🧹 归档清理 ${markers.length} 个 runId marker（execute/stage-review）`)
       }
+      // 取证回收必须在下方 worktree 块的 `if (!meta) return` 之前：无 meta 早退是常态
+      // （apply 已 cleanup），漏接就会让 execute-runs/verify-runs 继续按变更数累积。
+      const pruned = pruneArchivedChangeRuntime(runtimeRoot, archiveChangeName)
+      if (pruned.removed > 0) {
+        console.log(`🧹 归档回收 ${pruned.removed} 项 runtime 取证（execute-runs/stage-reviews/verify-runs/apply-pathspec，按 change 精确匹配）`)
+      }
     }
   } catch (e) {
     console.warn(`⚠️  归档 runId marker 清理失败（不阻断归档）: ${e.message}`)
@@ -441,16 +551,19 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
   const deltaChangeName = progress.currentChange || changeName
   if (deltaChangeName) {
     try {
-      const { buildDeltaReport } = await import('../archive-delta.js')
+      const { buildDeltaReport, writeLastDeltaSidecar } = await import('../archive-delta.js')
       const deltaChangeDir = join(specBase, 'changes', deltaChangeName)
-      const deltaMd = buildDeltaReport({
+      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'), deltaMd)
+      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}`)
@@ -897,6 +1010,21 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         console.log(`🛡️ quick 边界已追加: ${added.length} 个文件（累计 ${guard.allowedFiles.length} 个）: ${added.join(', ')}`)
       }
     }
+    // --file-notes 路径同源并入边界（2026-09-08 用户反馈①：step3 只带 --file-notes 未带
+    // --files 时，QUICKLOG 文件行写进了这些文件、审计却按「超出 allowedFiles + 未声明」
+    // 拦——两条声明通道口径打架）。--file-notes 是显式的改动文件声明（路径部分参与落盘
+    // 文件行），与 --files 同语义追加；括注只是展示不参与。读取用 getQuickFileNotes（与
+    // 下方 completeQuicklogEntry 消费同一 per-process 值，读不清）。
+    {
+      const fileNotePaths = parseFileNotes(getQuickFileNotes()).map(n => n.path).filter(Boolean)
+      if (guard && fileNotePaths.length > 0) {
+        const { added } = mergeQuickBoundaryFiles(guard, fileNotePaths, cwd)
+        if (added.length > 0) {
+          try { writeAtomicSync(sessionGuardFile, JSON.stringify(guard, null, 2)) } catch { /* 同上：内存合并值兜底 */ }
+          console.log(`🛡️ quick 边界已追加（--file-notes 声明与文件行同源）: ${added.length} 个文件（累计 ${guard.allowedFiles.length} 个）: ${added.join(', ')}`)
+        }
+      }
+    }
     // 审计：仅在有 guard 时跑（brownfield 无 guard 跳过，兼容 D-003 brownfield 行为）。
     // task-02：mergedGuard 提升到 if 外声明，供下方并发预检钩子复用与 auditQuickCompletion
     // 同源的 guard 字段（baselineFiles/linkedChanges）。brownfield 无 guard 时保持 null，
@@ -932,10 +1060,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)
@@ -1061,14 +1193,16 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
     // 翻状态进行中→已完成 + 追加结果 + 勾选关联 tasks.md
     // resultText 不再截断：结构化结果块（需求/根因/方案/结果）完整落盘，多行写成字段化块。
     try {
-      // 回填实际改动文件：review.changedFiles 含 quick 自身元数据（quicklog/.runtime/modules 等），
-      // 用 isQuickMetadata 过滤掉，只留真实业务文件。brownfield 无 review → 空数组，文件行不动。
+      // 回填实际改动文件：review.changedFiles 含 quick 自身元数据（quicklog/.runtime 等），
+      // 过滤掉只留真实业务文件——但**模块卡 + changelog sidecar 保留**（isQuicklogFileLineNoise，
+      // 2026-09-08 用户反馈①：收尾必改项此前每回手工补录；审计豁免面与记录面分叉）。brownfield
+      // 无 review → 空数组，文件行不动。
       // 归属口径（2026-08-18 误归属修复）：声明会话优先 attributedFiles（窗口∩声明∪同文件并发命中），
       // 他者窗口文件不进文件行；未声明会话/旧 review 无 attributedFiles → 兜底 changedFiles 全量。
       const auditFiles = Array.isArray(review?.attributedFiles)
         ? review.attributedFiles
         : (Array.isArray(review?.changedFiles) ? review.changedFiles : [])
-      const realFiles = auditFiles.filter(f => !isQuickMetadata(f, linkedChanges))
+      const realFiles = auditFiles.filter(f => !isQuicklogFileLineNoise(f, linkedChanges))
       // D-8 落盘（2026-08-18 修）：advisory 欠账信号从「纯打印」升级为「随条目落盘」——修复
       // 「欠账已记录（QUICKLOG reasons）」的不实承诺（交叉审查实证 reasons 纯 stdout，事后不可审计）。
       // 两周实测（2026-08-31 裁决，doc-consistency-debt §七）需要分母：信号触发次数必须可追溯。
@@ -1080,6 +1214,25 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
       }
       if (review?.docsCheckHint && review.docsCheckHint.invalid > 0) {
         auditNotes.push(`📎 文档引用失效：${review.docsCheckHint.invalid}/${review.docsCheckHint.total} 处 file:line 失效（sillyspec docs check 可复现）`)
+        // 行号漂移自动重锚（2026-09-08 用户反馈②：活文档 file:line 硬编码随任何插入失效，
+        // 每回手跑 docs check --fix 是机械活）：autoReanchorDocRefs = --fix 主链路编程化封装
+        // （fixable 唯一/优选命中才改 + 定点替换 + 同口径回执），只作用于本次改动的文档。
+        // fail-open：重锚任何异常只退化为上方 advisory 文案，绝不阻断 --done。
+        try {
+          const deletedSet = new Set(review.deletedFiles || [])
+          const mdChanged = (review.changedFiles || [])
+            .filter(f => f.endsWith('.md') && !deletedSet.has(f) && !isQuickMetadata(f, linkedChanges))
+          if (mdChanged.length > 0) {
+            const { autoReanchorDocRefs, readDocsCheckConfig } = await import('../docs-check.js')
+            let fixCfg = {}
+            try { fixCfg = readDocsCheckConfig(cwd) || {} } catch { fixCfg = {} }
+            const r = autoReanchorDocRefs(cwd, mdChanged, fixCfg)
+            if (r.applied > 0) {
+              auditNotes.push(`🔧 行号漂移已自动重锚 ${r.applied} 处（同口径复跑：${r.invalidBefore} → ${r.invalidAfter}；剩余 ${r.remaining} 处需人工 sillyspec docs check）`)
+              console.log(`🔧 文档行号漂移自动重锚：${r.applied} 处已改写，剩余 ${r.remaining} 处需人工（sillyspec docs check 可复现）`)
+            }
+          }
+        } catch { /* 自动重锚失败退化为纯 advisory（上方 auditNote 已落盘） */ }
       }
       // 归属切分注（2026-08-18 误归属修复）：窗口内未声明脏文件不进「文件：」行，但必须落盘可追溯
       // （多 agent 并发仓他者窗口改动 / 本会话漏声明均可能），防真实改动被静默挤走。

package/src/run/complete.js

@@ -21,7 +21,25 @@ 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'
+
+// 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'
@@ -220,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 施加到错误的步骤上
@@ -312,6 +330,29 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     }
   }
 
+  // ── 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
   // （stage.js noAI 分支，不写 step output）；若 agent 对 noAI step 直接 --done，此前
@@ -336,11 +377,52 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       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 if (_cliAction === 'doctorRunDiagnostics') {
+      // 2026-09-09-doctor-noai：与 stage.js 分支同语义（诊断+渲染+落盘）
+      const { runDoctorDiagnostics, renderDoctorSummary, writeDoctorDiagnosis } = await import('../doctor-diagnostics.js')
+      const diag = await runDoctorDiagnostics({ cwd })
+      console.log(renderDoctorSummary(diag))
+      try { writeDoctorDiagnosis(diag, (platformOpts?.specRoot || join(cwd, '.sillyspec'))) } catch { /* 落盘 fail-soft */ }
     } else {
       throw new Error(`noAI 步骤 ${steps[currentIdx].name} 的未知 _cliAction: ${_cliAction}——请在 complete.js 注册对应分支`)
     }
   }
 
+  // ── 并发 --done 防护（坑 execute-concurrent-done-skips-next-wave，2026-09-08 实证）──
+  // 会话 B 先 --done 推进了 Wave N，会话 A 随后的 --done 会落到**新的当前步 = Wave N+1**，
+  // 用 Wave N 的摘要静默完成 Wave N+1（产物未落地却标完成）。CLI 短进程无法读心，两层防护：
+  // ① 醒目前置横幅（邻步 60s 内刚被完成 = 疑似并行会话刚推进）——操作者在看到「✅ Step N
+  //    完成：Wave X」与自己所做不符时可立即 --reopen，不静默；
+  // ② 写前重读校验（本命令读库→落盘窗口内的真实竞态）：重读 DB，若本命令要完成的步骤
+  //    已被并行进程标 completed/skipped，拒绝覆盖式推进（防双写交错把状态机写花）。
+  if (stageName === 'execute' && currentIdx > 0) {
+    const prev = steps[currentIdx - 1]
+    const _prevDoneAgoSec = prev?.completedAt ? Math.round((Date.now() - new Date(prev.completedAt.replace(/(\d{4})\/(\d{2})\/(\d{2})/, '$1-$2-$3')).getTime()) / 1000) : null
+    if (_prevDoneAgoSec !== null && Number.isFinite(_prevDoneAgoSec) && _prevDoneAgoSec >= 0 && _prevDoneAgoSec <= 60) {
+      console.warn('')
+      console.warn(`⚠️ 并发防护：上一步「${prev.name}」${_prevDoneAgoSec}s 前刚被（可能另一会话的）--done 完成——本次将完成的是「${steps[currentIdx].name}」。`)
+      console.warn(`   若与你刚做完的 Wave 不符，立即停手：sillyspec run ${stageName} --reopen --from-step ${currentIdx + 1}${changeName ? ` --change ${changeName}` : ''} 退回本步，勿继续下一 Wave。`)
+      console.warn('')
+    }
+  }
+  let _dupCompletedByPeer = false
+  try {
+    const _fresh = pm.read(cwd, changeName)
+    const _freshSteps = _fresh?.stages?.[stageName]?.steps
+    if (Array.isArray(_freshSteps) && _freshSteps[currentIdx] && _freshSteps[currentIdx].name === steps[currentIdx].name
+        && (_freshSteps[currentIdx].status === 'completed' || _freshSteps[currentIdx].status === 'skipped')) {
+      _dupCompletedByPeer = true
+    }
+  } catch { /* 重读失败（平台模式瞬态等）不阻断——横幅防护仍在 */ }
+  if (_dupCompletedByPeer) {
+    console.error(`❌ 步骤「${steps[currentIdx].name}」刚被并行会话完成（本命令读库后被推进），拒绝重复推进——防把下一步误标完成。`)
+    console.error(`   排查：sillyspec progress show${changeName ? ` --change ${changeName}` : ''} 确认当前步；你若也完成了同一 Wave，无需再次 --done；若要完成的是下一步，重跑 --done（此时它会落在正确的当前步）。`)
+    process.exit(1)
+  }
+
   steps[currentIdx].status = 'completed'
   steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
   if (outputText) {
@@ -356,6 +438,13 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       mkdirSync(artifactBase, { recursive: true })
       const ts = new Date().toISOString().slice(0,19).replace(/[-T:]/g, '')
       writeFileSync(join(artifactBase, `${changeName || 'unknown'}-${stageName}-step${currentIdx + 1}-${ts}.txt`), outputText)
+      // 写入侧滚动裁剪（runtime-hygiene.js，2026-09-08 系统性回收）：artifacts/ 只写不收，
+      // 实证本仓 534 份累积。文件名时间戳在尾部、前缀是变更名（长变更晚收尾会乱序）→ 按
+      // mtime 排序（write-once 本地审计文件，mtime 可靠）。fail-open 静默。
+      try {
+        const { pruneTimestampedEntries } = await import('../runtime-hygiene.js')
+        pruneTimestampedEntries({ dir: artifactBase, keep: 100, orderBy: 'mtime' })
+      } catch { /* 卫生动作 fail-open */ }
     } else {
       steps[currentIdx].output = outputText
     }
@@ -483,6 +572,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})
@@ -606,7 +700,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）
@@ -1007,7 +1101,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
@@ -1121,7 +1215,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
@@ -1219,6 +1313,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 同语义）。
@@ -1303,7 +1402,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}" 不可跳过`)