sillyspec 3.27.12 → 3.28.2

package/src/run/prompt.js

@@ -477,6 +477,35 @@ 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)
+  }
+
   // 决策防复潮注入（W1.1 第 3 点，task-04，FR-05）：brainstorm「加载项目上下文」Step2 的
   // {DECISION_HITS} → matchKnowledge decisionHits——命中 rejected 条目时渲染「否决决策提示」段
   // （ID/标题/否决理由/复潮条件），无命中替换为空串零输出（不留残留占位符）；注入结果同步落
@@ -683,6 +712,47 @@ 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 自查）')
+    }
+  }
+
+  // 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 误判「全未完成」）。

package/src/run/quick-audit.js

@@ -48,6 +48,23 @@ export function printQuickAuditReview(review) {
     for (const r of review.reasons) {
       console.warn(`   - ${r}`)
     }
+    // WARNING 也给解法（坑 quick-audit-warning-no-guidance，2026-09-03 用户实证：--files 声明后
+    // 追加测试文件 →「超出 allowedFiles」只列问题不给出路，非阻断但体验差——「别只警告」）。
+    // 指引按 reason 类型给；其他 advisory（文档欠账/引用失效等）已有各自的处置行。
+    const outOfDecl = review.reasons.filter((r) => r.startsWith('超出 allowedFiles'))
+    const undeclaredNew = review.reasons.filter((r) => r.startsWith('新增文件'))
+    if (outOfDecl.length > 0) {
+      const sample = outOfDecl.map((r) => r.split(': ')[1]).filter(Boolean)[0] || '<追加文件>'
+      console.warn(`   ➜ 出路：文件属本会话 → 带 --files（全量逗号分隔）重跑 --done 即并入边界，一条命令消掉本警告：`)
+      console.warn(`     sillyspec run quick --done --files <已声明文件>,${sample} --change <会话ID>`)
+      console.warn(`     （--files 只声明归属口径；确认收尾不想再改也可直接忽略本警告——非阻断。）`)
+    }
+    if (undeclaredNew.length > 0) {
+      const sampleNew = undeclaredNew.map((r) => r.split(': ')[1]).filter(Boolean)[0] || '<新增文件>'
+      console.warn(`   ➜ 出路：新增文件确认收进本会话 → --done 时 --files 声明归属 + --allow-new 放行新增：`)
+      console.warn(`     sillyspec run quick --done --allow-new --files <原声明文件>,${sampleNew} --change <会话ID>`)
+      console.warn(`     （两套开关：--files 管归属口径，--allow-new 管新增放行；不想要该文件可删除后再 --done。）`)
+    }
   } else {
     // 区分「本轮新增」（changedFiles，已扣前序 baseline）vs「累计暂存」（stagedTotal，全部未提交）。
     // 仅当存在前序 baseline 残留（累计 > 本轮新增）时才追加括注，避免普通场景冗余。
@@ -184,3 +201,84 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
   const selected = await checkbox({ message: '关联变更（空格切换，回车确认）', choices })
   return selected
 }
+
+// ============ quick --done test+lint 硬门禁（2026-09-02 跨 agent 工单 P0-2）============
+
+/**
+ * quick --done 内置 test+lint 实测门禁：把 CLAUDE.md 规则 8「触及 src/test 的改动先
+ * npm test + npm run lint」从 agent 自律下沉为 CLI 卡点。
+ *
+ * 语义（对齐规则 8 + verify-postcheck 既有降级哲学）：
+ *   - changedFiles 未触及 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/特殊场景，审计留痕）
+ *
+ * verify-postcheck 顶层 import 链较重（contract-matrix 等），且本函数仅 quick --done
+ * 收尾路径调用——用动态 import，不进 run 命令通用启动路径（与上方 @inquirer/prompts 同款纪律）。
+ *
+ * @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.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 }) {
+  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 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 }
+  }
+  if (codeFiles.length === 0) {
+    return { action: 'skip', failed: [], reason: `纯 doc/配置改动（${files.length} 个文件均未触及 src/test，规则 8 语义跳过 test+lint）`, test: null, lint: null }
+  }
+
+  const { runVerifyTestCheck, runVerifyLintCheck } = await import('../verify-postcheck.js')
+  const test = runVerifyTestCheck({ cwd, specBase, changeName })
+  const lint = runVerifyLintCheck({ cwd, specBase })
+  const failed = []
+  if (test.status === 'failed') failed.push('test')
+  if (lint.status === 'failed') failed.push('lint')
+  return {
+    action: failed.length > 0 ? 'fail' : 'pass',
+    failed,
+    reason: failed.length > 0
+      ? `实测失败：${failed.join(' + ')}（命令与输出尾部见上；修复后重跑 --done 不丢进度）`
+      : `触及 src/test 共 ${codeFiles.length} 个文件，test+lint 实测通过（或未配置命令自动跳过）`,
+    test,
+    lint,
+  }
+}
+
+/**
+ * 打印 quick test+lint 门禁结论（fail 时附输出尾部，供 agent 直接定位修复）。
+ */
+export function printQuickTestLintGate(gate) {
+  if (!gate) return
+  if (gate.action === 'skip') {
+    console.log(`\n🧪 quick test+lint 门禁 — SKIP：${gate.reason}`)
+    return
+  }
+  for (const [label, r] of [['test', gate.test], ['lint', gate.lint]]) {
+    if (!r) continue
+    const icon = r.status === 'failed' ? '❌' : r.status === 'passed' ? '✅' : '⏭️'
+    const dur = typeof r.durationMs === 'number' ? ` (${(r.durationMs / 1000).toFixed(1)}s)` : ''
+    console.log(`${icon} ${label}: ${r.status}${r.command ? ` ← ${r.command}${dur}` : ''}${r.status === 'skipped' && r.reason ? ` — ${r.reason}` : ''}`)
+  }
+  if (gate.action === 'fail') {
+    console.error(`\n🚫 quick test+lint 门禁 — BLOCKED：${gate.reason}`)
+    for (const key of gate.failed) {
+      const r = gate[key]
+      if (r && r.outputTail) console.error(`   ── ${key} 输出尾部 ──\n${r.outputTail}`)
+    }
+    console.error(`   quick 已停止：修复后重跑 --done（进度不丢）；确认要跳过实测请设 SILLYSPEC_QUICK_TEST_GATE=skip（审计留痕）。`)
+  } else {
+    console.log(`\n✅ quick test+lint 门禁 — PASS（${gate.reason}）`)
+  }
+}

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 { existsSync, readdirSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs'
 import { safeGit } 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,89 @@ 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('')
+}
+
+/**
+ * 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

@@ -378,6 +378,60 @@ export function collectOtherQuickSessionDeclarations(platformOpts, localSpecBase
   return out
 }
 
+/**
+ * quick 边界 --files 追加并入（stage.js 恢复路径与 --done 收尾共用，坑
+ * quick-audit-warning-no-guidance 2026-09-03）：追加不替换、去重保序；同时点录
+ * allowedFilesHash 供同文件并发检测（文件不存在跳过——预声明将新建文件与启动时同语义）。
+ * 就地修改 guard，返回 added 清单（空数组 = 无新增，调用方免打印免持久化）。
+ */
+export function mergeQuickBoundaryFiles(guard, quickFiles, cwd) {
+  const known = new Set(guard.allowedFiles || [])
+  const added = (Array.isArray(quickFiles) ? quickFiles : []).filter((f) => f && !known.has(f))
+  if (added.length === 0) return { guard, added: [] }
+  guard.allowedFiles = [...(guard.allowedFiles || []), ...added]
+  guard.allowedFilesHash = { ...(guard.allowedFilesHash || {}) }
+  for (const f of added) {
+    try { guard.allowedFilesHash[f] = createHash('sha256').update(readFileSync(join(cwd, f))).digest('hex') }
+    catch { /* 预声明将新建的文件，与启动时 allowedFilesHash 同语义：不存在跳过 */ }
+  }
+  return { guard, added }
+}
+
+/**
+ * 空壳 quick 会话探测（坑 quick-duplicate-empty-shell，2026-09-03 用户实证：一次输出被吞
+ * → agent 误判失败重跑 → 重复空壳会话，此前只能手工 reset + 删骨架）。判定：会话目录
+ * guard 存在、7 天内启动（超龄按僵尸跳过，与 collectOtherQuickSessionDeclarations 同口径）、
+ * 进度库中该会话有步骤记录但零步骤完成（全 pending——刚起步即中断的形态）。
+ * fail-open：进度读不到/无步骤记录的会话不列（宁可漏报不误报，并行真会话不误伤）。
+ */
+export function detectEmptyShellQuickSessions(platformOpts, localSpecBase, currentSessionId, pm, cwd, nowMs = Date.now()) {
+  const out = []
+  try {
+    const sessionsDir = resolveQuickSessionsDir(platformOpts, localSpecBase)
+    let sessionDirs = []
+    try {
+      sessionDirs = readdirSync(sessionsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name)
+    } catch { return out }
+    for (const sessionName of sessionDirs) {
+      if (sessionName === currentSessionId) continue
+      let guard = null
+      try { guard = JSON.parse(readFileSync(join(sessionsDir, sessionName, 'guard.json'), 'utf8')) } catch { continue }
+      if (!guard || !guard.startedAt) continue
+      const startedAtMs = Date.parse(guard.startedAt)
+      if (!Number.isFinite(startedAtMs) || nowMs - startedAtMs > FOREIGN_SESSION_STALE_MS) continue
+      try {
+        const p = pm.read(cwd, sessionName)
+        if (!p || !p.stages) continue
+        const allSteps = Object.values(p.stages).flatMap((s) => (Array.isArray(s.steps) ? s.steps : []))
+        if (allSteps.length === 0) continue // 无步骤记录：无法判定空壳，不列
+        if (allSteps.some((s) => s.completedAt)) continue // 有完成步骤 = 真实在用
+        out.push({ sessionId: guard.sessionId || sessionName, startedAt: guard.startedAt })
+      } catch { continue }
+    }
+  } catch { /* fail-open：探测失败不打扰 quick 启动 */ }
+  return out
+}
+
 /**
  * 平台指针三写（单一数据源，runCommand scan 与 cmdInit 平台模式共用）。
  *
@@ -560,13 +614,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

@@ -19,8 +19,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 } from './shared.js'
-import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
+import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps, warnApprovalUnknown, predictProtectedQuickFiles, mergeQuickBoundaryFiles, detectEmptyShellQuickSessions } from './shared.js'
+import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck, executeScanDetectProjects, executeScanResumeCheck, executeScanFinalize } from './scan-profile.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { allocateQuicklogEntry, deriveTitleFromLinkedChange, sanitizeDesc } from '../quicklog.js'
 import { createHash } from 'node:crypto'
@@ -350,12 +350,12 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
       progress.quickGuard = existingGuard
       // 中途追加边界：会话中途发现要改启动声明外的文件，此前 resume 会把 --files 静默丢弃、
       // 边界冻结在启动时刻，只能靠事后归属/审计行兜底。恢复时带 --files 即并入 allowedFiles
-      // （追加不替换、去重保序），同时点录 allowedFilesHash 供同文件并发检测（文件不存在跳过，
-      // 与启动同语义）。--done 审计直读 guard.json（complete-handlers §4.6），追加即被归属消费。
+      // （追加不替换、去重保序，mergeQuickBoundaryFiles 与 --done 收尾路径同源），同时点录
+      // allowedFilesHash 供同文件并发检测（文件不存在跳过，与启动同语义）。--done 审计直读
+      // guard.json（complete-handlers §4.6），追加即被归属消费。
       const resumeFiles = Array.isArray(quickOpts?.quickFiles) ? quickOpts.quickFiles.filter(Boolean) : []
       if (resumeFiles.length > 0) {
-        const known = new Set(progress.quickGuard.allowedFiles || [])
-        const added = resumeFiles.filter(f => !known.has(f))
+        const { added } = mergeQuickBoundaryFiles(progress.quickGuard, resumeFiles, cwd)
         if (added.length > 0) {
           // 受保护文件预告（坑 quick-protected-late-hint）：追加声明若含审计将拦的文件，
           // 追加时即点破（省一轮跑到 --done 才发现）。--files 只声明归属，不解锁拦截。
@@ -364,12 +364,6 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
             forceBaseline: quickOpts?.isForceBaseline || false,
           })
           if (protectedPreview.length > 0) warnProtectedQuickFiles(protectedPreview)
-          progress.quickGuard.allowedFiles = [...(progress.quickGuard.allowedFiles || []), ...added]
-          progress.quickGuard.allowedFilesHash = { ...(progress.quickGuard.allowedFilesHash || {}) }
-          for (const f of added) {
-            try { progress.quickGuard.allowedFilesHash[f] = createHash('sha256').update(readFileSync(join(cwd, f))).digest('hex') }
-            catch { /* 预声明将新建的文件，与启动时 allowedFilesHash 同语义：不存在跳过 */ }
-          }
           writeAtomicSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
           console.log(`🛡️ quick 边界已追加: ${added.length} 个文件（累计 ${progress.quickGuard.allowedFiles.length} 个）: ${added.join(', ')}`)
         }
@@ -451,6 +445,19 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         if (allowDelete) parts.push('允许删除文件')
         console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
         console.log(`📝 QUICKLOG 条目已创建: ${qlId}`)
+        // 空壳会话探测（坑 quick-duplicate-empty-shell，2026-09-03 用户实证：一次输出被吞 →
+        // agent 误判失败重跑 → 重复空壳会话，此前只能手工 reset + 删骨架）。新会话起步时点名
+        // 他者「已启动但零步骤完成」的会话 + 给官方清理口 --cancel（QUICKLOG 翻已取消 + 挂载行
+        // 移除）。advisory 不阻断：真在用的并行会话不受影响（有完成步骤即不列）。
+        try {
+          const shells = detectEmptyShellQuickSessions(platformOpts, specBase, changeName, pm, cwd)
+          if (shells.length > 0) {
+            console.warn('')
+            console.warn(`🧹 检测到 ${shells.length} 个疑似空壳 quick 会话（已启动但零步骤完成——常见于输出中断后误重启的残留）：`)
+            for (const s of shells) console.warn(`   - ${s.sessionId}（启动于 ${s.startedAt}）`)
+            console.warn(`   清理：sillyspec run quick --cancel --change <会话ID>；若确在用请忽略本提示。`)
+          }
+        } catch { /* fail-open：探测失败不打扰 quick 启动 */ }
         // 缺 --input 且关联变更无可提取标题 → 条目落「(quick 任务)」占位标题，平台「快速修复」列表
         // 默认隐藏进行中占位（task-06 口径），长会话全程不可见、语义标题要到最终 --done 才回填。
         // 此刻会话刚起步零沉没成本，提示放弃重启带 --input 是最便宜的自愈点。
@@ -522,6 +529,12 @@ 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 {

package/src/scan-diff.js

@@ -26,6 +26,7 @@ import { safeGit } from './git-helper.js'
 import { parseSourceCommit } from './scan-staleness.js'
 import { matchFilesToModules } from './docs-debt.js'
 import { parseModuleMapSimple } from './modules.js'
+import { collectDocRefs } from './docs-check.js'
 
 /** safeGit 超时（仿 docs-debt 的 GIT_TIMEOUT_MS 模式：大 diff 慢时降级不挂起） */
 const GIT_TIMEOUT_MS = 10000
@@ -40,7 +41,8 @@ const DEFAULT_LIST_CAP = 5
  *   specBase / projectName：scan 文档与 module-map 定位（specBase/docs/<projectName>/...）
  *   base：基线 commit（短/长哈希、引用均可）；缺省读 scan 文档 frontmatter 的 source_commit
  * @returns {{ ok: true, base, baseSource, head, behindCommits, daysSinceScan, scope,
- *   added, deleted, modified, unknown, unmapped, outOfScope, renameMap, byModule, warnings, driftCount }
+ *   added, deleted, modified, unknown, unmapped, outOfScope, renameMap, byModule,
+ *   staleRefs, warnings, driftCount }
  *   | { ok: false, error: string }}
  *   ok:false = 硬错误（参数缺失 / 无 source_commit / 无效 base / git diff 失败）
  *   added/deleted/modified/unknown：范围内变更文件（POSIX 相对路径；R/C 记新路径）
@@ -163,6 +165,40 @@ export function computeScanDiff({ projectRoot, specBase, projectName, base } = {
     byModule[id] = { doc: entry.doc || '', added: a, deleted: d, modified: m, files: entry.files }
   }
 
+  // ── 引用级漂移（archify 借鉴，2026-09-04）：scan 文档显式 file:line 引用 × 基线后变更文件集。
+  // 变更集取 parseNameStatus 全量——**不经 module-map scope 过滤**（引用自带范围：指向「已变更
+  // 但范围外」文件的引用同样过时，advisory 信号不该被 scope 吞掉）；rename 的旧路径也入集
+  //（文档写在 scan 时点，引用的是旧路径，重命名后引用必失效——最强失效信号）。
+  // best-effort（读不到文档/异常 → 空清单不阻断文件级结果），不计入 driftCount / 退出码
+  //（advisory：引用指向已变更文件 ≠ 引用失效，提示人工核对）。──
+  const staleRefs = []
+  try {
+    const scanDir = join(specBase, 'docs', projectName, 'scan')
+    if (existsSync(scanDir)) {
+      const fullChanged = new Map() // POSIX path → A/D/M/R
+      for (const item of parseNameStatus(diffRes.value)) {
+        if (item.status === 'A' || item.status === 'D') fullChanged.set(item.path, item.status)
+        else if (item.status === 'M' || item.status === 'C') fullChanged.set(item.path, 'M')
+        else if (item.status === 'R') { fullChanged.set(item.path, 'R'); fullChanged.set(item.oldPath, 'R') }
+      }
+      const hitChange = (p) => {
+        if (fullChanged.has(p)) return { file: p, change: fullChanged.get(p) }
+        // src/ 前缀双向归一：文档 src 相对写法 ↔ git 仓库根路径
+        const alt = p.startsWith('src/') ? p.slice(4) : `src/${p}`
+        return fullChanged.has(alt) ? { file: alt, change: fullChanged.get(alt) } : null
+      }
+      for (const f of readdirSync(scanDir)) {
+        if (!f.endsWith('.md')) continue
+        const content = readFileSync(join(scanDir, f), 'utf8')
+        for (const ref of collectDocRefs(content)) {
+          if (ref.repo !== null) continue
+          const hit = hitChange(ref.file.replace(/\\/g, '/'))
+          if (hit) staleRefs.push({ doc: f, ref: ref.ref, change: hit.change, file: hit.file })
+        }
+      }
+    }
+  } catch { /* 引用级漂移为 advisory，异常静默降级 */ }
+
   return {
     ok: true,
     base: baseDisplay,
@@ -174,6 +210,7 @@ export function computeScanDiff({ projectRoot, specBase, projectName, base } = {
     added, deleted, modified, unknown, unmapped, outOfScope,
     renameMap,
     byModule,
+    staleRefs,
     warnings,
     driftCount: added.length + deleted.length + modified.length,
   }
@@ -240,6 +277,13 @@ function renderTerminal(r, { full }) {
   if (r.unknown.length > 0) {
     console.log(`无法归类（unknown，${r.unknown.length} 条）：${r.unknown.slice(0, cap).join(', ')}`)
   }
+  if (r.staleRefs && r.staleRefs.length > 0) {
+    console.log(`引用过时（scan 文档 file:line 引用指向基线后已变更的文件，${r.staleRefs.length} 条，advisory）：`)
+    for (const s of r.staleRefs.slice(0, cap)) {
+      console.log(`  - ${s.doc}: \`${s.ref}\`（${s.change === 'D' ? '文件已删除' : s.change === 'A' ? '文件为基线后新增' : s.change === 'R' ? '文件已重命名' : '文件已变更'}）`)
+    }
+    if (r.staleRefs.length > cap) console.log(`    ... 其余 ${r.staleRefs.length - cap} 条，--full 展开`)
+  }
   console.log(`漂移合计：${r.driftCount} 条（A${r.added.length} / D${r.deleted.length} / M${r.modified.length}）`)
 }
 
@@ -304,6 +348,15 @@ function writeReport(r, { specBase, projectName }) {
     for (const f of r.outOfScope) lines.push(`- \`${f}\``)
     lines.push('')
   }
+  if (r.staleRefs && r.staleRefs.length > 0) {
+    lines.push('## 引用过时（advisory，不计入漂移合计）', '')
+    lines.push('scan 文档 file:line 引用指向基线后已变更的文件——不必然失效，逐条核对：', '')
+    for (const s of r.staleRefs) {
+      const label = s.change === 'D' ? '文件已删除' : s.change === 'A' ? '文件为基线后新增' : s.change === 'R' ? '文件已重命名' : '文件已变更'
+      lines.push(`- ${s.doc}: \`${s.ref}\`（${label}）`)
+    }
+    lines.push('')
+  }
   if (r.warnings.length > 0) {
     lines.push('## 提示', '')
     for (const w of r.warnings) lines.push(`- ${w}`)