sillyspec 3.28.3 → 3.28.4

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 语义清晰（关联变更），不与「指定变更名」混淆。
@@ -1250,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) {

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}`)
@@ -900,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，
@@ -1068,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 §七）需要分母：信号触发次数必须可追溯。
@@ -1087,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

@@ -380,11 +380,49 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     } 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) {
@@ -400,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
     }

package/src/run/gates.js

@@ -552,7 +552,33 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
   // runtimeRoot 进 context（坑 verify-receipt-runtime-split）：verify 回执写入方
   // reapVerifyServices 落 resolveRuntimeRoot(platformOpts, specBase)，校验器读侧不透传时
   // 平台/漂移模式恒读不到回执 → 证据门退回纯字面匹配（回执机制正是为消灭它而生）
-  const contractResult = runValidators(stageName, cwd, changeName, { projectName, specRoot: platformOpts?.specRoot, runtimeRoot: resolveRuntimeRoot(platformOpts, specBase) })
+  //
+  // ── verify 收尾前置：facts slot-backfill + verifyStartAt（2026-09-08-ir-verify-facts FR-03）──
+  // 执行次序（design Phase 3）：backfill（结论/证据/回执槽固化）先行 → runValidators（结论门/
+  // 集成证据门读得到固化值与 context.verifyStartAt）→ verify 专属块（test 实测 → tests 段二次
+  // 回填 → cannot_verify 硬门）。verifyStartAt = DB execute 行 completed_at（只读；缺省 null →
+  // 证据核验走 R-05 design created_at fallback）。
+  let verifyStartAtIso = null
+  if (stageName === 'verify') {
+    try {
+      verifyStartAtIso = pm.getStageCompletedAt(cwd, changeName, 'execute')
+    } catch { verifyStartAtIso = null }
+    try {
+      const verifyMdPath = join(specBase, 'changes', changeName, 'verify-result.md')
+      if (existsSync(verifyMdPath)) {
+        const verifyMd = readFileSync(verifyMdPath, 'utf8')
+        const { backfillFactsFromMdAndTests } = await import('../verify-probes.js')
+        const { extractVerifyConclusionSlot } = await import('../stage-contract.js')
+        backfillFactsFromMdAndTests(join(specBase, 'changes', changeName, 'verify-facts.json'), {
+          verifyMd,
+          conclusion: extractVerifyConclusionSlot(verifyMd),
+        })
+      }
+    } catch (e) {
+      console.warn(`⚠️ facts slot-backfill 失败（fail-soft，不阻断；门禁仍读 md 槽）: ${e && e.message ? e.message : e}`)
+    }
+  }
+  const contractResult = runValidators(stageName, cwd, changeName, { projectName, specRoot: platformOpts?.specRoot, runtimeRoot: resolveRuntimeRoot(platformOpts, specBase), ...(verifyStartAtIso ? { verifyStartAt: verifyStartAtIso } : {}) })
   if (contractResult.errors.length > 0) {
     console.error(`\n❌ 阶段 ${stageName} 校验失败：`)
     for (const err of contractResult.errors) {
@@ -584,7 +610,9 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     try {
       const { resolveApplyAllowSet } = await import('../worktree-apply.js')
       const { warnFacadeCandidateFiles } = await import('../facade-hint.js')
-      const allowMap = resolveApplyAllowSet(cwd, changeName)
+      // specBase 显式传（2026-09-08 平台模式修复）：changes/ 实体在 specRoot，本地目录常空——
+      // 旧硬编码在平台模式 allow 集恒空，facade 候选预检对空集全量误报
+      const allowMap = resolveApplyAllowSet(cwd, changeName, { specBase })
       warnFacadeCandidateFiles({ cwd, changeName, allowSet: allowMap.get('main') })
     } catch { /* 预检失败不阻断 plan 完成 */ }
   }
@@ -598,6 +626,21 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     console.log(`\n⏳ Verify 测试对账：CLI 亲自执行 local.yaml 的 commands.test（同步，耗时可能较长，请等待…）`)
     const testCheck = runVerifyTestCheck({ cwd, specBase, changeName, ctx })
     printVerifyTestCheck(testCheck)
+    // tests 段二次回填（2026-09-08-ir-verify-facts FR-03 次序：实测在 runValidators 之后，
+    // tests 快照此刻才可得；不参与门禁——供 P3d 追溯）
+    try {
+      const verifyMdPath2 = join(specBase, 'changes', changeName, 'verify-result.md')
+      if (existsSync(verifyMdPath2)) {
+        const { backfillFactsFromMdAndTests } = await import('../verify-probes.js')
+        const { extractVerifyConclusionSlot } = await import('../stage-contract.js')
+        const verifyMd2 = readFileSync(verifyMdPath2, 'utf8')
+        backfillFactsFromMdAndTests(join(specBase, 'changes', changeName, 'verify-facts.json'), {
+          verifyMd: verifyMd2,
+          conclusion: extractVerifyConclusionSlot(verifyMd2),
+          testCheckResult: testCheck,
+        })
+      }
+    } catch { /* fail-soft：回填失败不影响门禁 */ }
     if (testCheck.status === 'failed') {
       console.error('\n❌ verify 阶段被阻断：verify-result.md 自报告通过，但 CLI 实测测试失败。')
       // 并行 WIP 归因鉴别（坑 verify-reconcile-foreign-wip）：实测跑在主仓共享工作区，并行会话
@@ -650,6 +693,19 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
       console.log(`\n⏳ Verify lint 对账：CLI 亲自执行 local.yaml 的 commands.lint…`)
     }
     printVerifyLintCheck(lintCheck)
+    // lint 硬门（2026-09-09 升硬：观察期 14 次 5 败全真阳性，pre-push 本就硬拦——fail-fast 前移；
+    // 逃生 SILLYSPEC_VERIFY_LINT_GATE=advisory）
+    const { shouldBlockVerifyLint } = await import('../verify-postcheck.js')
+    if (shouldBlockVerifyLint(lintCheck)) {
+      console.error('\n❌ verify 阶段被阻断：CLI 亲自实测 lint 失败（agent 的 lint 自报告与实测不符时以实测为准）。')
+      if (lintCheck.outputTail) {
+        const tail = lintCheck.outputTail.split('\n').slice(-8).join('\n')
+        console.error('   输出（末尾）：')
+        for (const line of tail.split('\n')) console.error(`   | ${line}`)
+      }
+      console.error('   修复后重跑 --done（进度不丢）；确认要跳过实测请设 SILLYSPEC_VERIFY_LINT_GATE=advisory（审计留痕）。')
+      return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
+    }
     // 契约 parity 对账：扫前端 API 调用 vs execute 提取的 provider endpoint artifact。
     // 接线自 contract-matrix pipeline（verifyApiParity 的 CLI 入口）。
     const { runVerifyParityCheck, printVerifyParityCheck } = await import('../verify-postcheck.js')
@@ -660,12 +716,26 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     const { runVerifyDeletionCheck, printVerifyDeletionCheck } = await import('../verify-postcheck.js')
     const deletionCheck = runVerifyDeletionCheck({ cwd, specBase, changeName })
     printVerifyDeletionCheck(deletionCheck)
-    // ── required-evidence 对账（advisory，不阻断）：闭合 execute→verify evidence 死链 ──
-    // execute Task Review Gate 把 cannot_verify 任务的 evidence 落盘 verify-required-evidence.json，
-    // 本探针查每个 cannot_verify 任务是否在 verify-result.md 体现（CLI 只查提及，满足度 agent 自报告）。
+    // ── required-evidence 对账（2026-09-08-ir-verify-facts FR-03：v2 起 cannot_verify 不闭环阻断）──
+    // execute Task Review Gate 把 cannot_verify 任务的 evidence 落盘 verify-required-evidence.json。
+    // v2 槽优先分类核验（FR-02）：blocked = missing 无豁免或 satisfied 核验不过 → 阻断 verify 完成
+    // （此前 advisory 只查「提及」——死链不闭环）；无槽存量 md 降级 legacy 子串对账（warning 不阻断）。
     const { runVerifyRequiredEvidenceCheck, printVerifyRequiredEvidenceCheck } = await import('../verify-postcheck.js')
-    const evidenceCheck = runVerifyRequiredEvidenceCheck({ cwd, specBase, changeName })
+    const evidenceCheck = runVerifyRequiredEvidenceCheck({ cwd, specBase, changeName, verifyStartAt: verifyStartAtIso })
     printVerifyRequiredEvidenceCheck(evidenceCheck)
+    if (evidenceCheck.status === 'blocked') {
+      console.error(`\n❌ verify 阶段被阻断：cannot_verify 证据账未闭环（${evidenceCheck.summary}）。`)
+      for (const d of (evidenceCheck.detailed || [])) {
+        console.error(`   - ${d.task} [${d.status}${d.exempt ? '/豁免' : ''}] ${d.reason}`)
+        for (const v of (d.verification || [])) {
+          if (v && v.reason) console.error(`     · ${v.path || '(无路径)'} [${v.pathClass || '?'}] ${v.reason}（filesExist=${v.filesExist} mtimeOk=${v.mtimeOk} diffHit=${v.diffHit}）`)
+        }
+      }
+      console.error(`   修复：在 verify-result.md「## 证据账（cannot_verify 任务）」槽段逐 task 一行——`)
+      console.error(`   - task-NN: satisfied | verifiedFiles: <精确路径>（CLI 核验：代码类 存在×mtime×diff 交集；日志/文档类豁免 diff）`)
+      console.error(`   - 确实无法验证 → 填 missing 并加（豁免：<一句话理由>）后缀；部分满足 → partial + 已核验路径`)
+      return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
+    }
     // ── target_files 声明 ↔ 实际改动 对账（task-05 / ir-stage-p3a：②ERROR 阻断 / ③WARNING 放行）──
     // 「计划落空」（task 卡声明没做）此前全盲区：review.json changedFiles 是 agent 手写不能当
     // 事实源，execute 的 scope creep 只有 symbol-impact 试图抓。reconcileTargetFiles 用 git 三源
@@ -721,6 +791,24 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     if (probeBlocked) {
       return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
     }
+    // ── 行号漂移自动重锚（2026-09-09 §7-6：quick --done 已接，verify/archive 收尾补接）──
+    // 本变更 diff 中的 .md 文档经 autoReanchorDocRefs 定点重锚（fixable 唯一/优选命中才改 +
+    // 同口径回执），消灭「src 改动平移行号 → 下次 docs gate 拦」的人工往返。挂 verify 收尾即
+    // 覆盖 archive 面（漂移源是 src 改动，archive 的文档同步步不产生新 src 平移）。fail-open。
+    try {
+      const { resolveVerifyChangedFiles } = await import('../verify-postcheck.js')
+      const mdChangedVa = (resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true, specBase }) || [])
+        .filter(f => f.endsWith('.md') && !f.startsWith('.sillyspec/changes/'))
+      if (mdChangedVa.length > 0) {
+        const { autoReanchorDocRefs, readDocsCheckConfig } = await import('../docs-check.js')
+        let fixCfgVa = {}
+        try { fixCfgVa = readDocsCheckConfig(cwd) || {} } catch { fixCfgVa = {} }
+        const rVa = autoReanchorDocRefs(cwd, mdChangedVa, fixCfgVa)
+        if (rVa.applied > 0) {
+          console.log(`🔧 文档行号漂移自动重锚（${stageName} 收尾）：${rVa.applied} 处已改写（${rVa.invalidBefore} → ${rVa.invalidAfter}；剩余 ${rVa.remaining} 处需人工 sillyspec docs check）`)
+        }
+      }
+    } catch { /* 自动重锚失败不影响收尾（docs gate 兜底） */ }
     // ── module-impact 死信探针（blocking，债单 D-1/D-5）：更新结果表 pending/待办行 → 阻断 verify ──
     // 与 archive 移动前校验（extractPendingDocSyncRows）同一口径，把死信号从 archive 提前到 verify：
     // agent 在 verify 阶段就须完成文档同步并回填 done/skipped，而非拖到归档被拦（修复 perf-remediation

package/src/run/prompt.js

@@ -19,7 +19,7 @@
  *   - loadModuleContextIndex/buildModuleContextInjection 内 require('fs'/'path') 改顶部静态 import
  */
 import { basename, join } from 'node:path'
-import { existsSync, readFileSync, mkdirSync } from 'node:fs'
+import { existsSync, readFileSync, mkdirSync, readdirSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { stageRegistry } from '../stages/index.js'
 import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, WAIT_MARKER_RE, QUICK_SID_RE } from './shared.js'
@@ -124,6 +124,63 @@ function buildModuleContextInjection(taskDescription, moduleIndex, specBase, pro
   return injection
 }
 
+/**
+ * 读 quick session guard 的任务描述（刀①）：启动 --input 由 stage.js 落 guard.taskDescription，
+ * 渲染 step1 模块上下文注入时作匹配源（changeName 是 quick-<hash> 无语义）。
+ * 与 <quicklog-id>/<linked-changes> 占位符同源同容错（session guard 优先，legacy 单文件回退）。
+ */
+export function readQuickGuardField(changeName, specBase, field) {
+  try {
+    const sessionGuardFile = join(specBase, '.runtime', 'quick-sessions', changeName, 'guard.json')
+    const legacyGuardFile = join(specBase, '.runtime', 'quick-guard.json')
+    const guard = existsSync(sessionGuardFile)
+      ? JSON.parse(readFileSync(sessionGuardFile, 'utf8'))
+      : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
+    return guard ? (guard[field] || '') : ''
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * quick step1 项目上下文摘要（刀①）：CLI 代读 projects/*.yaml 与 CONVENTIONS.md 开头注入
+ * prompt——替代 agent 两轮 cat（quick 是最高频路径，省 token + 省轮次）。fail-soft：
+ * 读不到落单行说明，绝不阻断 prompt 输出。
+ */
+export function buildQuickContextDigest(specBase, projectName) {
+  try {
+    const sections = []
+    // 项目登记摘要（name/path/status 一行一个——技术栈等扩展字段按行透传 top-level 短行）
+    const projectsDir = join(specBase, 'projects')
+    if (existsSync(projectsDir)) {
+      const lines = []
+      for (const f of readdirSync(projectsDir).filter(f => f.endsWith('.yaml'))) {
+        const text = readFileSync(join(projectsDir, f), 'utf8')
+        const name = (text.match(/^name:\s*(.+)$/m) || [])[1]
+        const path = (text.match(/^path:\s*(.+)$/m) || [])[1]
+        const status = (text.match(/^status:\s*(.+)$/m) || [])[1]
+        lines.push(`- ${name ? name.trim() : f.replace(/\.yaml$/, '')}（${path ? path.trim() : '?'}）${status ? ` — ${status.trim()}` : ''}`)
+      }
+      if (lines.length > 0) sections.push('### 项目登记（projects/*.yaml 摘要）\n' + lines.join('\n'))
+    }
+    // CONVENTIONS.md 开头（截断保底——全文可能很长，注入是省读取税不是塞全文）
+    const convPath = join(specBase, 'docs', projectName, 'scan', 'CONVENTIONS.md')
+    if (existsSync(convPath)) {
+      const text = readFileSync(convPath, 'utf8')
+      const HEAD_CHARS = 1200
+      const head = text.length > HEAD_CHARS
+        ? text.slice(0, HEAD_CHARS) + `\n…（截断——全文 ${convPath}，需要时再读）`
+        : text
+      sections.push('### 项目约定（CONVENTIONS.md 开头，CLI 代读）\n' + head)
+    }
+    return sections.length > 0
+      ? sections.join('\n\n')
+      : '（无项目登记/约定文档——需要时按 prompt 内路径自查）'
+  } catch (e) {
+    return `（项目上下文注入失败：${e && e.message ? e.message : e}——需要时再 cat {SPEC_ROOT}/projects/*.yaml 与 CONVENTIONS.md）`
+  }
+}
+
 // parseModuleMapSimple 复用 modules.js 的 canonical 实现（合并历史 copy-paste 副本，2026-08-07；
 // 无循环依赖：modules.js 仅 import fs/path/db.js，prompt.js → modules.js 单向）。
 /**
@@ -566,6 +623,14 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     promptText = promptText.replace(/\{LOCAL_COMMANDS\}/g, localBlock)
   }
 
+  // ①b {QUICK_CONTEXT_DIGEST}（刀①，2026-09-08）：quick step1 的项目/约定上下文 CLI 代读注入
+  // ——替代 agent cat projects/*.yaml 与 CONVENTIONS.md 两轮文件读取（quick 是最高频路径）。
+  // fail-soft 同三件套；无 quick 占位符自然零输出。
+  if (stageName === 'quick' && promptText.includes('{QUICK_CONTEXT_DIGEST}')) {
+    const digestSpecBase = resolvePromptSpecBase(platformOpts, cwd)
+    promptText = promptText.replace(/\{QUICK_CONTEXT_DIGEST\}/g, buildQuickContextDigest(digestSpecBase, projectName))
+  }
+
   // ② {GIT_DIRTY}：工作区脏文件清单（git status --porcelain，quick 收尾步消费）
   if (promptText.includes('{GIT_DIRTY}')) {
     let dirtyBlock = ''
@@ -927,13 +992,39 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     promptText = promptText.split('{EVIDENCE_AUTO_RECOMMENDATION}').join(eaInjected)
   }
 
-  // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
-  if (['brainstorm', 'plan', 'execute'].includes(stageName) && projectName) {
+  // {ARCHIVE_IMPACT_AUDIT}（2026-09-09 ql-20260909-004）：archive extract-module-impact 步的
+  // 三重核对机械预填——auditModuleImpactAgainstDiff 代算（module-impact × diff × map 归属），
+  // agent 只裁决不一致项。fail-soft：审计异常降级单行指引（回退手跑 git diff）。
+  if (stageName === 'archive' && promptText.includes('{ARCHIVE_IMPACT_AUDIT}')) {
+    let auditBlock = ''
+    try {
+      const { auditModuleImpactAgainstDiff } = await import('../archive-delta.js')
+      const auditSpecBase = resolvePromptSpecBase(platformOpts, cwd)
+      const r = auditModuleImpactAgainstDiff({ cwd, changeName, specDir: auditSpecBase })
+      auditBlock = [
+        '【三重核对报告（CLI 机械预填）】',
+        r.summary,
+        ...(r.mismatches.length > 0 ? ['不一致项：', ...r.mismatches.map(m => '  - ' + m), '→ 逐项裁决并修正 module-impact.md；其余（未列出的 diff 文件为 .sillyspec 产物不参与核对）无需处理。'] : ['一致 ✓——第 3 步修正可跳过。']),
+      ].join(String.fromCharCode(10))
+    } catch (e) {
+      auditBlock = '（三重核对机械预填失败：' + (e && e.message ? e.message : e) + '——回退手跑 git diff --name-only 比对）'
+    }
+    promptText = promptText.split('{ARCHIVE_IMPACT_AUDIT}').join(auditBlock)
+  }
+
+  // 注入模块上下文（brainstorm/plan/execute 阶段全步 + quick 首步「理解任务」——刀①：quick
+  // step1 原让 agent cat module-map 再挑模块卡读，改为按任务描述匹配后注入，基于 Module Context Index）
+  const quickFirstStep = stageName === 'quick' && step && step.name === '理解任务'
+  if ((['brainstorm', 'plan', 'execute'].includes(stageName) || quickFirstStep) && projectName) {
     const effectiveSpecBase = resolvePromptSpecBase(platformOpts, cwd)
     const moduleIndex = loadModuleContextIndex(effectiveSpecBase, projectName)
     if (moduleIndex && Object.keys(moduleIndex).length > 0) {
-      // 尝试从 step prompt / changeName 匹配模块
-      const taskDesc = step.prompt || changeName || ''
+      // 尝试从 step prompt / changeName 匹配模块；quick 用 guard.taskDescription（启动 --input）——
+      // changeName 是 quick-<hash> 无语义、step.prompt 全文噪音大（刀①）
+      let taskDesc = step.prompt || changeName || ''
+      if (stageName === 'quick') {
+        taskDesc = readQuickGuardField(changeName, effectiveSpecBase, 'taskDescription') || taskDesc
+      }
       const injection = buildModuleContextInjection(taskDesc, moduleIndex, effectiveSpecBase, projectName)
       if (injection) {
         promptText = injection + '\n' + promptText