sillyspec 3.28.0 → 3.28.3

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 {
@@ -477,6 +502,109 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     }
   }
 
+  // 机械事实底稿注入（IR P3c task-03，D-003@v1 三件套之三）：brainstorm「加载项目上下文」Step2
+  // 的 {SCAN_FACTS} → docs/<project>/scan/_facts.md 全文（scan facts CLI 确定性抽取的端点/依赖/
+  // 规模底稿）+ 红线一句（措辞对齐 scan 子代理先例 stages/scan.js——禁止重新 grep 发现底稿覆盖
+  // 的机械事实，冲突以底稿为准），探索期直接消费省 token。>15KB 按 UTF-8 字节截断并提示跑
+  // `sillyspec scan facts` 刷新（design R-04）；文件不存在/读取失败空注入（fail-soft，不留残留
+  // 占位符）。只挂 brainstorm：双重条件（stageName 判定 + 占位符仅存在于 brainstorm Step2
+  // prompt），与下方 buildModuleContextInjection（横跨 brainstorm/plan/execute 三阶段）相互独立。
+  if (stageName === 'brainstorm' && promptText.includes('{SCAN_FACTS}')) {
+    let factsInjected = ''
+    try {
+      const factsSpecBase = resolvePromptSpecBase(platformOpts, cwd)
+      const factsProjectName = dbProjectName || basename(cwd)
+      const factsPath = join(factsSpecBase, 'docs', factsProjectName, 'scan', '_facts.md')
+      if (existsSync(factsPath)) {
+        const factsBuf = readFileSync(factsPath) // Buffer：按 UTF-8 字节判 15KB 阈值
+        const FACTS_LIMIT = 15 * 1024
+        const factsBody = factsBuf.length > FACTS_LIMIT
+          ? factsBuf.subarray(0, FACTS_LIMIT).toString('utf8') +
+            `\n\n（⚠️ 底稿超过 15KB 已截断——完整内容可读 \`${factsPath}\`；底稿已过期时可跑 \`sillyspec scan facts\` 刷新）`
+          : factsBuf.toString('utf8')
+        factsInjected =
+          '\n\n### 🧾 机械事实底稿（scan facts CLI 抽取，docs/' + factsProjectName + '/scan/_facts.md 全文注入）\n\n' +
+          factsBody +
+          '\n\n⛔ 红线（同 scan 子代理先例）：禁止重新 grep 发现底稿覆盖的机械事实（端点/依赖/规模），冲突以底稿为准。\n'
+      }
+    } catch { /* fail-soft：读取失败空注入，不阻断 prompt 输出 */ }
+    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/标题/否决理由/复潮条件），无命中替换为空串零输出（不留残留占位符）；注入结果同步落
@@ -683,6 +811,35 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     }
   }
 
+  // 三主阶段 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。
+  if (stageName === 'execute' && promptText.includes('{WORKTREE_META}')) {
+    let metaInfo
+    try {
+      const { WorktreeManager } = await import('../worktree.js')
+      const wm = new WorktreeManager({ cwd })
+      const meta = changeName ? wm.getMeta(changeName) : null
+      if (meta && meta.worktreePath) {
+        const dirOk = existsSync(meta.worktreePath)
+        metaInfo =
+          `- worktreePath：${meta.worktreePath}\n` +
+          `- branch：${meta.branch || '（meta 未记录）'}\n` +
+          `- mode：${meta.mode || 'worktree'}\n` +
+          `- worktree 目录存在：${dirOk ? '是' : '否——in-place 模式属正常；worktree/native-worktree 模式缺失则停止并报错'}`
+      } else {
+        metaInfo = '（worktree meta 不可读——meta.json 不存在说明创建失败，停止并报错；可运行 sillyspec worktree meta ' + (changeName || '<change-name>') + ' 自查）'
+      }
+    } catch (e) {
+      metaInfo = '（注入失败：' + e.message + '——运行 sillyspec worktree meta 自查，meta.json 不存在则停止并报错）'
+    }
+    promptText = promptText.split('{WORKTREE_META}').join(metaInfo)
+  }
+
   // archive Step1「任务完成度检查」客观真相源注入：以 review.json verdict 算完成度，
   // 替代「机械数 plan.md checkbox」（checkbox 依赖 autoCheckPlanFromReviews 回填，runId marker /
   // review 缺失时回填静默 no-op，会停在未勾态导致完成度失真 → archive 误判「全未完成」）。
@@ -818,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}`
@@ -828,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('- 聚焦本步骤：只执行本步骤描述的操作并完整做完；自行扩展或跳步会破坏状态机推进，后续步骤再做后续事。')
@@ -879,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,9 @@
  *   - executeScanPostcheck 原冗余动态 import('fs'/'path'/'child_process') 删除，改顶部静态（execSync 实际未直接用，纯遗留）
  */
 import { join, basename, extname } from 'node:path'
-import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync } 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'
 
 /**
  * 估算源码规模（文件数 + 字节数）—— 跨平台 Node 遍历，替代 Unix `find`（原生 Windows 无 find，
@@ -130,19 +131,21 @@ export function buildQuickScanSteps() {
 当前为 quick profile（小项目自动判定 或 用户显式 --quick），一次性生成核心文档用于快速接入。
 
 ### 操作
-1. 读取项目结构和关键文件（package.json / pyproject.toml / README / 入口文件）
-2. 生成以下 4 份文档并写入 \`{DOCS_ROOT}/scan/\`：
+1. 先跑 \`sillyspec scan facts\`（CLI 确定性抽取端点/依赖/规模，产物 {DOCS_ROOT}/scan/_facts.md，零 token）——PROJECT/ARCHITECTURE 的技术栈与集成事实以底稿为准，不重复 grep 发现
+2. 读取项目结构和关键文件（package.json / pyproject.toml / README / 入口文件）
+3. 生成以下 4 份文档并写入 \`{DOCS_ROOT}/scan/\`：
    - **PROJECT.md** — 项目简介、技术栈、模块划分
    - **ARCHITECTURE.md** — 架构概览、模块关系、技术决策
    - **CONVENTIONS.md** — 代码风格、框架隐形规则
    - **STRUCTURE.md** — 目录树 + 模块说明
-3. 如发现子项目，注册到 \`{PROJECTS_ROOT}/\` 下
+4. 如发现子项目，注册到 \`{PROJECTS_ROOT}/\` 下
 
-每份文档 frontmatter 必须包含：\`author\`、\`created_at\`、\`scan_depth: quick\`（标记快速接入的浅层版本；后续深度扫描 --deep 会识别此标记并覆盖升级为完整文档）。
+每份文档正文第 1 行直接写中文标题；frontmatter（author / created_at / source_commit / updated_at / generator / scan_depth: quick——标记快速接入的浅层版本，后续深度扫描 --deep 会识别此标记并覆盖升级）**由 CLI 在终检时自动注入，你不需要写 frontmatter、也不要跑 git 取值**。
 
 ### ⛔ 硬约束
 - **严禁使用子代理（Agent/Task 工具）。** 所有文档在一个 turn 内完成。
 - 不要搜索 .sillyspec/ .claude/ .git/ node_modules/ dist/ build/
+- 关键事实（模块职责/技术栈组件/外部集成）须带反引号 path:line 引用（如 \`src/db.js:42\`，真实可核验——CLI postcheck 逐条核验）；不确定就不写行号，**禁止编造**
 - --output 只需要列出生成的文件名，不要写长篇总结
 
 ### 输出
@@ -219,8 +222,11 @@ export async function executeScanPreflight(cwd, platformOpts, scanProfile) {
  */
 export async function executeScanPostcheck(cwd, platformOpts, scanProfile) {
   // scan-postcheck.js 在 src/，本模块在 src/run/ → 退一层（真环依赖，保留动态 import）
-  const { runScanPostCheck, printScanPostCheckResult } = await import('../scan-postcheck.js')
+  const { runScanPostCheck, printScanPostCheckResult, stampScanDocHeaders } = await import('../scan-postcheck.js')
   const specDir = platformOpts?.specRoot || null
+  // ② frontmatter CLI 盖章（幂等，只补缺不覆盖）：quick 档注入含 scan_depth: quick
+  const stamped = stampScanDocHeaders({ cwd, specDir, mode: scanProfile?.mode })
+  if (stamped.fixed.length > 0) console.log(`  📝 frontmatter 已由 CLI 注入 ${stamped.fixed.length} 份文档`)
   const result = runScanPostCheck({
     cwd,
     specDir,
@@ -268,3 +274,107 @@ export async function executeScanPostcheck(cwd, platformOpts, scanProfile) {
     }
   }
 }
+
+// ─── noAI 化步骤动作（2026-09-05 ①：ls 级操作不值整轮 agent 往返） ─────────────
+
+/** 已注册项目清单（projects/*.yaml 文件名去后缀）；无注册时回退 [仓库根 basename]（单项目口径） */
+function listRegisteredProjects(specBase, cwd) {
+  const projectsRoot = join(specBase, 'projects')
+  try {
+    const names = readdirSync(projectsRoot).filter(f => f.endsWith('.yaml')).map(f => f.replace(/\.yaml$/, ''))
+    if (names.length > 0) return names
+  } catch { /* 无 projects 目录 → 回退单项目 */ }
+  return [basename(cwd)]
+}
+
+/**
+ * CLI-only: 子项目探测（scan 步骤 1 的 noAI 化）。
+ * 顶层目录 × 构建文件存在性 → 打印建议清单；**只建议不注册**（原红线语义不变，注册仍由用户确认）。
+ */
+export async function executeScanDetectProjects(cwd, platformOpts) {
+  const specBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+  const projectsRoot = join(specBase, 'projects')
+  const buildFiles = [
+    ['package.json', 'Node.js'], ['pom.xml', 'Java/Maven'], ['build.gradle', 'Java/Gradle'],
+    ['pyproject.toml', 'Python'], ['requirements.txt', 'Python'], ['go.mod', 'Go'], ['Cargo.toml', 'Rust'],
+  ]
+  const skip = new Set(['node_modules', '.git', '.sillyspec', 'dist', 'build', 'out', 'target', 'coverage', '.claude'])
+  console.log('  📁 子项目探测（CLI，只建议不注册——注册需用户在后续步骤确认）')
+  let found = 0
+  try {
+    for (const e of readdirSync(cwd, { withFileTypes: true })) {
+      if (!e.isDirectory() || skip.has(e.name) || e.name.startsWith('.')) continue
+      const hit = buildFiles.find(([f]) => existsSync(join(cwd, e.name, f)))
+      if (!hit) continue
+      found++
+      const registered = existsSync(join(projectsRoot, `${e.name}.yaml`))
+      console.log(`  - ${e.name}：${hit[1]} · ${registered ? '已注册' : '未注册（是否注册由用户确认）'}`)
+    }
+  } catch { /* 顶层目录读取失败 → 空清单 */ }
+  if (found === 0) console.log('  （未发现独立子项目，按单项目扫描）')
+  console.log('')
+}
+
+/**
+ * CLI-only: 断点续扫检测（scan 步骤 4 的 noAI 化）。existsSync 级检查，一次遍历全部已注册项目。
+ */
+export async function executeScanResumeCheck(cwd, platformOpts) {
+  const specBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+  for (const p of listRegisteredProjects(specBase, cwd)) {
+    const scanDir = join(specBase, 'docs', p, 'scan')
+    const states = SCAN_REQUIRED_DOCS.map(d => existsSync(join(scanDir, d)) ? `✅${d.replace('.md', '')}` : `⬜${d.replace('.md', '')}`)
+    const facts = existsSync(join(scanDir, '_facts.md')) ? '· 底稿✅' : '· 底稿⬜'
+    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 缺席零影响） */ }
+}
+
+/**
+ * CLI-only: scan 终检（步骤 11「自检和提交」的 noAI 化，含 ② frontmatter 盖章）。
+ * 顺序：frontmatter 注入（幂等）→ 清理 _env-detect.md → runScanPostCheck（本地轻量/平台严格）
+ * → failed_post_check 时 throw（step 保持 pending）→ 非平台 git add 扫描产物（不 commit）。
+ */
+export async function executeScanFinalize(cwd, platformOpts) {
+  const specDir = platformOpts?.specRoot || null
+  const specBase = specDir || join(cwd, '.sillyspec')
+  const { stampScanDocHeaders, runScanPostCheck, printScanPostCheckResult } = await import('../scan-postcheck.js')
+
+  const stamped = stampScanDocHeaders({ cwd, specDir })
+  if (stamped.fixed.length > 0) console.log(`  📝 frontmatter 已由 CLI 注入 ${stamped.fixed.length} 份文档（${stamped.stampedKeys} 个键，只补缺不覆盖）`)
+
+  for (const p of listRegisteredProjects(specBase, cwd)) {
+    const tmp = join(specBase, 'docs', p, 'scan', '_env-detect.md')
+    try { if (existsSync(tmp)) { unlinkSync(tmp); console.log(`  🧹 已清理 ${p}/scan/_env-detect.md`) } } catch { /* 清理失败不阻断 */ }
+  }
+
+  const result = runScanPostCheck({ cwd, specDir })
+  printScanPostCheckResult(result)
+  // 不 throw：平台模式的 manifest/指针/exit(1) 由 handleScanStageCompleted 在阶段完成时统一落
+  //（throw 会拦在完成前 → manifest.json 永不写入，破坏 SillyHub 消费契约，实测
+  //  run-complete-step-scan-platform Case 1）；本地模式的告警打印/postcheck-result.json 同理
+  // 由 complete-handlers 非平台收尾分支负责。本动作只负责：盖章 + 清理 + 即时报告 + 暂存。
+
+  if (!specDir) {
+    const r = safeGit(cwd, ['add', '.sillyspec/docs', '.sillyspec/knowledge'])
+    if (r && r.error) console.warn(`  ⚠️ git add 扫描产物失败（可手动处理）`)
+    else console.log('  📦 已暂存扫描产物 .sillyspec/docs 与 .sillyspec/knowledge（未提交，由统一提交工具处理）')
+  }
+}

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')
 }
 
 /**
@@ -614,13 +619,24 @@ export function resolveChangeDir(cwd, progress, specDir = null) {
 // 仍在跑，平台可能已接受推送而客户端当作超时放弃（spec 树推送无 base_ts 自愈兜底）。
 const SYNC_TOTAL_TIMEOUT_MS = 8_000
 
+// 熔断总预算 env 开关（坑 spec-sync-aborted-looks-exception / 债 E22b 场景实证，2026-09-07）：
+// 真实平台执行环境后端偶发 >8s 响应，8s 熔断间歇触发（warn 文案见 spec-sync.js
+// describeSyncError）。SILLYSPEC_SYNC_TIMEOUT_MS 允许平台环境放宽总预算；代价是 --done
+// 最坏等待同比例变长（e2c9f90 治的体感 hang 需自行权衡）。整数毫秒，[1000, 120000]，
+// 非法/越界一律回退默认 8s。raceWithAbort 默认参数逐次求值——进程内改 env 即时生效。
+export function resolveSyncTotalTimeoutMs() {
+  const raw = Number(process.env.SILLYSPEC_SYNC_TIMEOUT_MS)
+  if (Number.isInteger(raw) && raw >= 1_000 && raw <= 120_000) return raw
+  return SYNC_TOTAL_TIMEOUT_MS
+}
+
 /**
  * 熔断 race + 确定性取消：超时触发 controller.abort() 并 resolve，在飞 fetch 收到
  * AbortError 后自然失败（各调用方 catch 返回降级值，进程不挂起）。
  * @param {() => Promise} op 接收 { signal } 的异步操作
  * @param {number} timeoutMs 熔断时长（测试可缩短）
  */
-async function raceWithAbort(op, timeoutMs = SYNC_TOTAL_TIMEOUT_MS) {
+async function raceWithAbort(op, timeoutMs = resolveSyncTotalTimeoutMs()) {
   const controller = new AbortController()
   let timer
   try {

package/src/run/stage.js

@@ -20,7 +20,8 @@ import { join, dirname } from 'node:path'
 import { existsSync, readdirSync, readFileSync, mkdirSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps, warnApprovalUnknown, predictProtectedQuickFiles, mergeQuickBoundaryFiles, detectEmptyShellQuickSessions } from './shared.js'
-import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
+import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck, executeScanDetectProjects, executeScanResumeCheck, executeScanFinalize } from './scan-profile.js'
+import { executeProgressConfirm } from './progress-confirm.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { allocateQuicklogEntry, deriveTitleFromLinkedChange, sanitizeDesc } from '../quicklog.js'
 import { createHash } from 'node:crypto'
@@ -529,8 +530,18 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         await executeScanPreflight(cwd, platformOpts, scanProfile)
       } else if (cliAction === 'scanPostcheck') {
         await executeScanPostcheck(cwd, platformOpts, scanProfile)
+      } else if (cliAction === 'scanDetectProjects') {
+        await executeScanDetectProjects(cwd, platformOpts)
+      } else if (cliAction === 'scanResumeCheck') {
+        await executeScanResumeCheck(cwd, platformOpts)
+      } else if (cliAction === 'scanFinalize') {
+        await executeScanFinalize(cwd, platformOpts)
       } else if (cliAction === 'planPostcheck') {
         await executePlanPostcheck(cwd, platformOpts, progress)
+      } else if (cliAction === 'progressConfirm') {
+        // 主流程 step1「进度确认」noAI 化（2026-09-07）：brainstorm/execute/verify——
+        // 快照本就 CLI 注入、阶段路由已由 run 落定，省一轮「复述摘要→--done」往返
+        executeProgressConfirm({ stageName, cwd, stageData, changeName, pm })
       } else {
         throw new Error(`noAI 步骤 ${stepName} 的未知 _cliAction: ${cliAction}——请在 stage.js 注册对应分支`)
       }
@@ -546,6 +557,8 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         // 所有步骤完成
         stageData.status = 'completed'
         stageData.completedAt = new Date().toLocaleString('zh-CN', { hour12: false })
+        // 主阶段完成钉 currentStage（troubleshooting #56 根因修复，2026-09-08；与 complete.js 两处同语义）
+        if (!AUXILIARY_STAGES.includes(stageName)) progress.currentStage = stageName
         // persist _write 移到 completeStageGates 成功之后（task-02 / review-2026-08-09 #2）：gate 异常/失败 → rollback 回 in-progress 落盘，此处未到 _write，DB 不留假 completed。
         // 阶段完成收尾共享管线（noAI 末步核心修复 S1：plan postcheck independent-tier review verdict=fail /
         // 平台 scan manifest 此前被绕过）。gate 失败已 rollback 为 in-progress，early-return（不 fall through 到末尾 return）。