sillyspec 3.26.7 → 3.26.9

package/src/run/complete.js

@@ -24,7 +24,7 @@ import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveR
 import { executeScanPreflight, executeScanPostcheck, computeScanProfile } from './scan-profile.js'
 import { executePlanPostcheck as runPlanPostcheckLib } from '../stages/plan-postcheck.js'
 import { outputStep } from './prompt.js'
-import { enforceDepsGate, enforceReviewJsonGate, completeStageGates, readDesignScale } from './gates.js'
+import { enforceDepsGate, enforceReviewJsonGate, enforceSymbolImpactGate, completeStageGates, readDesignScale } from './gates.js'
 import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact } from './complete-handlers.js'
 import { formatExecuteSummary } from '../worktree-apply.js'
 import { isEndToEndTaskText } from '../change-risk-profile.js'
@@ -64,32 +64,6 @@ export function resolveWaitingStepWithAnswer(steps, doneAnswer, nowStr) {
   return waitIdx
 }
 
-/**
- * wait 选项单选校验（坑 wait-choice-enforcement）：定义了 waitOptions 的 requiresWait/
- * repeatableWait 步骤，--answer 必须命中预设选项之一——防止 agent 一句话代答绕过人工
- * 选择（方案选择类 wait 的 answer 本就该是选项本身）。开放回答型步骤（澄清追问，answer
- * 为自由文本）在 step 定义显式声明 waitFreeAnswer: true 豁免。
- * 校验失败打印选项清单 + exit 1（fail-loud，与 requiresWait 门同风格）。
- *
- * waitOptions 优先取 stepDef（运行时构建的步骤定义，与 brainstorm/plan 静态定义同源），
- * 回退 DB step entry（--continue 路径 waiting 步骤的 waitOptions 已落盘）。
- */
-function enforceWaitChoice(stepDef, stepEntry, answer, stageName, changeName) {
-  if (answer == null) return
-  const opts = Array.isArray(stepDef?.waitOptions) ? stepDef.waitOptions
-    : (Array.isArray(stepEntry?.waitOptions) ? stepEntry.waitOptions : null)
-  if (!opts || opts.length === 0) return
-  if (stepDef?.waitFreeAnswer === true) return
-  if (opts.includes(answer)) return
-  console.error(`❌ Step "${stepEntry?.name || '当前步骤'}" 是封闭单选 wait，--answer 必须命中预设选项之一（防 AI 代答绕过人工选择）。`)
-  console.error(`   你的 --answer: ${JSON.stringify(answer)}`)
-  console.error(`   可选值（复制其一）: ${opts.join(' / ')}`)
-  console.error(`   自由文本回答的场景，该步骤应声明 waitFreeAnswer（当前未声明）。`)
-  if (changeName) console.error(`   重试：sillyspec run ${stageName} --done --answer "<选项>" --change ${changeName}`)
-  else console.error(`   重试：sillyspec run ${stageName} --done --answer "<选项>"`)
-  process.exit(1)
-}
-
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
   const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false } = options
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
@@ -148,10 +122,6 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   const defStepsForCurrent = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
   const currentStepDef = defStepsForCurrent?.[currentIdx] || {}
   const currentStep = steps[currentIdx]
-  // --done --answer 解 waiting 的路径同样过单选校验（与下方 requiresWait doneAnswer 分支同规则）
-  if (_resolvedWaitIdx !== -1 && _doneAnswer) {
-    enforceWaitChoice(currentStepDef, currentStep, _doneAnswer, stageName, changeName)
-  }
   if (currentStepDef.requiresWait === true && !currentStep.waitAnswer) {
     // 检查 --done 是否带了 --answer：如果是，自动补全 waitAnswer 状态，一步完成
     const doneAnswer = typeof options !== 'undefined' && options.doneAnswer ? options.doneAnswer : null
@@ -168,7 +138,6 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       currentStep.waitReason = currentStepDef.waitReason || '等待用户输入'
       console.log(`⚠️  Step "${currentStep.name}" 的确认（${currentStepDef.waitReason}）已在前置步骤完成，自动跳过。`)
     } else if (doneAnswer) {
-      enforceWaitChoice(currentStepDef, currentStep, doneAnswer, stageName, changeName)
       currentStep.status = 'waiting'
       currentStep.waitAnswer = doneAnswer
       currentStep.waitReason = currentStepDef.waitReason || '等待用户输入'
@@ -191,6 +160,9 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   // review.json 字段硬门（坑 review-json-field-gap）：已勾 [x] task 的 review.json 必须 schema 完整，
   // 提前到每次 --done 校验（而非等 Task Review Gate 在整阶段收尾才暴露，迫使用户事后批量补）。
   await enforceReviewJsonGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts)
+  // 符号影响面报告硬门（ql-20260816-005-3d7f）：execute「加载上下文」步产出落盘核验——
+  // symbol-impact.md 存在 + plan 每 task 有结论行；防前缀步被一句「上下文在会话内」盖章跳过。
+  await enforceSymbolImpactGate(stageName, changeName, steps[currentIdx]?.name, specBase)
 
   // ── noAI 步骤硬门（坑 noai-done-bypass）：noAI 步骤的确定性校验不可被 --done 绕过 ──
   // 正常路径 agent 跑 `run <stage>` 推进到 noAI step 时，runStage 自动执行 _cliAction
@@ -354,6 +326,9 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       console.warn('⚠️ 阶段完成 ctx 构造失败，降级单仓 gate（' + (e && e.message ? e.message : e) + '）')
     }
     const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, outputText, ctx: _completeCtx })
+    // task-04 / A5：gate 失败（stageCompleted===false）设进程退出码 1，对齐 quick 审计 blocked→exit 1 惯例。
+    // 用 process.exitCode 而非 process.exit(1)：让回滚 pm._write + triggerSync 落盘完成后自然退出，保留失败现场。
+    if (_stageGatesResult?.stageCompleted === false) process.exitCode = 1
     if (_stageGatesResult) return _stageGatesResult
 
     // 完整流程 change title 刷新：proposal/design 落盘后（brainstorm/plan 完成），从 proposal 首个 #
@@ -750,7 +725,6 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
   const prevOutput = currentStep.output || ''
   const waitRound = (currentStep.waitRound || 0) + 1
   currentStep.waitRound = waitRound
-  enforceWaitChoice(currentStepDef, currentStep, answer, stageName, changeName)
   currentStep.waitAnswer = answer
   currentStep.waitAnswers = Array.isArray(currentStep.waitAnswers) ? currentStep.waitAnswers : []
   currentStep.waitAnswers.push({
@@ -837,6 +811,8 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
       console.warn('⚠️ 阶段完成 ctx 构造失败，降级单仓 gate（' + (e && e.message ? e.message : e) + '）')
     }
     const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps: stageData.steps, currentIdx, outputText: null, ctx: _contCtx })
+    // task-04 / A5：gate 失败（stageCompleted===false）设进程退出码 1（与 completeStep 完成分支同语义）。
+    if (_stageGatesResult?.stageCompleted === false) process.exitCode = 1
     if (_stageGatesResult) return _stageGatesResult
     // 完整流程 change title 刷新（同 completeStep 完成分支，wait 解除后阶段完成也刷新）。
     if (changeName && !/^quick-[0-9a-f]{8}$/.test(changeName)) {

package/src/run/gates.js

@@ -27,6 +27,68 @@ import { handleScanStageCompleted, handleExecuteWorktreeCleanup } from './comple
 import { detectConcurrentChanges, formatConcurrentWarning } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
 
+/**
+ * 从 plan.md 提取全部 task id（task-XX）——符号影响面覆盖度校验用。
+ * 只认 checkbox 行 `- [ ] task-XX:` / `- [x] task-XX:`（与 execute.js parseWavesFromPlan 的
+ * 收容口径一致：### 标题式 task / 非 task 区 checkbox 不算），light plan 的 `## Tasks` 段同样收。
+ */
+function extractTaskIdsFromPlan(planContent) {
+  if (!planContent) return []
+  return [...String(planContent).matchAll(/^[-*]\s*\[[ x]\]\s*(?:.*\b)?task-(\d+)\b/gim)]
+    .map(m => `task-${m[1].padStart(2, '0')}`)
+}
+
+/**
+ * 符号影响面报告结构校验（纯函数）：execute「加载上下文」步的产出落盘核验。
+ *
+ * 治 persuasion-only 失效现场（ql-20260816-005-3d7f）：execute 前缀 4 步无任何 gate，agent 可
+ * <1s 连发 4 次 --done 盖章跳过，「符号影响面扫描」（execute.js 操作 11）被一句「上下文在会话内」
+ * 带过（输出契约只写「上下文摘要」，操作与输出脱节）。修法 = 报告落盘
+ * {SPEC_ROOT}/changes/<change>/symbol-impact.md + 本函数校验：plan.md 每个 task-XX 在报告中出现
+ * （逐 task 结论，「无签名级变更」也要显式写，治整体一句话带过）。语义质量（调用点找没找全）
+ * 仍归 agent，CLI 只核结构覆盖度——符合债单「persuasion-only → 补最小硬门」原则。
+ *
+ * @param {{reportContent: string|null, planContent: string|null}} params
+ * @returns {{ok: boolean, errors: string[]}}
+ */
+export function validateSymbolImpactReport({ reportContent, planContent }) {
+  const errors = []
+  if (!reportContent || !String(reportContent).trim()) {
+    return { ok: false, errors: ['symbol-impact.md 不存在或内容为空——「加载上下文」步的符号影响面报告必须落盘（逐 task 一行结论，「无签名级变更」也要显式写）'] }
+  }
+  const taskIds = extractTaskIdsFromPlan(planContent)
+  if (taskIds.length === 0) return { ok: true, errors } // plan 无 task 可列（默认兜底形态）→ 无可校验对象
+  const missing = taskIds.filter(id => !String(reportContent).includes(id))
+  for (const id of missing) {
+    errors.push(`${id} 未在 symbol-impact.md 中出现——每个 task 都要有一行结论（含「无签名级变更」的显式声明）`)
+  }
+  return { ok: errors.length === 0, errors }
+}
+
+/**
+ * 符号影响面报告硬门：execute「加载上下文」步 --done 时校验 symbol-impact.md 落盘 + task 覆盖度。
+ * fail-closed：不通过 → 当前步标 blocked + exit 1（进度不推进）。非目标步骤/阶段直接放行。
+ */
+export async function enforceSymbolImpactGate(stageName, changeName, currentStepName, specBase) {
+  if (stageName !== 'execute') return
+  if (!currentStepName || !currentStepName.includes('加载上下文')) return
+  const planPath = join(specBase, 'changes', changeName || '', 'plan.md')
+  const reportPath = join(specBase, 'changes', changeName || '', 'symbol-impact.md')
+  if (!existsSync(planPath)) return // plan.md 缺失场景已有 plan 阶段 gate 把关，此处不重复拦
+  let planContent = ''
+  try { planContent = readFileSync(planPath, 'utf8') } catch { return }
+  let reportContent = null
+  try { reportContent = readFileSync(reportPath, 'utf8') } catch { /* 缺失由 validate 报 */ }
+  const result = validateSymbolImpactReport({ reportContent, planContent })
+  if (result.ok) return
+  console.error('❌ ── 符号影响面报告校验阻断（本次 --done 未完成，进度未推进）──')
+  console.error(`   「加载上下文」步的符号影响面检查报告未落盘或不完整：`)
+  console.error(`   期望路径：${reportPath}`)
+  for (const e of result.errors) console.error(`   • ${e}`)
+  console.error('   修复：按「加载上下文」步操作 11 完成符号影响面扫描，逐 task 写结论（无签名级变更也要显式写「无」），落盘后重跑 execute --done。')
+  process.exit(1)
+}
+
 /**
  * 判断当前 execute step 所在 wave 是否全部 task 都声明 no_deps_verify: true（D-006@v2）。
  * 仅 wave 执行步骤（名如 "Wave N 执行"）可 opt-out；非 wave 步骤恒返回 false（保守过门）。
@@ -248,6 +310,24 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     const { runVerifyRequiredEvidenceCheck, printVerifyRequiredEvidenceCheck } = await import('../verify-postcheck.js')
     const evidenceCheck = runVerifyRequiredEvidenceCheck({ cwd, specBase, changeName })
     printVerifyRequiredEvidenceCheck(evidenceCheck)
+    // ── module-impact 死信探针（blocking，债单 D-1/D-5）：更新结果表 pending/待办行 → 阻断 verify ──
+    // 与 archive 移动前校验（extractPendingDocSyncRows）同一口径，把死信号从 archive 提前到 verify：
+    // agent 在 verify 阶段就须完成文档同步并回填 done/skipped，而非拖到归档被拦（修复 perf-remediation
+    // 类「verify PASS → archive 才发现 pending」的时序漏洞）。
+    const verifyChangeDir = resolveChangeDir(cwd, progress, platformOpts?.specRoot)
+    if (verifyChangeDir) {
+      const impactPath = join(verifyChangeDir, 'module-impact.md')
+      if (existsSync(impactPath)) {
+        const { extractPendingDocSyncRows } = await import('./complete-handlers.js')
+        const pendingRows = extractPendingDocSyncRows(readFileSync(impactPath, 'utf8'))
+        if (pendingRows.length > 0) {
+          console.error(`\n❌ verify 阶段被阻断：module-impact.md「更新结果」表存在 ${pendingRows.length} 个未清 pending/待办项（死信）`)
+          for (const row of pendingRows) console.error(`   - ${row}`)
+          console.error('   文档同步是 verify 的收尾义务：请完成模块文档同步并回填状态为 done/skipped（说明原因），再重新完成 verify。')
+          return rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
+        }
+      }
+    }
     console.log('\n✅ 验证通过，下一步：sillyspec run archive')
   }
 
@@ -361,7 +441,11 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           if (!executeRunId) {
             executeRunId = generateExecuteRunId()
             // 落盘（marker 缺失时 fallback 生成后写盘，保证后续 checkbox/gate 读到同一 ID）
-            try { mkdirSync(runtimeRoot, { recursive: true }); writeFileSync(runIdFile, executeRunId + '\n') } catch {}
+            // D-001#1 fallback 写入点：mkdir execute-runs/<runId>/tasks 先于 marker（不变量：
+            // marker 在则目录在）。不 try/catch——异常直穿外层 catch 走 fail-closed 阻断
+            //（gate 自身写 run 目录失败不能静默放行完成）。
+            mkdirSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'), { recursive: true })
+            writeFileSync(runIdFile, executeRunId + '\n')
           }
         }
 

package/src/run/prompt.js

@@ -390,6 +390,24 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     promptText = applyRootPlaceholders(promptText, { specRoot: specSillyspec, docsRoot, projectsRoot, workflowsRoot, knowledgeRoot })
   }
 
+  // scan 漂移事实注入（债单 D-7 方案 A）：brainstorm「加载项目上下文」读 scan 文档前，
+  // CLI 算出 staleness（source_commit vs HEAD）注入一行事实——"算事实注入"原则（债单第六节），
+  // 不是劝说指令。computeScanStaleness 内部全降级（无文档 null / git 失败 unknown），不阻断。
+  if (stageName === 'brainstorm' && promptText.includes('{SCAN_STALENESS}')) {
+    try {
+      const { computeScanStaleness } = await import('../scan-staleness.js')
+      const stalenessSpecBase = resolvePromptSpecBase(platformOpts, cwd)
+      const projectName = dbProjectName || basename(cwd)
+      const fact = computeScanStaleness({ projectRoot: cwd, specBase: stalenessSpecBase, projectName })
+      const injected = fact
+        ? `[docs-debt] scan 基线漂移：${fact.message}`
+        : '[docs-debt] scan 基线漂移：无 scan 文档（绿地项目），跳过判定'
+      promptText = promptText.replace(/\{SCAN_STALENESS\}/g, injected)
+    } catch (e) {
+      promptText = promptText.replace(/\{SCAN_STALENESS\}/g, `[docs-debt] scan 漂移检测异常（${e.message}），跳过判定`)
+    }
+  }
+
   // Knowledge hit report: execute 阶段注入匹配结果
   if (stageName === 'execute' && promptText.includes('{KNOWLEDGE_HIT_REPORT}')) {
     try {
@@ -420,6 +438,61 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     }
   }
 
+  // docs-debt 模块文档欠账事实注入（2026-08-15 docs-debt-inject D-006，债单第六节"CLI 算事实"）：
+  // Wave prompt {DOCS_DEBT} → computeDocsDebt（git diff × module-map）facts；空 facts 替换为空串
+  // （无债零输出，无残留占位符）。changedFiles 口径（D-001/FR-007）：worktree 根
+  // （meta.json 所在）git status --porcelain + diff baselineCommit..HEAD 并集；无 worktree
+  // （in-place/非 execute worktree 场景）退 cwd。全降级不抛（异常 → 单行说明）。
+  if (stageName === 'execute' && promptText.includes('{DOCS_DEBT}')) {
+    try {
+      const { computeDocsDebt } = await import('../docs-debt.js')
+      const debtSpecBase = resolvePromptSpecBase(platformOpts, cwd)
+      const debtProjectName = dbProjectName || basename(cwd)
+      // worktree 根解析：changeName → <specBase>/.runtime/worktrees/<changeName>/ 存在即锚
+      let debtProjectRoot = cwd
+      const wtRoot = join(debtSpecBase, '.runtime', 'worktrees', changeName || '')
+      if (changeName && existsSync(wtRoot)) {
+        debtProjectRoot = wtRoot
+      }
+      // changedFiles：已提交（baseline..HEAD）∪ 未提交（status porcelain，非未跟踪）
+      const changed = new Set()
+      const { safeGit } = await import('../git-helper.js')
+      const statusRes = safeGit(debtProjectRoot, ['status', '--porcelain'], { trim: false })
+      if (!statusRes.error && statusRes.value) {
+        for (const line of statusRes.value.split('\n')) {
+          if (!line.trim()) continue
+          // "XY path" / rename "R  old -> new" 取 new
+          const pathPart = line.slice(3).split('->').pop().trim().replace(/"/g, '')
+          if (pathPart && !pathPart.startsWith('.sillyspec/')) changed.add(pathPart.replace(/\\/g, '/'))
+        }
+      }
+      const { readFileSync: rf } = await import('node:fs')
+      const metaPath = join(wtRoot, 'meta.json')
+      if (changeName && existsSync(metaPath)) {
+        try {
+          const meta = JSON.parse(rf(metaPath, 'utf8'))
+          if (meta.baselineCommit) {
+            const diffRes = safeGit(debtProjectRoot, ['diff', '--name-only', `${meta.baselineCommit}..HEAD`], { trim: false })
+            if (!diffRes.error && diffRes.value) {
+              for (const f of diffRes.value.split('\n')) {
+                if (f.trim() && !f.trim().startsWith('.sillyspec/')) changed.add(f.trim().replace(/\\/g, '/'))
+              }
+            }
+          }
+        } catch { /* meta 读失败只用未提交集 */ }
+      }
+      const result = computeDocsDebt({
+        projectRoot: debtProjectRoot,
+        specBase: debtSpecBase,
+        projectName: debtProjectName,
+        changedFiles: [...changed],
+      })
+      promptText = promptText.replace(/\{DOCS_DEBT\}/g, result.facts)
+    } catch (e) {
+      promptText = promptText.replace(/\{DOCS_DEBT\}/g, `[docs-debt] 欠账计算异常（${e.message}），跳过`)
+    }
+  }
+
   // Execute: 注入 currentExecuteRunId（从变更专属标记文件读取）
   if (stageName === 'execute' && promptText.includes('{EXECUTE_RUN_ID}')) {
     let runId = ''
@@ -442,7 +515,15 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       const { generateExecuteRunId } = await import('../task-review.js')
       runId = generateExecuteRunId()
       // 落盘（与启动站点一致），保证 agent 收到的 ID == gate/checkbox 读取的 ID
-      try { mkdirSync(runtimeRoot, { recursive: true }); writeFileSync(runIdFile, runId + '\n') } catch {}
+      // D-001#1 fallback 写入点：mkdir execute-runs/<runId>/tasks 先于 marker（不变量：marker 在则目录在）。
+      // 渲染路径异常不能炸 prompt 输出 → catch 内 console.error 留痕 + 保留降级（ID 注入继续，
+      // 目录由下游 review 写入 / 其他写入点补齐）。
+      try {
+        mkdirSync(join(runtimeRoot, 'execute-runs', runId, 'tasks'), { recursive: true })
+        writeFileSync(runIdFile, runId + '\n')
+      } catch (e) {
+        console.error(`[sillyspec] execute run marker/目录写入失败（降级继续，ID ${runId} 仍注入 prompt）: ${e.message}`)
+      }
     }
     promptText = promptText.replace(/\{EXECUTE_RUN_ID\}/g, runId)
   }

package/src/run/quick-audit.js

@@ -50,6 +50,29 @@ export function printQuickAuditReview(review) {
       console.log(`\n✅ quick 变更边界审计 — SAFE (本轮新增变更 ${review.changedFiles.length} 个文件)`)
     }
   }
+  // D-8 文档欠账显性化（advisory，独立于 status 三态都打）：改了源码没动文档 → 一行欠账标记。
+  // 不阻断、不解锁、纯显性化——累积欠账可事后审计 QUICKLOG reasons 追溯。
+  if (review.docSyncHint && review.docSyncHint.touchedSource > 0 && review.docSyncHint.docFiles.length === 0) {
+    console.warn(`\n📝 文档欠账标记（D-8）：本次 ${review.docSyncHint.touchedSource} 个源码文件改动未同步任何模块文档。`)
+    // O-1（docs-signals-o12）：模块归属——从"改了 N 文件"到"欠在哪"（matchFilesToModules 纯函数，map 缺失时空数组降级）
+    if (Array.isArray(review.docSyncHint.modules) && review.docSyncHint.modules.length > 0) {
+      console.warn(`   涉及模块：${review.docSyncHint.modules.map(m => m.id).join(' · ')}（模块卡待同步，execute 场景详见 [docs-debt] 块）`)
+    }
+    console.warn(`   quick 不强制文档同步，但欠账已记录（QUICKLOG reasons）。若改动触及接口/契约，建议顺手同步模块文档。`)
+  }
+  if (review.docsCheckHint && review.docsCheckHint.invalid > 0) {
+    console.warn(`\n📎 文档引用失效（docs check）：本次改动的文档含 ${review.docsCheckHint.invalid}/${review.docsCheckHint.total} 处失效 file:line 引用。`)
+    console.warn(`   行号漂移 → 更新到当前源码；文件删改名 → 更新引用路径。跑 sillyspec docs check 可看完整清单。`)
+    console.warn(`   引用格式：\`src/foo.js:42\`（或 42-48）+ 同行反引号代码符号（如 \`runDocsCheck\`）——符号可让 --suggest 给出候选行号。`)
+  }
+  // task-03: 活文档引用漂移（advisory 不阻断，不改 status 三态判定）——方向与上方互补：
+  // 上方查「本次改的文档」，这里查「本次改的 src 被活文档（platform-interface-map 等）引用」。
+  if (review.docsCheckHint && review.docsCheckHint.livingDocDrift) {
+    const drift = review.docsCheckHint.livingDocDrift
+    const total = typeof drift.total === 'number' ? drift.total : drift.files.length
+    console.warn(`\n📎 活文档引用漂移：改动 ${drift.files.length}/${total} 被 ${drift.docs.join('、')} 引用——建议顺手跑 docs check 修引用行号。`)
+    console.warn(`   文件：${drift.files.join(', ')}`)
+  }
 }
 
 /**