sillyspec 3.28.2 → 3.28.3

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,6 +377,9 @@ 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 {
       throw new Error(`noAI 步骤 ${steps[currentIdx].name} 的未知 _cliAction: ${_cliAction}——请在 complete.js 注册对应分支`)
     }
@@ -483,6 +527,11 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       }
     }
 
+    // 主阶段完成钉 currentStage（troubleshooting #56 根因修复，2026-09-08）：
+    // `run <stage> --done` 直达完成不经过裸 run 入口（唯一写点 stage.js:227），
+    // currentStage 停留旧阶段 → 下游 checkTransition 用 stale prevStage 误拦
+    // （实证：verify 全 --done 完成后归档报 execute→archive）。与入口写点同语义：辅助阶段不写。
+    if (!AUXILIARY_STAGES.includes(stageName)) progress.currentStage = stageName
     stageData.status = 'completed'
     stageData.completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
     progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
@@ -606,7 +655,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     }
   }
 
-  const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const defSteps = await getStageStepsAutoAware(stageName, cwd, progress, platformOpts?.specRoot || null)
   console.log(`✅ Step ${currentIdx + 1}/${steps.length} 完成：${steps[currentIdx].name}\n`)
 
   // Workflow post_check（W6 Step6 抽至 complete-handlers.js handleWorkflowPostCheck）
@@ -1007,7 +1056,7 @@ export async function waitStep(pm, progress, stageName, cwd, outputText, waitRea
 
   // maxWaitRounds 硬上限：达到后拒绝继续 --wait
   const currentStep = stageData.steps[currentIdx]
-  const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const defSteps = await getStageStepsAutoAware(stageName, cwd, progress, platformOpts?.specRoot || null)
   const stepDef = defSteps?.[currentIdx] || {}
   const maxWaitRounds = currentStep.maxWaitRounds ?? stepDef.maxWaitRounds
   const currentWaitRound = currentStep.waitRound || 0
@@ -1121,7 +1170,7 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
   } else {
     currentIdx = waitingSteps[0].idx
   }
-  const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const defSteps = await getStageStepsAutoAware(stageName, cwd, progress, platformOpts?.specRoot || null)
   const currentStepDef = defSteps?.[currentIdx] || {}
   const currentStep = stageData.steps[currentIdx]
   const isRepeatableWait = currentStepDef.repeatableWait === true || currentStep.repeatableWait === true
@@ -1219,6 +1268,11 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
   if (nextPendingIdx === -1 && nextWaitingIdx === -1) {
     stageData.status = 'completed'
     stageData.completedAt = now
+    // 主阶段完成钉 currentStage（troubleshooting #56 根因修复，2026-09-08）：
+    // `run <stage> --done` 直达完成不经过裸 run 入口（唯一写点 stage.js:227），
+    // currentStage 停留旧阶段 → 下游 checkTransition 用 stale prevStage 误拦
+    // （实证：verify 全 --done 完成后归档报 execute→archive）。与入口写点同语义：辅助阶段不写。
+    if (!AUXILIARY_STAGES.includes(stageName)) progress.currentStage = stageName
     // persist _write 移到 completeStageGates 成功之后（task-03 / review-2026-08-09 #2）：gate 异常/失败 → rollback 回 in-progress 落盘，此处未到 _write，DB 不留假 completed。
     // 阶段完成收尾共享管线（含 execute worktree cleanup），消除 continueStep 完成分支绕过 gate 的 S2（task-01 抽出）。
     // gate 失败已 rollback，early-return 跳过下方"阶段已完成/下一步"提示（与 completeStep 同语义）。
@@ -1303,7 +1357,7 @@ export async function skipStep(pm, progress, stageName, cwd, changeName, platfor
     process.exit(1)
   }
 
-  const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
+  const defSteps = await getStageStepsAutoAware(stageName, cwd, progress, platformOpts?.specRoot || null)
   const stepDef = defSteps ? defSteps[currentIdx] : null
   if (stepDef && !stepDef.optional) {
     console.error(`❌ 步骤 "${steps[currentIdx].name}" 不可跳过`)

package/src/run/gates.js

@@ -674,13 +674,15 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     // 声明=scope creep）启发式噪音面大（并行 WIP 剔除后仍可能有工具产物），WARNING 放行留审计；
     // skipped/degraded（无 task 卡 / 全无声明 / git 不可用）降级不误红（存量变更零红门禁）。
     // 阻断形态照 runVerifyTestCheck 先例：逐条列 task + path + 修复提示 + rollbackCompletionAndReturn。
-    const { reconcileTargetFiles } = await import('../verify-postcheck.js')
+    const { reconcileTargetFiles, isStrictChange } = await import('../verify-postcheck.js')
     const reconcileRuntimeRoot = resolveRuntimeRoot(platformOpts, specBase)
     const reconcileCheck = reconcileTargetFiles({
       cwd, specBase, changeName,
       // runtimeRoot 口径与上方 parity 对账同源（B3 apply-pathspec 兜底源在此根下；平台模式下
       // specBase 与 .runtime 分离，不传会读不到兜底清单 → 假降级）
       runtimeRoot: reconcileRuntimeRoot,
+      // IR 严格档（2026-09-07-ir-hardening D-003@v1）：主仓卡全零声明 → strictViolation → ERROR
+      strictMode: isStrictChange({ pm, cwd, changeName }),
     })
     const reconcileEnvelope = buildReconcileTargetFilesEnvelope(reconcileCheck)
     const reconcileBlocked = printReconcileTargetFilesCheck(reconcileCheck, reconcileEnvelope)
@@ -705,6 +707,9 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
       // 的锚点产物实际都在 changeDir，此参为统一传参签名对齐预留，口径一处定义不二算
       cwd, specBase, changeName,
       runtimeRoot: reconcileRuntimeRoot,
+      // IR 严格档（2026-09-07-ir-hardening D-002@v1）：created_at ≥ IR_STRICT_SINCE 的变更
+      // 探针子节全缺 = ERROR（存量 skip 语义零变化）；fail-open（读不到 → false 落豁免）
+      strictMode: isStrictChange({ pm, cwd, changeName }),
     })
     const probeEnvelope = buildProbeConsistencyEnvelope(probeCheck)
     const probeBlocked = printProbeConsistencyCheck(probeCheck, probeEnvelope)
@@ -1357,6 +1362,14 @@ export function printReconcileTargetFilesCheck(r, envelope = buildReconcileTarge
     console.warn(`   对账口径 actual=${(r.sources || []).join(' + ') || 'n/a'}（③类误报先核对 sources 与并行会话剔除提示）。`)
     return false
   }
+  // IR 严格档（2026-09-07-ir-hardening D-003）：strictViolation → ERROR 阻断（与②类同处置）
+  if (r.status === 'skipped' && r.strictViolation) {
+    console.error(`
+❌ target_files 对账阻断：${r.skipReason}`)
+    console.error(`   ${r.strictViolation.message}`)
+    console.error(`   信封 code: ${r.strictViolation.code}`)
+    return true
+  }
   // 降级（skipped/degraded）：WARNING 放行，skipReason 一句话（存量卡/git 不可用，不误红）
   if (r.status === 'skipped' || r.status === 'degraded') {
     console.warn(`\n⚠️  target_files 对账${r.status === 'degraded' ? '降级' : '跳过'}（不阻断）：${r.skipReason}`)
@@ -1385,6 +1398,12 @@ export function printReconcileTargetFilesCheck(r, envelope = buildReconcileTarge
 export function buildProbeConsistencyEnvelope(r) {
   const blocked = r.status === 'mismatch' && r.severity === 'error'
   const drifted = r.status === 'mismatch' && !blocked
+  // IR 严格档独立 code（2026-09-07-ir-hardening D-002）：首条 mismatch 携带
+  // probe_prefill_missing_strict 时路由专用 code（平台/上游按 code 分支可区分
+  // 「篡改预填段」与「从未生成预填段」两类 ERROR）
+  const strictMissing = blocked
+    && Array.isArray(r.mismatches) && r.mismatches.length > 0
+    && r.mismatches[0] && r.mismatches[0].code === 'probe_prefill_missing_strict'
   const supportedFixes = []
   if (blocked) {
     supportedFixes.push('如实重生成：跑 `sillyspec verify-probes --change <变更名> --init` 重新落盘机械预填段，再基于新预填段如实补写正文结论（删改预填段过门是 Step7 防篡改纪律红线）')
@@ -1396,7 +1415,8 @@ export function buildProbeConsistencyEnvelope(r) {
   }
   return {
     // code 机器路由键（task-02 JSDoc）：四状态→四 code，供平台/上游按 code 分支
-    code: blocked ? 'probe_consistency_mismatch'
+    code: strictMissing ? 'probe_prefill_missing_strict'
+      : blocked ? 'probe_consistency_mismatch'
       : drifted ? 'probe_consistency_drift'
       : (r.status === 'ok' ? 'probe_consistency_ok' : 'probe_consistency_skipped'),
     name: 'probe_consistency',

package/src/run/progress-confirm.js

@@ -0,0 +1,66 @@
+/**
+ * progressConfirm — 主流程 Step1「进度确认」的 noAI 动作（brainstorm / execute / verify）
+ * （2026-09-07 noAI 主流程首批；机制先例：scan 系 noAI 步 + planPostcheck，见 run/stage.js noAI 分支）
+ *
+ * noAI 化依据（step1 职责在历次加固后已全部机械化）：
+ *   - 阶段路由：`run <stage>` 显式调用即写 currentStage（run/stage.js D-003@v1），
+ *     阶段顺序违规由 checkTransition 拦截——原 prompt 的「阶段不符则停止」检查已残留化
+ *     （{PROGRESS_SNAPSHOT} 注入文案本就写着「CLI 已路由到本阶段」）；
+ *   - 进度摘要：快照三行（变更/阶段/步骤位置）由 CLI 注入，agent 的「输出当前进度摘要」
+ *     只是把注入内容复述一遍再 --done——整轮往返零判断增量；
+ *   - brainstorm 变更名检查：自动名在创建时 CLI 已打印 rename 提示（run/command.js），
+ *     此处机械复检一次模式命中；命中只打印 ⚠️ 建议（noAI 步的 console 输出仍在 CLI 工具
+ *     结果里，agent 可见、可在后续步骤与用户交互改名）——不 throw、不阻塞推进。
+ *   - execute 执行范围：$ARGUMENTS 是会话层信息，CLI 不掺入；本步只补 tasks 勾选计数
+ *     （readPlanCheckboxStatus 既有机器事实），范围以用户在会话中给出的为准。
+ *   - verify 测试提示：原 prompt 首段的「CLI 在 --done 统一跑测试」要点改为 console 提示。
+ *
+ * 输出纪律：只 console 打印（noAI 步不写 step output，与 scan 系动作一致）；
+ * 纯确认步无失败语义，不 throw。
+ */
+import { join } from 'node:path'
+
+/** brainstorm 自动生成变更名的模式（run/command.js:1083 `${date}-new-change-${hex}`） */
+const AUTO_CHANGE_NAME_RE = /^\d{4}-\d{2}-\d{2}-new-change-[a-f0-9]+$/
+
+/**
+ * 执行「进度确认」noAI 动作：打印进度快照 + 阶段专属机械提示。
+ *
+ * @param {object} opts
+ * @param {string} opts.stageName - brainstorm / execute / verify
+ * @param {string} opts.cwd
+ * @param {object} opts.stageData - progress.stages[stageName]（steps 数组）
+ * @param {string|null} opts.changeName
+ * @param {object|null} [opts.pm] - ProgressManager（execute 档 tasks 勾选计数用；缺省跳过该段）
+ */
+export function executeProgressConfirm({ stageName, cwd, stageData, changeName, pm = null }) {
+  const steps = Array.isArray(stageData?.steps) ? stageData.steps : []
+  const done = steps.filter(s => s.status === 'completed').length
+  console.log('📊 进度快照（CLI 注入，无需跑 progress show）：')
+  console.log(`   - 变更：${changeName || '（未知）'}`)
+  console.log(`   - 阶段：${stageName}（CLI 已路由到本阶段）`)
+  console.log(`   - 步骤：${done}/${steps.length} 已完成；本步已由 CLI 自动确认`)
+
+  if (stageName === 'brainstorm' && changeName && AUTO_CHANGE_NAME_RE.test(changeName)) {
+    console.log('')
+    console.log(`⚠️  变更名「${changeName}」疑似自动生成——建议与用户确认语义化名称后执行：`)
+    console.log(`   sillyspec change-rename ${changeName} <新名称>（勿用 mv，会漏改进度库引用）`)
+  }
+
+  if (stageName === 'execute' && pm && changeName) {
+    try {
+      const changeDir = join(pm._getSpecDir(cwd), 'changes', changeName)
+      const plan = pm.readPlanCheckboxStatus(changeDir)
+      if (plan && plan.total > 0) {
+        console.log(`   - 任务勾选：tasks ${plan.checked}/${plan.total}（执行范围以用户会话指定为准，未指定则全部 Wave）`)
+      }
+    } catch { /* 勾选计数 fail-soft：plan.md 缺失/解析失败不阻塞确认步 */ }
+  }
+
+  if (stageName === 'verify') {
+    console.log('')
+    console.log('💡 `run verify` 只下发指令不跑测试——全量测试由 CLI 在最后 --done 统一执行')
+    console.log('   （local.yaml 的 commands.test，同步对账可能耗时较长）；后续「运行测试和质量扫描」')
+    console.log('   步骤无需手动跑全量，只做 lint/静态检查 + 可选快速冒烟。')
+  }
+}

package/src/run/prompt.js

@@ -185,7 +185,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 +212,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 +267,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 +278,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 +421,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 +531,80 @@ 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)
+  }
+
+  // ② {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 +811,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。
@@ -888,9 +975,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 +985,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 +1036,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')
 }
 
 /**