sillyspec 3.28.2 → 3.28.4

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 单向）。
 /**
@@ -185,7 +242,20 @@ export function collectStageWaitHistory(progress, stageName) {
 /**
  * 输出当前步骤的 prompt
  */
-export async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjectName, platformOpts = {}, prevStepAnswer = null, waitHistory = null) {
+/**
+ * requiresUser —— auto driver 元数据（change: 2026-09-08-auto-driver，D-002@v1）的四源判定纯函数：
+ * step.requiresWait / conditionalWait / requiresConfirm 三键（step 定义权威信号）+ WAIT_MARKER_RE 正文扫描
+ * （execute/verify 的 step 定义无三键，纯三源会漏真 wait 步）。全缺兜底 **false**——auto 默认语义是
+ * 继续驱动（Grill P1-①：保守 true 会让 execute/verify 逐步人工确认，推翻 FR-01）。
+ * 与 outputStep 内既有 mayNeedWait 计算同源（:1019 附近），仅多 requiresConfirm 一源。
+ */
+export function requiresUser(step, promptText) {
+  if (!step) return false
+  if (step.requiresWait === true || step.conditionalWait === true || step.requiresConfirm === true) return true
+  return WAIT_MARKER_RE.test(String(promptText || ''))
+}
+
+export async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjectName, platformOpts = {}, prevStepAnswer = null, waitHistory = null, autoMeta = null) {
   const step = steps[stepIndex]
   const total = steps.length
   // ── 越界防御 ──
@@ -199,6 +269,16 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     console.error(`   请检查 --change 指定的变更目录是否存在、specRoot 是否正确，然后重试。`)
     return false
   }
+
+  // ── 首个 agent 可见步索引（「首步一次建立」类注入的锚点）──
+  // step0 为 noAI（brainstorm/execute/verify 的 step1「进度确认」，2026-09-07）时不渲染 prompt，
+  // persona/护栏/完成契约/铁律/平台路径约束等 step0 专属注入须顺延到首个渲染步，否则整段丢失
+  //（spec-dir.test.mjs Test4 平台 specDir 断言即此坑的行为探针）。全 noAI 防御性回退 0。
+  const firstRenderableIdx = (() => {
+    const i = steps.findIndex(s => s?.noAI !== true)
+    return i === -1 ? 0 : i
+  })()
+
   const projectName = dbProjectName || basename(cwd)
 
   // ── Revision context injection ──
@@ -244,8 +324,8 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     console.log(`changeDir: ${changeDir}`)
   }
   console.log(`---\n`)
-  // persona 只在 stage 首步注入（step0）——角色设定一次即可，后续 step 重复注入纯属 token 浪费
-  if (personas[stageName] && stepIndex === 0) {
+  // persona 只在首个 agent 可见步注入——角色设定一次即可，后续 step 重复注入纯属 token 浪费
+  if (personas[stageName] && stepIndex === firstRenderableIdx) {
     console.log(personas[stageName])
     console.log('')
   }
@@ -255,7 +335,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
 
   console.log(`## Step ${stepIndex + 1}/${total}: ${step.name}\n`)
   if (guardrails) {
-    if (stepIndex === 0) {
+    if (stepIndex === firstRenderableIdx) {
       console.log(guardrails.trim())
       console.log('')
     } else {
@@ -398,13 +478,15 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       platformDirectives.push(`workspace_id: ${platformOpts.workspaceId}`)
     }
     // 平台 directives 前置条件：
-    //   - step0（对齐 persona 仅 step0 策略）：路径列表/Write 规则/占位符映射一次建立即可；
+    //   - 首个 agent 可见步（对齐 persona 仅 step0 策略）：路径列表/Write 规则/占位符映射
+    //     一次建立即可——step0 为 noAI（brainstorm/execute/verify 的 step1「进度确认」，
+    //     2026-09-07）时首个可见步顺延，按 defSteps 计算（坑同 scan quick 档 noAI preflight）；
     //   - scan 阶段所有 step：scan 的 profileDirectives 本就每步注入（见下方 L917），平台路径
     //     约束也需每步可见——否则 quick profile 的 step0 是 noAI preflight（自动执行），run scan
     //     输出的首个可见 step 是 step1，会漏掉 specDir 路径，导致平台模式写入约束丢失。
     //     后续 step 靠 changeDir header + footer 平台规则（L1077+）维持，platformDirectives
     //     每步重复约 500 tokens 仅在 scan（步数有限）可接受。
-    if (stepIndex === 0 || stageName === 'scan') {
+    if (stepIndex === firstRenderableIdx || stageName === 'scan') {
       promptText = platformDirectives.join('\n') + '\n\n' + promptText
     }
   } else {
@@ -506,6 +588,88 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     promptText = promptText.replace(/\{SCAN_FACTS\}/g, factsInjected)
   }
 
+  // ── 机械事实注入三件（2026-09-07 注入缺口批次）：{LOCAL_COMMANDS} / {GIT_DIRTY} / {TASKS_CHECKBOX} ──
+  // CLI 渲染 prompt 时已能确定性拿到的机械事实，替代 agent 各自跑一趟 cat local.yaml /
+  // git status / 手数勾选（全流程 7+ 处步骤的高频机械读）。全部 fail-soft：异常注入单行
+  // 说明，不留残留占位符；替换后占位符即消失（不存在的档位自然零输出）。
+
+  // ① {LOCAL_COMMANDS}：local.yaml commands 段原文（brainstorm/plan/execute/verify/quick 多步消费）
+  if (promptText.includes('{LOCAL_COMMANDS}')) {
+    let localBlock = ''
+    try {
+      const lcSpecBase = resolvePromptSpecBase(platformOpts, cwd)
+      const localPath = join(lcSpecBase, 'local.yaml')
+      if (existsSync(localPath)) {
+        const lcLines = String(readFileSync(localPath, 'utf8')).replace(/\r\n?/g, '\n').split('\n')
+        const start = lcLines.findIndex(l => /^commands:\s*(#.*)?$/.test(l))
+        if (start !== -1) {
+          const body = []
+          for (let i = start + 1; i < lcLines.length && !/^\S/.test(lcLines[i]); i++) body.push(lcLines[i])
+          // unavailable 标记的条目按未配置语义剔除行（与 extractTestCommand 同口径）
+          const avail = body.filter(l => !/^\s*[\w.-]+:\s*['"]?unavailable['"]?\s*(#.*)?$/i.test(l))
+          const trimmed = avail.join('\n').trim()
+          localBlock = trimmed
+            ? 'commands:\n' + trimmed
+            : '（local.yaml 存在但 commands 段为空——可跑 `sillyspec local detect` 补默认骨架）'
+        } else {
+          localBlock = '（local.yaml 存在但无 commands 段——可跑 `sillyspec local detect` 补默认骨架）'
+        }
+      } else {
+        localBlock = '（未配置 local.yaml——先跑 `sillyspec local detect` 生成骨架，以命令输出为准）'
+      }
+    } catch (e) {
+      localBlock = `（构建命令注入失败：${e.message}——可自行读 local.yaml）`
+    }
+    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 = ''
+    try {
+      const { gitQuiet } = await import('../git-helper.js')
+      // gitQuiet 返回裸 string（失败 null）——非 safeGit 的 {value,error} 形状
+      const lines = String(gitQuiet(cwd, ['status', '--porcelain']) || '').split('\n').filter(Boolean)
+      dirtyBlock = lines.length === 0
+        ? '（工作区干净，无脏文件）'
+        : lines.slice(0, 40).join('\n') + (lines.length > 40 ? `\n（…共 ${lines.length} 行，超出 40 行截断——完整清单可自行跑 git status --porcelain）` : '')
+    } catch (e) {
+      dirtyBlock = `（脏文件注入失败：${e.message}——可自行跑 git status --porcelain）`
+    }
+    promptText = promptText.replace(/\{GIT_DIRTY\}/g, dirtyBlock)
+  }
+
+  // ③ {TASKS_CHECKBOX}：tasks.md 任务勾选状态投影（verify 逐项检查步消费——省 agent 手数）
+  if (promptText.includes('{TASKS_CHECKBOX}')) {
+    let tasksBlock = ''
+    try {
+      const tcSpecBase = resolvePromptSpecBase(platformOpts, cwd)
+      const tasksPath = changeName ? join(tcSpecBase, 'changes', changeName, 'tasks.md') : null
+      if (tasksPath && existsSync(tasksPath)) {
+        const re = /^(\s*[-*]\s+\[([ xX])\]\s+task-\d+.*)$/
+        const rows = String(readFileSync(tasksPath, 'utf8')).replace(/\r\n?/g, '\n').split('\n')
+          .map(l => l.match(re)).filter(Boolean).map(m => m[1].trim())
+        const checked = rows.filter(r => /\[x\]/i.test(r)).length
+        tasksBlock = rows.length === 0
+          ? '（tasks.md 无 task-NN checkbox 行）'
+          : `已勾 ${checked}/${rows.length}：\n` + rows.slice(0, 60).join('\n') + (rows.length > 60 ? `\n（…共 ${rows.length} 条，超出 60 条截断）` : '')
+      } else {
+        tasksBlock = '（tasks.md 不存在——跳过勾选对照）'
+      }
+    } catch (e) {
+      tasksBlock = `（勾选状态注入失败：${e.message}——可自行读 tasks.md）`
+    }
+    promptText = promptText.replace(/\{TASKS_CHECKBOX\}/g, tasksBlock)
+  }
+
   // 决策防复潮注入（W1.1 第 3 点，task-04，FR-05）：brainstorm「加载项目上下文」Step2 的
   // {DECISION_HITS} → matchKnowledge decisionHits——命中 rejected 条目时渲染「否决决策提示」段
   // （ID/标题/否决理由/复潮条件），无命中替换为空串零输出（不留残留占位符）；注入结果同步落
@@ -712,22 +876,10 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     }
   }
 
-  // 三主阶段 Step1「进度确认」快照注入（2026-09-05 全流程审计）：progress show 的核心信息
-  // （阶段/步骤位置/推进态）CLI 渲染 prompt 时已全部在手——注入替代 agent 跑一趟 CLI 的
-  // 工具往返（progress show 全量输出还很长）。fail-soft：异常降级为自查指引。
-  if (['brainstorm', 'execute', 'verify'].includes(stageName) && promptText.includes('{PROGRESS_SNAPSHOT}')) {
-    try {
-      const done = steps.filter(s => s.status === 'completed').length
-      const waiting = steps.filter(s => s.status === 'waiting').length
-      const snapshot =
-        `- 变更：${changeName || '（未知）'}\n` +
-        `- 阶段：${stageName}（CLI 已路由到本阶段，无需再跑 progress show 确认）\n` +
-        `- 步骤：${done}/${steps.length} 已完成${waiting > 0 ? `，${waiting} 个等待中` : ''}；当前推进到第 ${stepIndex + 1} 步`
-      promptText = promptText.split('{PROGRESS_SNAPSHOT}').join(snapshot)
-    } catch (e) {
-      promptText = promptText.split('{PROGRESS_SNAPSHOT}').join('（快照注入失败：' + e.message + '——可运行 sillyspec progress show 自查）')
-    }
-  }
+  // 三主阶段 Step1「进度确认」快照注入（2026-09-05 全流程审计）已随 step1 整体 noAI 化退役
+  // （2026-09-07）：brainstorm/execute/verify 的 step1 不再渲染 prompt，快照改由
+  // run/progress-confirm.js 的 progressConfirm 动作 console 直出（占位符 {PROGRESS_SNAPSHOT}
+  // 无消费者，注入分支删除）。
 
   // execute Step「确认 worktree 路径」meta 注入（2026-09-05 全流程审计）：worktree meta 由 CLI
   // 读出直接注入，agent 省一趟 worktree meta 工具往返；工具链可用性检查（真实工作）仍归 agent。
@@ -840,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
@@ -888,9 +1066,9 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   }
 
   // 完成契约(事前预知):该 stage 的机械校验通过条件,从 stage-contract-spec.js manifest 渲染,
-  // 与 CLI 完成校验严格同源(事前给的 == 事后查的)。仅 step0 注入(与 persona/guardrails 同模式,
-  // 一次建立即可;后续步靠 context 保留)。
-  if (stepIndex === 0) {
+  // 与 CLI 完成校验严格同源(事前给的 == 事后查的)。仅首个 agent 可见步注入(与 persona/guardrails
+  // 同模式,一次建立即可;后续步靠 context 保留)。
+  if (stepIndex === firstRenderableIdx) {
     const stageContract = renderStageContract(stageName)
     if (stageContract) {
       promptText = `${promptText}\n\n${stageContract}`
@@ -898,10 +1076,10 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   }
 
   console.log(promptText)
-  // 铁律拆分（W3 token 效率）：通用流程纪律（文档优先/不跳步/不编造命令）只在首步注入——
+  // 铁律拆分（W3 token 效率）：通用流程纪律（文档优先/不跳步/不编造命令）只在首个 agent 可见步注入——
   // 每步重复 ~800B 纯耗 context。但【平台写入规则 + 路径规则】是安全关键（防写错目录/绕过 Write），
   // 且依赖 changeName/platformOpts，必须【每步注入】（context 压缩丢失会让 agent 越界写源码）。
-  if (stepIndex === 0) {
+  if (stepIndex === firstRenderableIdx) {
     console.log(`\n### ⚠️ 铁律`)
     console.log('- 文档优先：代码产出必须先有对应的设计/规范文档支撑。')
     console.log('- 聚焦本步骤：只执行本步骤描述的操作并完整做完；自行扩展或跳步会破坏状态机推进，后续步骤再做后续事。')
@@ -949,21 +1127,42 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   // archive-batch-31-tool-notes ②：通用 --done 模板不带该 flag，agent 照抄执行撞
   // 「请添加 --confirm」确认门，误以为参数没带。
   const confirmFlag = step.requiresConfirm === true ? ' --confirm' : ''
+  // auto driver（2026-09-08-auto-driver D-002/P1-③）：auto 模式下命令一律 run auto 形态——
+  // 与 SS-META 的 doneCommand 同源（同一 cmdStage 变量），消灭「正文 run <stage> / 元数据 run auto」双命令
+  const cmdStage = autoMeta ? 'auto' : stageName
+  const doneCommand = `sillyspec run ${cmdStage} --done${confirmFlag}${changeFlag} --output "你的摘要"`
   if (requiresWait) {
     console.log(`本步骤必须等待用户输入，不能直接 --done：`)
-    console.log(`sillyspec run ${stageName} --wait --reason "${step.waitReason || '等待用户输入'}" --options "${(step.waitOptions || ['确认']).join(',')}"${changeFlag} --output "你的问题/方案摘要"`)
+    console.log(`sillyspec run ${cmdStage} --wait --reason "${step.waitReason || '等待用户输入'}" --options "${(step.waitOptions || ['确认']).join(',')}"${changeFlag} --output "你的问题/方案摘要"`)
     console.log(``)
     console.log(`用户回答后执行：`)
-    console.log(`sillyspec run ${stageName} --continue --answer "用户回答"${changeFlag}`)
+    console.log(`sillyspec run ${cmdStage} --continue --answer "用户回答"${changeFlag}`)
     console.log(``)
     console.log(`收到回答并完成本步骤总结后，再执行：`)
   } else if (mayNeedWait) {
     console.log(`如果需要用户决策（选择方案/确认设计等）：`)
-    console.log(`sillyspec run ${stageName} --wait --reason "${step.waitReason || '等待原因'}" --options "${(step.waitOptions || ['选项1', '选项2']).join(',')}"${changeFlag} --output "你的摘要"`)
+    console.log(`sillyspec run ${cmdStage} --wait --reason "${step.waitReason || '等待原因'}" --options "${(step.waitOptions || ['选项1', '选项2']).join(',')}"${changeFlag} --output "你的摘要"`)
     console.log(``)
     console.log(`如果不需要用户决策，正常完成：`)
   }
-  console.log(`sillyspec run ${stageName} --done${confirmFlag}${changeFlag} --input "用户原始需求/反馈" --output "你的摘要"`)
+  console.log(doneCommand + (autoMeta ? '' : ' --input "用户原始需求/反馈"'))
+
+  // ── SS-META 机器可读元数据块（change: 2026-09-08-auto-driver，D-002@v1，FR-01）──
+  // 仅 auto 模式（autoMeta 非空）渲染：单行 HTML 注释内 JSON，agent 低噪可读、脚本一行正则
+  // 可提取（<!--SS-META:(.*)-->）。requiresUser 四源见上方纯函数；doneCommand 与正文同源。
+  if (autoMeta) {
+    const meta = {
+      stage: stageName,
+      stepIndex: stepIndex + 1,
+      stepName: step.name,
+      requiresUser: requiresWait || mayNeedWait || step.requiresConfirm === true,
+      doneCommand,
+      waitHint: (requiresWait || mayNeedWait)
+        ? 'requiresUser=true：先与用户交互（wait/continue 或 --wait-interactive 直通），再 done'
+        : '直接执行任务后逐字跑 doneCommand',
+    }
+    console.log('<!--SS-META:' + JSON.stringify(meta) + '-->')
+  }
 }
 /**
  * 替换 prompt 文本中的路径根占位符 {SPEC_ROOT}/{DOCS_ROOT}/{PROJECTS_ROOT}/

package/src/run/quick-audit.js

@@ -209,12 +209,15 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
  * npm test + npm run lint」从 agent 自律下沉为 CLI 卡点。
  *
  * 语义（对齐规则 8 + verify-postcheck 既有降级哲学）：
- *   - changedFiles 未触及 src/ 或 test/（纯 doc/配置改动）→ skip（不跑不阻断）
+ *   - 变更文件未触及 src/ 或 test/（纯 doc/配置改动）→ skip（不跑不阻断）
  *   - 触及 → 亲自执行 local.yaml 的 commands.test / commands.lint（复用 verify 阶段
  *     对账引擎 runVerifyTestCheck/runVerifyLintCheck，含 test_strategy/known_failures/
  *     超时语义）；未配置命令 → 内部 skipped，不阻断（兼容无测试项目）
  *   - 任一实测 failed → fail（调用方阻断 --done，step 回 pending）
  *   - 逃生门：SILLYSPEC_QUICK_TEST_GATE=skip 显式跳过（CI/特殊场景，审计留痕）
+ *   - 倒推 B 模式兜底（2026-09-07，quick-f9138c2f 实证）：代码先行会话的文件全部早于
+ *     启动时间窗 → 审计 changedFiles 为空 → 此前静默 skip；--files 声明边界
+ *     （declaredFiles = guard.allowedFiles）明确触及 src/test 时实测仍应跑。
  *
  * verify-postcheck 顶层 import 链较重（contract-matrix 等），且本函数仅 quick --done
  * 收尾路径调用——用动态 import，不进 run 命令通用启动路径（与上方 @inquirer/prompts 同款纪律）。
@@ -222,18 +225,22 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
  * @param {object} opts
  * @param {string} opts.cwd - 仓库根（命令执行 cwd）
  * @param {string} opts.specBase - .sillyspec 目录（local.yaml 读取源，信任边界见 runVerifyTestCheck SEC-02 注释）
- * @param {string[]} [opts.changedFiles] - 审计口径的本轮变更文件（仓库根相对 POSIX 路径；空/null → skip）
+ * @param {string[]} [opts.changedFiles] - 审计口径的本轮变更文件（仓库根相对 POSIX 路径；空/null → 回退 declaredFiles）
+ * @param {string[]} [opts.declaredFiles] - 会话声明边界（guard.allowedFiles；changedFiles 为空时的兜底判定源）
  * @param {string} [opts.changeName] - quick 会话名（evidence-auto 策略解析用）
  * @returns {Promise<{action:'pass'|'fail'|'skip', failed:string[], reason:string, test:object|null, lint:object|null}>}
  */
-export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], changeName = null }) {
+export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], declaredFiles = [], changeName = null }) {
   if (process.env.SILLYSPEC_QUICK_TEST_GATE === 'skip') {
     return { action: 'skip', failed: [], reason: 'SILLYSPEC_QUICK_TEST_GATE=skip 显式跳过（审计留痕）', test: null, lint: null }
   }
-  const files = Array.isArray(changedFiles) ? changedFiles : []
+  const audited = Array.isArray(changedFiles) ? changedFiles : []
+  // 倒推 B 模式兜底：审计口径为空时回退声明边界（文件早于会话启动被基线吸收的场景）
+  const files = audited.length > 0 ? audited : (Array.isArray(declaredFiles) ? declaredFiles : [])
+  const fileSource = audited.length > 0 ? '审计' : (files.length > 0 ? '声明边界兜底（倒推 B：文件早于会话启动被基线吸收）' : '无')
   const codeFiles = files.filter(f => typeof f === 'string' && (f.startsWith('src/') || f.startsWith('test/')))
   if (files.length === 0) {
-    return { action: 'skip', failed: [], reason: '无变更文件清单（brownfield 无 guard 或空审计），跳过', test: null, lint: null }
+    return { action: 'skip', failed: [], reason: `无变更文件清单（${fileSource}口径均空——brownfield 无 guard 或空审计），跳过`, test: null, lint: null }
   }
   if (codeFiles.length === 0) {
     return { action: 'skip', failed: [], reason: `纯 doc/配置改动（${files.length} 个文件均未触及 src/test，规则 8 语义跳过 test+lint）`, test: null, lint: null }

package/src/run/scan-profile.js

@@ -9,8 +9,8 @@
  *   - executeScanPostcheck 原冗余动态 import('fs'/'path'/'child_process') 删除，改顶部静态（execSync 实际未直接用，纯遗留）
  */
 import { join, basename, extname } from 'node:path'
-import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs'
-import { safeGit } from './shared.js'
+import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync, unlinkSync, readFileSync } from 'node:fs'
+import { safeGit, resolveRuntimeRoot } from './shared.js'
 import { SCAN_REQUIRED_DOCS } from '../constants.js'
 
 /**
@@ -327,6 +327,24 @@ export async function executeScanResumeCheck(cwd, platformOpts) {
     console.log(`  📂 ${p}: ${states.join(' ')} ${facts}`)
   }
   console.log('')
+
+  // IR 增量回灌 advisory（change: 2026-09-07-ir-hardening，D-006@v1，FR-03）：读
+  // .runtime/last-delta.json（归档/delta 补跑写入的最近变更快照），14 天窗口内提示本轮
+  // scan 优先核对其涉及模块——advisory 不阻断不改变步骤结构；缺失/过期/解析失败静默。
+  try {
+    const sidecarPath = join(resolveRuntimeRoot(platformOpts, specBase), 'last-delta.json')
+    if (existsSync(sidecarPath)) {
+      const sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8'))
+      const ageMs = Date.now() - Date.parse(sidecar.updatedAt || '')
+      const FOURTEEN_DAYS = 14 * 24 * 60 * 60 * 1000
+      if (Number.isFinite(ageMs) && ageMs >= 0 && ageMs <= FOURTEEN_DAYS
+        && Array.isArray(sidecar.affectedModules) && sidecar.affectedModules.length > 0) {
+        console.log(`🔁 增量回灌提示（上次归档变更 ${sidecar.change}，${new Date(sidecar.updatedAt).toISOString().slice(0, 10)}）：`)
+        console.log(`   其涉及模块 ${sidecar.affectedModules.join('、')} 的文档与 staleRefs 本轮 scan 优先核对（advisory，不据此跳过其他模块）`)
+        console.log('')
+      }
+    }
+  } catch { /* sidecar 读取/解析失败静默跳过（advisory 缺席零影响） */ }
 }
 
 /**

package/src/run/shared.js

@@ -107,19 +107,24 @@ export function resolvePromptIncludes(text) {
 export function resolveSpecDir(cwd, opts = {}) {
   if (opts.specDir) return resolve(opts.specDir)
   const home = os.homedir()
-  let dir = resolve(cwd)
+  const origin = resolve(cwd)
+  const originBelowHome = origin.startsWith(home + sep) // 严格子目录，不含 home 自身
+  let dir = origin
+  let passedHome = false
   while (true) {
-    // home 拒绝守卫：cwd 本身就在 home 下（含恰好在 home 跑命令）时，home 层不匹配 .sillyspec，
-    // 继续向上只会离项目更远（home 的父目录不可能有真项目 .sillyspec），直接回退 cwd/.sillyspec。
-    if (dir !== home) {
+    // home 拒绝守卫：起点在 home 子树内时，home 层不检查 .sillyspec，
+    // 防止 home 子目录遍历经过 home 误命中 ~/.sillyspec；
+    // passedHome：经过 home 后不再检查（覆盖遍历到真实 home 的场景）。
+    if (!(passedHome || (dir === home && originBelowHome))) {
       const candidate = join(dir, '.sillyspec')
       if (existsSync(candidate)) return candidate
     }
+    if (dir === home) passedHome = true
     const parent = dirname(dir)
     if (parent === dir) break
     dir = parent
   }
-  return join(resolve(cwd), '.sillyspec')
+  return join(origin, '.sillyspec')
 }
 
 /**
@@ -333,6 +338,8 @@ export function resolveQuickSessionsDir(platformOpts, localSpecBase) {
 // GHOST_EMPTY_DIR_STALE_MS 同口径（7 天）——正常并发会话间隔在分钟/小时级，7 天未收尾的
 // 会话按僵尸处理，防崩溃残留的 guard 永久「认领」文件侵蚀危险门。
 const FOREIGN_SESSION_STALE_MS = 7 * 24 * 60 * 60 * 1000
+// 空壳会话点名宽限期：零步骤完成但启动未满此时长的不列（进行中会话的正常起步态）
+const EMPTY_SHELL_GRACE_MS = 10 * 60 * 1000
 
 /**
  * 枚举其他 active quick 会话的显式文件声明（坑 foreign-session-declared-false-block）。
@@ -419,6 +426,9 @@ export function detectEmptyShellQuickSessions(platformOpts, localSpecBase, curre
       if (!guard || !guard.startedAt) continue
       const startedAtMs = Date.parse(guard.startedAt)
       if (!Number.isFinite(startedAtMs) || nowMs - startedAtMs > FOREIGN_SESSION_STALE_MS) continue
+      // 宽限期（2026-09-09 §7-4，会话实证：2 分钟前刚启动的进行中会话被点名疑似空壳）：
+      // 零步骤完成对刚起步的会话是正常态，不满 10 分钟不列（宁可漏报不误报的同款取向）。
+      if (nowMs - startedAtMs < EMPTY_SHELL_GRACE_MS) continue
       try {
         const p = pm.read(cwd, sessionName)
         if (!p || !p.stages) continue
@@ -467,6 +477,16 @@ export function writePlatformPointer(cwd, platformOpts, extra = {}) {
     console.warn(`⚠️ 检测到自指平台指针（repo-native junction 回环，specRoot 指回本地 .sillyspec），已跳过指针写入并按本地模式运行: ${platformOpts.specRoot}`)
     return false
   }
+  // temp 残留写侧守卫（2026-09-08 temp 投毒治理，防患于未然）：specRoot 在系统 temp 且
+  // 项目 cwd 不在 temp → 拒绝三写。真实平台 spec 根永不在 temp；此类组合只可能来自
+  // 测试/联调以临时 specRoot 在真实项目根跑平台模式命令——指针/声明一旦落盘，指针被
+  // 清理后残留声明会让全命令 fail-closed（读侧 isTempResidueSpecRoot 降级兜底已存在
+  // 的污染，此处从源头断新增）。cwd 同在 temp（套件隔离正常形态）不拦，平台模式
+  // 测试不受影响。
+  if (isTempResidueSpecRoot(cwd, platformOpts.specRoot)) {
+    console.warn(`⚠️ 拒绝写入平台指针：specRoot 指向系统 temp 目录（${platformOpts.specRoot}）而项目不在 temp 下——测试/联调残留特征，已跳过三写并按本地模式运行`)
+    return false
+  }
   // HUB-05：合并保留既有生命周期字段。scan 完成时指针被写入 status/completedAt/scanStatus
   //（complete-handlers），但下一次任何平台模式 run（含只读 --status）都会重写指针——
   // 恢复链只回填 specRoot 等四字段，不保留 status → 指针永远回 active、isPointerStale
@@ -564,6 +584,38 @@ export function isSelfReferentialSpecRoot(cwd, specRoot) {
   }
 }
 
+/**
+ * temp 残留 specRoot 判定（temp 投毒治理，2026-09-08：multi-agent-platform 工作台
+ * 「总览不可用」排障实证——Git Bash mktemp 临时 specRoot 的平台模式命令在真实项目根
+ * 写下指针+声明，指针随后被 cleanup/STALE 清理，声明按设计存活（唯一删除路径 =
+ * platform disconnect）→ 全命令 fail-closed，且 disconnect 会连带清 local.yaml
+ * platform 段误伤真实平台连接）。
+ *
+ * 判定：specRoot 位于系统 temp 目录 **且** cwd 不在 temp 下 → true。两个条件缺一不可：
+ * 真实平台的 spec 根永不在 temp（daemon 用 ~/.sillyhub/daemon/specs/{ws}，服务器用
+ * /data/spec-workspaces）；测试/联调的 temp specRoot 只允许配 temp 项目 cwd（套件隔离
+ * 正常形态，见 test/run-tests.mjs childEnv 与 platform-managed-declaration 夹具——
+ * cwd 与 spec 同在 temp 下时本函数返回 false，既有 fail-closed 测试语义不变）。
+ *
+ * 与 isSelfReferentialSpecRoot 并列为声明的两类「可证伪残留」：自指回环（repo-native
+ * junction 投毒）已有降级先例（run/command.js:429），本函数补 temp 残留这一类。
+ * 口径对齐 progress.js 指针路径的 temp 警告（resolve() 前缀比较，不 realpath——temp
+ * 判定是残留启发式，无需穿透 junction 的强一致）。
+ *
+ * @param {string} cwd - 项目根（与 isSelfReferentialSpecRoot 同基准）
+ * @param {string|null} [specRoot] - 平台 specRoot（可 null/undefined/空串）
+ * @returns {boolean} 是否 temp 残留（写侧应拒绝三写，读侧应降级本地并清理声明）
+ */
+export function isTempResidueSpecRoot(cwd, specRoot) {
+  if (!specRoot || typeof specRoot !== 'string') return false
+  const tmp = resolve(os.tmpdir())
+  const sr = resolve(specRoot)
+  if (sr !== tmp && !sr.startsWith(tmp + sep)) return false
+  const c = resolve(cwd)
+  if (c === tmp || c.startsWith(tmp + sep)) return false
+  return true
+}
+
 /**
  * 平台模式判定单一数据源（自指免疫，变更 2026-08-23-repo-native-spec-backfill）。
  *
@@ -769,7 +821,8 @@ export async function triggerPull(cwd, changeName, platformOpts = {}, opts = {})
     if (!sm._getPlatform()) return
     if (_autoPullRecently(cwd)) return
     _stampAutoPull(cwd)
-    await raceWithAbort((sig) => sm.pull(changeName, { skipIfLocalDirty: true, signal: sig.signal }), opts.timeoutMs ?? AUTO_PULL_TIMEOUT_MS)
+    // autoPull：噪音闸标识（sync.js pull 的失败 warn 走跨进程静默窗口，见 sync-noise.js）
+    await raceWithAbort((sig) => sm.pull(changeName, { skipIfLocalDirty: true, signal: sig.signal, autoPull: true }), opts.timeoutMs ?? AUTO_PULL_TIMEOUT_MS)
   } catch (e) {
     // pull 失败静默跳过（Best Effort，失败不影响正确性）
     console.warn('⚠️ 拉取失败:', e.message)
@@ -808,9 +861,10 @@ export async function triggerPullActiveChange(cwd, platformOpts = {}) {
   }
   if (!cn) return
   // 已确认连接 + 单活跃变更，调 pull（自动注入 2s 熔断 + abort（HUB-09）；skipIfLocalDirty 保守守卫
-  // 同 triggerPull——本地脏时跳过 import，防平台旧快照覆盖本地领先进度，ql-20260818-008）
+  // 同 triggerPull——本地脏时跳过 import，防平台旧快照覆盖本地领先进度，ql-20260818-008）。
+  // autoPull：噪音闸标识（sync.js pull 的失败 warn 走跨进程静默窗口，见 sync-noise.js）
   try {
-    await raceWithAbort((sig) => sm.pull(cn, { skipIfLocalDirty: true, signal: sig.signal }), AUTO_PULL_TIMEOUT_MS)
+    await raceWithAbort((sig) => sm.pull(cn, { skipIfLocalDirty: true, signal: sig.signal, autoPull: true }), AUTO_PULL_TIMEOUT_MS)
   } catch (e) {
     console.warn('⚠️ 拉取失败:', e.message)
   }
@@ -879,8 +933,9 @@ export function parsePorcelainPath(line) {
 }
 
 /**
- * quick 自身写入的 .sillyspec/ 元数据判定（auditQuickCompletion 审计 与 QUICKLOG「文件：」行回填
- * 单源）。回填文件行时复用：review.changedFiles 含这些元数据时过滤掉，只留真实业务文件。
+ * quick 自身写入的 .sillyspec/ 元数据判定（auditQuickCompletion 审计豁免的单一真相源）。
+ * 注意：QUICKLOG「文件：」行回填**不再直接复用**本谓词——记录面与审计豁免面已分叉
+ * （模块卡 + changelog sidecar 审计照旧放行、但要进文件行），见 isQuicklogFileLineNoise。
  *
  * 归类口径：
  * - quicklog/.runtime/modules/_module-map/knowledge-uncategorized 等 quick 自身产物 → 元数据
@@ -889,7 +944,7 @@ export function parsePorcelainPath(line) {
  *
  * 「并发工作 vs 偷建变更」的意图软判定留给 sillyhub，确定性校验只做路径归类。
  *
- * @param {string} p 文件路径（容错 \\ / 混用）
+ * @param {string} p 文件路径（容错 \ / 混用）
  * @param {string[]} [linkedChanges] 关联变更名列表（影响 changes/ 归类）
  * @returns {boolean} true=quick 元数据，应从业务文件列表过滤掉
  */
@@ -910,6 +965,24 @@ export function isQuickMetadata(p, linkedChanges = []) {
   return false
 }
 
+/**
+ * QUICKLOG「文件：」行回填过滤——isQuickMetadata 的**记录面**变体（2026-09-08 用户反馈①：
+ * 审计按 .sillyspec/ 放行规则整体豁免没问题，但模块卡 + changelog sidecar 恰是收尾必改项，
+ * 被同一谓词从文件行滤掉后每回都得手工补录）。审计豁免面（isQuickMetadata）与记录面在此
+ * 分叉：quick 自身元数据（quicklog/.runtime/知识库未归类）照旧不入文件行，但本 quick 实际
+ * 改动的模块卡（`modules/<id>.md`）与 sidecar（`modules/<id>.changelog.md`，同被上方
+ * `[^/]+\.md$` 覆盖）保留——它们是真实收尾工作的一部分。`_module-map.yaml` 仍滤：CLI
+ * （module-resolve）维护的索引，非 agent 手工改动。
+ * @param {string} p 文件路径（容错 \ / 混用）
+ * @param {string[]} [linkedChanges] 关联变更名列表（透传 isQuickMetadata）
+ * @returns {boolean} true=元数据噪音，应从「文件：」行过滤掉
+ */
+export function isQuicklogFileLineNoise(p, linkedChanges = []) {
+  const file = String(p).replace(/\\/g, '/')
+  if (/^\.sillyspec\/docs\/[^/]+\/modules\/[^/]+\.md$/.test(file)) return false
+  return isQuickMetadata(p, linkedChanges)
+}
+
 // 危险文件清单（auditQuickCompletion 危险门与 predictProtectedQuickFiles 预告共用单一真相源）。
 // SillySpec 核心流程代码。W6 重构后 src/run.js（23 行 barrel）/ src/progress.js（facade）
 // 把真正逻辑下沉到 src/run/、src/progress/ 子目录——旧的精确文件名匹配