sillyspec 3.28.8 → 3.28.10

package/src/run/gates.js

@@ -27,7 +27,7 @@ import { writeAtomicSync } from '../fs-atomic.js'
 import { triggerSync, resolveChangeDir, resolveRuntimeRoot } from './shared.js'
 import { runValidators } from '../stage-contract.js'
 import { handleScanStageCompleted, handleExecuteWorktreeCleanup } from './complete-handlers.js'
-import { detectConcurrentChanges, formatConcurrentWarning } from './concurrent-detect.js'
+import { detectConcurrentChanges, formatConcurrentWarning, detectCommittedDrift, formatCommittedDriftWarning } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
 import { normalizeTaskId } from '../taskcard.js'
 import { recordFrictionEvent } from '../friction-tally.js'
@@ -322,12 +322,14 @@ export async function enforceDepsGate(stageName, cwd, changeName, step, steps, c
     // 下游已有物理目录存在性判定兜底（G2/R3），这里 warn 留下根因线索，避免静默误诊。
     console.warn(`⚠️ worktree meta 读取失败（deps gate 将走物理目录判定）: ${e.message}`)
   }
-  const depsStatus = meta?.depsStatus
-  const mainOk = ['linked', 'installed', 'n/a'].includes(depsStatus)
-  if (mainOk) {
-    // ── 跨仓 worktree deps 校验（坑 cross-repo-no-worktree-isolation）──
-    // 跨仓仓供给失败同样无构建/测试能力（前端仓无 node_modules 建不了 build）。只校验已建
-    // worktree 的跨仓仓（legacy 直写模式无 meta，维持原语义，下游 Task Review 兜底）。
+  const depsOk = (s) => ['linked', 'installed', 'n/a'].includes(s)
+  const changeDir = changeName ? join(specBase, 'changes', changeName) : null
+
+  // main 侧就绪后的跨仓 worktree deps 校验（坑 cross-repo-no-worktree-isolation）：
+  // 跨仓仓供给失败同样无构建/测试能力（前端仓无 node_modules 建不了 build）。只校验已建
+  // worktree 的跨仓仓（legacy 直写模式无 meta，维持原语义，下游 Task Review 兜底）。
+  // 放行返回 true；跨仓未就绪置 blocked + exit(1)。
+  const crossCheckOrExit = async () => {
     let crossFailed = []
     try {
       const crossSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
@@ -351,8 +353,39 @@ export async function enforceDepsGate(stageName, cwd, changeName, step, steps, c
     if (persist) { try { await persist() } catch { /* 落盘失败不吞阻断语义 */ } }
     process.exit(1)
   }
-  const changeDir = changeName ? join(specBase, 'changes', changeName) : null
+
+  if (depsOk(meta?.depsStatus)) return await crossCheckOrExit()
+
+  // wave 级 opt-out（先于重供给：无需 deps 能力的 wave 不花 install 成本）
   if (isCurrentWaveAllNoDepsVerify(step?.name, changeDir)) return true
+
+  // ── --done 重供给重试（坑 deps-gate-manual-retry-ineffective，2026-09-15 wp 会话实证）──
+  // 阻断提示承诺「在 worktree 内手动安装依赖后重试」，但 manual install 不改 meta.depsStatus，
+  // failed 态直读 meta 永不翻绿 → 重试 --done 必撞同一堵墙，唯一出路 doctor --fix（wp 会话
+  // 正是手动编译成功后重试仍被拦，被迫多跑一轮 doctor）。对齐 run execute 入口
+  // ensureDepsFreshness 的同款供给：阻断前重供给一次并写回 meta——PATH 已修好的 shell 里
+  // 重跑 --done 即等效 doctor --fix；marker 型生态（nodejs）手动安装补齐 node_modules 后
+  // 重供给的 install 也能自然通过。仍失败则维持阻断，不无限重试。
+  let depsStatus = meta?.depsStatus
+  if (wm && changeName) {
+    let wtPath = null
+    try { wtPath = wm.getWorktreePath(changeName) } catch { /* meta 缺失走物理目录判定 */ }
+    if (wtPath && existsSync(wtPath)) {
+      try {
+        const { provisionDeps } = await import('../worktree-deps.js')
+        console.log(`🔄 deps 门控：depsStatus=${depsStatus || 'unknown'}，阻断前按 --done 重试路径重供给一次（与 doctor --fix 同款）...`)
+        const deps = provisionDeps(wtPath, cwd, { specBase }) || {}
+        meta = { ...meta, ...deps }
+        writeAtomicSync(join(wtPath, 'meta.json'), JSON.stringify(meta, null, 2) + '\n')
+        depsStatus = meta.depsStatus
+        console.log(`   重供给完成：depsStatus=${depsStatus || 'unknown'}${meta.depsError ? `（${meta.depsError}）` : ''}`)
+        if (depsOk(depsStatus)) return await crossCheckOrExit()
+      } catch (e) {
+        console.warn(`⚠️ deps 门控重供给失败（维持阻断判定）：${e.message}`)
+      }
+    }
+  }
+
   if (steps && steps[currentIdx]) {
     steps[currentIdx].status = 'blocked'
     // 阻断原因持久化（坑 deps-gate-blocked-invisible）：--status/诊断时可见，不依赖阻断当刻的
@@ -643,6 +676,28 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
   // 再由 CLI 亲自执行 local.yaml 的测试命令，与 verify-result.md 的自报告对账：
   // 自报告 PASS 但实测失败 → 阻断（防止"文案通过"绕过验证）。
   if (stageName === 'verify') {
+    // 坑 mixed-baseline-drift-hint（ql-20260915-004）：verify 实测门执行前的混合基线 advisory
+    //（提前预警不阻断）——apply-manifest 的基点后主仓已提交推进若触及本变更相关文件（含
+    // .test. 变体），worktree 快照内验证过的断言可能漂移，本次实测红先做合并态归因。推进面
+    // 剔除本变更自身文件面（apply 已提交时 baseHash..HEAD 含自身交付，不剔会自污染误报）；
+    // 剔除后精确命中信号由 apply 时点提示兜底，此处保变体方向（他者推进我源文件的测试变体 /
+    // 我测试文件对应的源文件）。无 manifest（in-place/quick）→ no-op 零行为变化。
+    try {
+      const driftManifestPath = join(specBase, 'changes', changeName, 'apply-manifest.json')
+      if (existsSync(driftManifestPath)) {
+        const driftManifest = JSON.parse(readFileSync(driftManifestPath, 'utf8'))
+        const driftFace = (driftManifest && Array.isArray(driftManifest.files)
+          ? driftManifest.files.map(f => f && f.path).filter(Boolean) : [])
+        if (driftManifest && driftManifest.baseHash && driftFace.length > 0) {
+          const drift = detectCommittedDrift({
+            projectRoot: cwd, baseHash: driftManifest.baseHash,
+            touchedFiles: driftFace, excludeFiles: driftFace,
+          })
+          const driftMsg = formatCommittedDriftWarning(drift, { tailNote: '本次实测若红，先做合并态归因' })
+          if (driftMsg) console.warn(driftMsg)
+        }
+      }
+    } catch { /* fail-soft：drift 检测异常不影响 verify 门 */ }
     const { runVerifyTestCheck, printVerifyTestCheck } = await import('../verify-postcheck.js')
     // P0-1 指纹复用（noai-ir-roadmap §3 前置一·防重复跑）：noAI 质量扫描步已实测且代码指纹
     // 未变 → 直接复用免重跑（长套件 2~10 分钟不再跑两遍）；无记录/失配/git 不可用 → 照旧
@@ -823,6 +878,11 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     })
     const reconcileEnvelope = buildReconcileTargetFilesEnvelope(reconcileCheck)
     const reconcileBlocked = printReconcileTargetFilesCheck(reconcileCheck, reconcileEnvelope)
+    // 跨仓 per-repo 对账明细渲染（坑 cross-repo-reconcile-blindness，2026-09-15 复盘兑现 D-004
+    // 分期）：reconcileTargetFiles 的 crossRepo 字段（advisory 不阻断）——各仓 对上/②缺/③多
+    // 逐仓一行 + ②缺明细（跨仓声明落空是该去对应仓干活的信号，但不翻主仓状态——锚点窗口
+    // 脆弱期会假信号）。无跨仓卡时 crossRepo 为空数组零输出。
+    printCrossRepoReconcile(reconcileCheck.crossRepo)
     // 结果落盘（design Wave 2 承诺：对齐 .runtime/verify-runs/<ts>/ 先例）——五状态全落（含
     // 放行态），fail-soft 不影响 gate 判定；②类阻断回执同样留档供平台/审计消费
     writeReconcileRunResult({ runtimeRoot: reconcileRuntimeRoot, changeName, envelope: reconcileEnvelope, result: reconcileCheck })
@@ -850,6 +910,23 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     })
     const probeEnvelope = buildProbeConsistencyEnvelope(probeCheck)
     const probeBlocked = printProbeConsistencyCheck(probeCheck, probeEnvelope)
+    // 探针7 covered 证据锚点 advisory（坑 probe7-covered-anchor-missing，2026-09-15 复盘：7 行
+    // covered 证据缺 file:line 被审查打回——预填说明已载明口径，机器在 --done 时点再拦一道，
+    // 省一轮人工往返）。advisory 不阻断；独立模块零环（verify-probes 是多会话冲突面，不碰）。
+    try {
+      const { checkProbe7AnchorCoverage } = await import('../probe7-anchor-check.js')
+      const p7ReportPath = join(specBase, 'changes', changeName, 'verify-result.md')
+      if (existsSync(p7ReportPath)) {
+        const p7Anchor = checkProbe7AnchorCoverage(readFileSync(p7ReportPath, 'utf8'))
+        if (p7Anchor.applicable && p7Anchor.missingAnchors.length > 0) {
+          console.warn(`\n⚠️ 探针7 锚点校验：${p7Anchor.missingAnchors.length}/${p7Anchor.coveredRows} 行判定为 covered 但证据列缺 file:line 锚点（advisory 不阻断，审查会要求回补）：`)
+          for (const m of p7Anchor.missingAnchors.slice(0, 10)) {
+            console.warn(`   - ${m.task}：${m.acceptance || '(空 acceptance)'}——证据当前为「${m.evidence || '(空)'}」，应给 \`测试文件路径:行号\` 首命中锚点`)
+          }
+          if (p7Anchor.missingAnchors.length > 10) console.warn(`   …还有 ${p7Anchor.missingAnchors.length - 10} 行`)
+        }
+      }
+    } catch { /* 锚点校验异常 fail-soft 不影响 gate */ }
     // 结果落盘（对齐 writeReconcileRunResult 先例）：独立文件 probe-consistency-result.json——
     // 与 reconcile-result.json 同 gate 运行同目录组织（verify-runs/<ts>/），但不并入后者：
     // reconcile-result.json 的 schema 已被 P3a 消费方锁定，塞探针字段（读改写/扩参）只会引入
@@ -1151,13 +1228,17 @@ export function readDesignScale(specBase, changeName) {
 /**
  * 校验变更目录下近 10 分钟新增的 .md/.yaml/.yml 文件含 author/created_at 元数据（advisory 打印）。
  * 从 complete.js 迁入（completeStageGates 共享收尾管线消费）。
+ * 按变更隔离（2026-09-14 quick，用户反馈③）：带 changeName 时本变更目录的缺元数据文件逐个
+ * 列出；其他变更目录的命中折叠为一行汇总并点名目录与计数——多 agent 并发仓里并行会话的他者
+ * 文件不再逐条混入本变更收尾输出（同批后续变更包也走汇总行，agent 按目录名自认领）。
+ * changeName 缺省（历史调用面）保持全量逐列。
  */
-export function validateMetadata(cwd, stageName, specBase) {
+export function validateMetadata(cwd, stageName, specBase, changeName) {
   const changesDir = join(specBase, 'changes')
   if (!existsSync(changesDir)) return
 
   const cutoff = Date.now() - 10 * 60 * 1000
-  const missing = []
+  const missing = new Set()
 
   function walk(dir) {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -1168,19 +1249,34 @@ export function validateMetadata(cwd, stageName, specBase) {
         const mtime = statSync(full).mtimeMs
         if (mtime < cutoff) continue
         const content = readFileSync(full, 'utf-8')
-        if (!content.includes('author:') && !content.includes('author：')) missing.push(full)
-        if (!content.includes('created_at:') && !content.includes('created_at：')) missing.push(full)
+        if (!content.includes('author:') && !content.includes('author：')) missing.add(full)
+        if (!content.includes('created_at:') && !content.includes('created_at：')) missing.add(full)
       } catch (e) { /* skip unreadable files */ }
     }
   }
 
   walk(changesDir)
-  const unique = [...new Set(missing)]
-  if (unique.length > 0) {
+  if (missing.size === 0) return
+
+  // 归属分组：changes/ 下第一段目录名（[\\/] 切分兼容 Windows join 产物的反斜杠）
+  const current = []
+  const otherCounts = new Map()
+  for (const f of missing) {
+    const top = relative(changesDir, f).split(/[\\/]/)[0]
+    if (!changeName || top === changeName) current.push(f)
+    else otherCounts.set(top, (otherCounts.get(top) || 0) + 1)
+  }
+
+  if (current.length > 0) {
     console.log(`\n⚠️  以下文件缺少 author 或 created_at 元数据：`)
-    unique.forEach(f => console.log(`  - ${relative(cwd, f) || f}`))
+    current.forEach(f => console.log(`  - ${relative(cwd, f) || f}`))
     console.log('请在文件头部添加 author（git 用户名）和 created_at（精确到秒）')
   }
+  if (otherCounts.size > 0) {
+    const parts = [...otherCounts.entries()].map(([dir, n]) => `${dir}×${n}`).join('、')
+    const total = [...otherCounts.values()].reduce((a, b) => a + b, 0)
+    console.log(`\nℹ️  另有 ${total} 个其他变更目录的文件近 10 分钟新增且缺元数据（${parts}）——已按变更隔离折叠：并行会话产物请忽略；若为本步骤创建的同批变更包，请补 author/created_at`)
+  }
 }
 
 /**
@@ -1339,7 +1435,7 @@ export async function completeStageGates({ stageName, cwd, changeName, platformO
   const settledCount = steps.filter(s => s.status === 'completed' || s.status === 'skipped').length
   const total = steps.length
 
-  validateMetadata(cwd, stageName, specBase)
+  validateMetadata(cwd, stageName, specBase, changeName)
 
   // 验证关键文件位置（仅当所有步骤已结案 completed‖skipped 时才校验）
   if (settledCount === total && total > 0) {
@@ -1513,6 +1609,35 @@ export function writeReconcileRunResult({ runtimeRoot, changeName, envelope, res
  * @param {object} [envelope] 预构造信封（缺省现算；显式传入便于调用方先断言再打印）
  * @returns {boolean} true = 阻断（status='missing_declared'）
  */
+/**
+ * 打印跨仓 per-repo 对账结果（cross-repo-reconcile.js 产出的 advisory 明细，verify 块接线）。
+ * 恒不阻断（返回 void）：跨仓 diff 锚点=各仓最近提交窗口，锚点脆弱期（已 commit 多笔/全在
+ * working-tree）会产②类假信号——明细供人工裁决，不翻主仓对账状态。
+ * @param {Array<{repo:string,repoPath:string|null,declaredCount:number,actualCount:number,
+ *   matched:string[],missing:Array<{task:string,path:string,isNew?:boolean}>,
+ *   undeclared:string[],scaffoldCount:number,degradedReason:string|null}>|undefined} crossRepo
+ */
+function printCrossRepoReconcile(crossRepo) {
+  if (!Array.isArray(crossRepo) || crossRepo.length === 0) return
+  console.log(`\n🔀 跨仓 per-repo 对账（advisory 不阻断，锚点=各仓最近提交窗口）：`)
+  for (const r of crossRepo) {
+    if (r.degradedReason) {
+      console.warn(`   ⚠️ ${r.repo}：${r.degradedReason}`)
+      continue
+    }
+    const flag = (r.missing.length > 0 || r.undeclared.length > 0) ? '⚠️ ' : '✅ '
+    console.log(`   ${flag}${r.repo}（${r.repoPath}）：声明 ${r.declaredCount} / 实测 ${r.actualCount} / 对上 ${r.matched.length} / ②缺 ${r.missing.length} / ③多 ${r.undeclared.length}${r.scaffoldCount > 0 ? ` / 脚手架聚合 ${r.scaffoldCount}` : ''}`)
+    for (const m of r.missing.slice(0, 10)) {
+      console.warn(`      ②缺 ${m.task}: ${m.path}${m.isNew ? '（NEW: 声明新建，该仓未见）' : ''}——锚点窗口外已提交或多笔时可能假信号，到该仓 git log 核实`)
+    }
+    if (r.missing.length > 10) console.warn(`      …还有 ${r.missing.length - 10} 条②缺`)
+    for (const u of r.undeclared.slice(0, 10)) {
+      console.warn(`      ③多 ${u}（该仓最近窗口实际改动，未在任何跨仓卡声明）`)
+    }
+    if (r.undeclared.length > 10) console.warn(`      …还有 ${r.undeclared.length - 10} 条③多`)
+  }
+}
+
 export function printReconcileTargetFilesCheck(r, envelope = buildReconcileTargetFilesEnvelope(r)) {
   // ②类（声明未做=计划落空）：ERROR 阻断
   if (r.status === 'missing_declared') {

package/src/run/prompt.js

@@ -29,6 +29,11 @@ import { nowWallClock } from '../datetime.js'
 import { parseModuleMapSimple } from '../modules.js'
 import { readModuleRecentChanges } from '../module-changelog.js'
 import { REVIEW_SCHEMA_VERSION, isValidExecuteRunId } from '../task-review.js'
+// 机械知识注入（2026-09-14-knowledge-loop-close task-04，FR-04）：两者均为 fs/path 叶子模块，
+// 静态 import 不引入环（stages/* 反向引用本文件会撞 index.js 顶层 stageRegistry TDZ——见
+// buildKnowledgeInjection docstring）。
+import { matchKnowledge } from '../knowledge-match.js'
+import { appendKnowledgeHit } from '../knowledge-hits.js'
 
 /**
  * 从 _module-map.yaml 读取模块上下文索引
@@ -220,8 +225,159 @@ export function buildQuickSemanticGuardInjection({ specBase, cwd, changeName } =
   }
 }
 
+// ── 机械知识注入共享底座（2026-09-14-knowledge-loop-close task-04，FR-04 / D-002@v1 总体方案 D）──
+// 知识消费从 report 级升级为正文级：matchKnowledge 命中 → 按 entries 出现序（INDEX 行序）取
+// 前 3 个不同 file，单文件首 40 行截断 + 截断标记，渲染「📚 命中知识」段（R-02 膨胀控制）；
+// 未命中 section=''（调用方零字节零变化）。命中同时经 task-01 的 appendKnowledgeHit 落
+// .runtime/knowledge-hits.jsonl 一条 type:inject 记录；既有 knowledge-hit-report.json 由
+// execute 调用方照旧落盘（X-004 升级既有机制而非并行新建，新旧遥测共存）。
+//
+// ⚠️ 同款格式在 src/stages/execute.js buildWavePrompt 内有本地孪生实现（Wave 粒度注入）——
+// 本文件无法被 execute.js 静态 import（prompt.js → stages/index.js → execute.js 既有依赖方向，
+// 反向边会在 execute.js 作模块图入口时触发 index.js 顶层 stageRegistry 对其 definition const 的
+// TDZ 求值，2026-09-14 ESM 环实证）。格式漂移由 test/knowledge-inject.test.mjs 的格式等价断言
+// 锁定——改此处必同步改孪生。
+export const KNOWLEDGE_INJECT_MAX_FILES = 3
+export const KNOWLEDGE_INJECT_MAX_LINES = 40
+
+/** top-N 选取：按 entries 出现序（INDEX 行序）取前 N 个不同 file（matchKnowledge 布尔 filter
+ *  无相关度排序，X-009——出现序即唯一稳定序），每 file 取首个命中 entry 作代表。 */
+function pickTopKnowledgeEntries(entries, maxFiles) {
+  const seen = new Set()
+  const picked = []
+  for (const e of entries) {
+    if (seen.has(e.file)) continue
+    seen.add(e.file)
+    picked.push(e)
+    if (picked.length >= maxFiles) break
+  }
+  return picked
+}
+
+/** 命中正文段渲染（段头 + Status/Sources 命中报告语义 + top-3 文件截断正文）。 */
+function renderKnowledgeInjectSection(knowledgeResult, { knowledgeDir, maxFiles, maxLines }) {
+  const ref = e => (e.anchor ? `${e.file}#${e.anchor}` : e.file)
+  const lines = []
+  lines.push(`📚 命中知识（CLI 按任务描述机械匹配，top-${maxFiles}）`)
+  lines.push(`Status: matched | Entries: ${knowledgeResult.entries.length} | Sources:`)
+  for (const e of knowledgeResult.entries) lines.push(` - ${ref(e)}`)
+  lines.push(`（命中清单如上；正文按 INDEX 行序注入前 ${maxFiles} 个不同文件，单文件首 ${maxLines} 行截断——未注入条目需要时按 Sources 路径自行读取）`)
+  for (const e of pickTopKnowledgeEntries(knowledgeResult.entries, maxFiles)) {
+    lines.push('')
+    lines.push(`── ${ref(e)}${e.display ? `（${e.display}）` : ''} ──`)
+    let body = ''
+    try {
+      // CRLF/CR 归一（Windows 知识文件 + 行数截断按 \n 切分）
+      body = readFileSync(join(knowledgeDir, e.file), 'utf8').replace(/\r\n?/g, '\n')
+    } catch (err) {
+      lines.push(`（文件不可读：${err && err.message ? err.message : err}）`)
+      continue
+    }
+    const bodyLines = body.split('\n')
+    if (bodyLines.length > maxLines) {
+      lines.push(bodyLines.slice(0, maxLines).join('\n'))
+      lines.push('…（截断）')
+    } else {
+      lines.push(body.replace(/\n+$/, ''))
+    }
+  }
+  return lines.join('\n')
+}
+
+/**
+ * 机械知识注入一站式入口（execute「确认执行范围」step 与 quick step1 两个 prompt.js 内注入点共用）。
+ *
+ * @param {object} opts
+ * @param {string} opts.knowledgeDir - knowledge 目录（INDEX.md 所在）
+ * @param {string} opts.runtimeDir - .runtime 目录（hits.jsonl 落点）
+ * @param {string} opts.change - 变更名 / quick sessionId（进遥测记录 change 字段）
+ * @param {string} opts.query - 匹配查询串（execute: changeName+tasks.md 任务行；quick: guard.taskDescription）
+ * @returns {{matched: boolean, section: string, report: string, json: object}}
+ *   section：命中时的「📚 命中知识」段（含段头与正文）；未命中恒 ''（调用方零字节）。
+ *   report/json：matchKnowledge 原样透传（execute 调用方沿用旧 report.json 落盘与未命中替换口径）。
+ *   遥测 append 单独 fail-soft（hits 写失败不影响注入本体）；匹配/渲染异常向上抛由调用方降级。
+ */
+export function buildKnowledgeInjection({ knowledgeDir, runtimeDir, change, query, maxFiles = KNOWLEDGE_INJECT_MAX_FILES, maxLines = KNOWLEDGE_INJECT_MAX_LINES } = {}) {
+  const knowledgeResult = matchKnowledge(knowledgeDir, String(query || ''))
+  if (!knowledgeResult.matched) {
+    return { matched: false, section: '', report: knowledgeResult.report, json: knowledgeResult.json }
+  }
+  const section = renderKnowledgeInjectSection(knowledgeResult, { knowledgeDir, maxFiles, maxLines })
+  try {
+    appendKnowledgeHit(runtimeDir, {
+      type: 'inject',
+      change: change || '',
+      query: String(query || ''),
+      matchedFiles: knowledgeResult.entries.map(e => (e.anchor ? `${e.file}#${e.anchor}` : e.file)),
+    })
+  } catch { /* 遥测 fail-soft（R-04）：hits 落盘失败不阻断注入本体 */ }
+  return { matched: true, section, report: knowledgeResult.report, json: knowledgeResult.json }
+}
+
 // parseModuleMapSimple 复用 modules.js 的 canonical 实现（合并历史 copy-paste 副本，2026-08-07；
 // 无循环依赖：modules.js 仅 import fs/path/db.js，prompt.js → modules.js 单向）。
+
+/**
+ * 等效验证先例库（坑 verify-precedent-only-in-prose，2026-09-15 EHS 生产实证：mvn test 被
+ * 公司框架 parent pom pluginManagement 硬编码 surefire skip=true、-D 覆盖无效——等效口径
+ * dependency:build-classpath+javac+JUnitCore 第二次复用靠 agent 翻旧 verify-result.md 正文
+ * 续命；先例只活在散文里 = 换个 agent/换个变更就断档）。结构化登记进 local.yaml
+ * verify_precedents 段，verify prompt 时点注入提示（与 test_strategy 预检提示同挂点）。
+ *
+ * 对象数组形态（行扫描，同 extractKnownFailures 免 YAML 依赖口径——注释/空行/块界容错）：
+ *   verify_precedents:
+ *     - id: mvn-test-surefire-skip
+ *       standard_command: mvn test
+ *       reason: <标准命令为何不可用>
+ *       equivalent: <已验证的等效口径>
+ *       established_by: <确立该口径的变更名>
+ *       notes: <可选补充>
+ * 残项（standard_command 与 equivalent 双缺）过滤——登记不完整的先例没有可执行口径。
+ * @param {string|null} yamlText local.yaml 全文
+ * @returns {Array<object>} 先例对象数组
+ */
+export function parseVerifyPrecedents(yamlText) {
+  const lines = String(yamlText || '').split(/\r?\n/)
+  const headIdx = lines.findIndex(l => /^verify_precedents:\s*(?:#.*)?$/.test(l))
+  if (headIdx < 0) return []
+  const items = []
+  let cur = null
+  const clean = (v) => String(v || '').replace(/\s+#.*$/, '').trim()
+  for (let i = headIdx + 1; i < lines.length; i++) {
+    const l = lines[i]
+    if (/^\S/.test(l)) break // 下一个顶层键 → 块结束
+    if (!l.trim() || /^\s*#/.test(l)) continue
+    const item = l.match(/^\s*-\s+([A-Za-z_][\w-]*):\s*(.*)$/)
+    if (item) {
+      cur = {}
+      items.push(cur)
+      cur[item[1]] = clean(item[2])
+      continue
+    }
+    const kv = l.match(/^\s*([A-Za-z_][\w-]*):\s*(.*)$/)
+    if (kv && cur) cur[kv[1]] = clean(kv[2])
+  }
+  return items.filter(x => x && (x.standard_command || x.equivalent))
+}
+
+/**
+ * 先例提示渲染（verify prompt 注入用；空输入 → ''，调用方零输出）。
+ * 行动指引刻意指向「把等效命令配进 commands.test 照常全量实测对账」而非 test_strategy: skip
+ * 放行——EHS 实证里被环境阻断 deferred 的集成测试正是 P1 缺陷藏身处，能实测就实测。
+ * @param {Array<object>|null} precedents
+ * @returns {string}
+ */
+export function renderVerifyPrecedentHint(precedents) {
+  if (!Array.isArray(precedents) || precedents.length === 0) return ''
+  const L = [`【验证先例提示】本仓已登记 ${precedents.length} 条等效验证先例（标准命令不可用时的既有替代口径）：`]
+  for (const p of precedents.slice(0, 5)) {
+    L.push(`- ${p.id || '（无 id）'}：\`${p.standard_command || '?'}\` 不可用（${p.reason || '原因未注'}）→ 等效口径 \`${p.equivalent || '?'}\`（确立于 ${p.established_by || '?'}${p.notes ? `；${p.notes}` : ''}）`)
+  }
+  if (precedents.length > 5) L.push(`- …另有 ${precedents.length - 5} 条未展开（读 local.yaml verify_precedents 段看全量）`)
+  L.push('适用时把等效命令配进 local.yaml commands.test（或 modules.<m>.test）后照常全量实测对账，而不是只靠 test_strategy: skip 放行；先例不适用（环境已变/口径失效）可忽略并在 verify-result 注记。')
+  return L.join('\n')
+}
+
 /**
  * 提示词路径根的单一解析：specRoot(平台) > specDriftAnchor(worktree 漂移锚定主仓) > cwd/.sillyspec(本地)。
  * 治 execute review.json 提示路径写 worktree 副本、--done 校验读主仓的分裂（坑 execute-prompt-spec-drift）：
@@ -754,9 +910,13 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   }
 
   // Knowledge hit report: execute 阶段注入匹配结果
+  // 2026-09-14-knowledge-loop-close task-04（FR-04，X-004 升级既有机制）：命中清单报告 → 命中
+  // 正文注入——命中时占位符替换为「📚 命中知识」段（top-3 不同 file + 首 40 行截断，段头保留
+  // Status/Entries/Sources 命中报告语义），并逐条 appendKnowledgeHit 落 hits.jsonl 遥测；
+  // 未命中替换值与升级前字节一致（knowledgeResult.report == 'Status: no matches'，零膨胀）。
+  // 既有 knowledge-hit-report.json 照旧落盘（未命中也写 matched:false 快照，行为不变）。
   if (stageName === 'execute' && promptText.includes('{KNOWLEDGE_HIT_REPORT}')) {
     try {
-      const { matchKnowledge } = await import('../knowledge-match.js')
       const effectiveSpecBase = resolvePromptSpecBase(platformOpts, cwd)
       const knowledgeDir = join(effectiveSpecBase, 'knowledge')
       // taskContext: changeName + tasks.md 任务名（注册表唯一真相，2026-08-20-task-truth-unify）
@@ -774,12 +934,20 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
           }
         } catch {}
       }
-      const knowledgeResult = matchKnowledge(knowledgeDir, taskContext)
-      promptText = promptText.replace(/\{KNOWLEDGE_HIT_REPORT\}/g, knowledgeResult.report)
-      // 写入 runtime JSON
       const runtimeDir = join(effectiveSpecBase, '.runtime')
+      const knowledgeInjection = buildKnowledgeInjection({
+        knowledgeDir,
+        runtimeDir,
+        change: changeName || '',
+        query: taskContext,
+      })
+      promptText = promptText.replace(
+        /\{KNOWLEDGE_HIT_REPORT\}/g,
+        knowledgeInjection.matched ? knowledgeInjection.section : knowledgeInjection.report
+      )
+      // 写入 runtime JSON（既有机制照旧，新旧遥测共存）
       mkdirSync(runtimeDir, { recursive: true })
-      writeAtomicSync(join(runtimeDir, 'knowledge-hit-report.json'), JSON.stringify(knowledgeResult.json, null, 2) + '\n')
+      writeAtomicSync(join(runtimeDir, 'knowledge-hit-report.json'), JSON.stringify(knowledgeInjection.json, null, 2) + '\n')
     } catch (e) {
       promptText = promptText.replace(/\{KNOWLEDGE_HIT_REPORT\}/g, 'Status: no matches (error: ' + e.message + ')')
     }
@@ -1023,13 +1191,14 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   // 推荐组合、无从否决——故在 prompt 时点经 {EVIDENCE_AUTO_RECOMMENDATION} 把 task-11
   // resolveTestStrategy 的 evidence_auto_recommendation.summary 渲染进 step prompt（含推荐
   // 理由、降级注记与「可在 verify-result.md 否决并改跑全量」路径），供用户否决（FR-11）。
-  // 仅 test_strategy=evidence-auto 且 recommendation 非空时渲染；full/module/skip/未配置
-  // （recommendation=null）替换为空串零输出。fail-soft：读取/解析异常降级单行说明不抛，
+  // 仅 test_strategy=evidence-auto 且 recommendation 非空时渲染推荐；full/module/skip/已配置
+  // 替换为空串零输出；**未配置**且 commands.test 已配时渲染 test_strategy 预检提示（2026-09-15
+  // 复盘：环境硬伤的全量实测打回返工，提前在 prompt 时点给配置指引）。fail-soft：读取/解析异常降级单行说明不抛，
   // 绝不阻断 verify prompt 输出（对齐上方 {WORKTREE_BASELINE_INFO} 注入先例）。
   if (stageName === 'verify' && promptText.includes('{EVIDENCE_AUTO_RECOMMENDATION}')) {
     let eaInjected = ''
     try {
-      const { resolveTestStrategy } = await import('../verify-postcheck.js')
+      const { resolveTestStrategy, extractTestCommand, extractTestStrategy } = await import('../verify-postcheck.js')
       const eaSpecBase = resolvePromptSpecBase(platformOpts, cwd)
       // 信任边界：local.yaml 只读 specBase（平台 specRoot / 漂移锚定主仓 / cwd 本地），与
       // runVerifyTestCheck 的 specBase 来源同口径，不读 agent 可写的 worktree 副本。
@@ -1038,7 +1207,20 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       const eaChangeDir = changeName ? join(eaSpecBase, 'changes', changeName) : null
       const resolution = resolveTestStrategy({ yamlText: eaYamlText, changeDir: eaChangeDir })
       const rec = resolution.evidence_auto_recommendation
-      if (rec && rec.summary) eaInjected = rec.summary
+      if (rec && rec.summary) {
+        eaInjected = rec.summary
+      } else if (eaYamlText && extractTestCommand(eaYamlText) && !extractTestStrategy(eaYamlText)) {
+        // test_strategy 预检提示（2026-09-15 复盘教训「test_strategy 该在进 verify 前配好，
+        // 而不是被 verify-test gate 打回后才补」）：已配 commands.test 但顶层 test_strategy
+        // 未设（缺省=全量实测对账），prompt 时点先给配置指引——环境注定跑不了全量时省一轮
+        // 「--done 实测打回 → 补配置 → 重跑」返工
+        eaInjected = '【test_strategy 预检提示】local.yaml 已配置 commands.test 但未设顶层 test_strategy（缺省=全量实测对账）。若该命令在当前环境无法真实执行（框架/环境硬伤，如测试框架硬编码 skip、依赖外部服务），先在 local.yaml 显式配 `test_strategy: skip`（或 `module` + modules 映射收窄）并注释理由再继续——避免 verify --done 实测对账打回后返工。'
+      }
+      // 等效验证先例注入（verify-precedent-only-in-prose，2026-09-15 EHS 实证）：先例与
+      // 预检提示同挂点追加——标准命令不可用但已有验证过的等效口径时，指引优先配进
+      // commands.test 实测对账而非 skip 放行。
+      const _precHint = renderVerifyPrecedentHint(parseVerifyPrecedents(eaYamlText))
+      if (_precHint) eaInjected = eaInjected ? `${eaInjected}\n\n${_precHint}` : _precHint
     } catch (e) {
       eaInjected = `（evidence-auto 推荐注入失败：${e.message}——请读 .sillyspec/local.yaml 确认 test_strategy；--done 时 CLI 仍会按 resolveTestStrategy 实测对账，推荐不可用时可显式设 test_strategy: full/module）`
     }
@@ -1108,6 +1290,29 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     }
   }
 
+  // ── 机械知识注入（quick step1，2026-09-14-knowledge-loop-close task-04，FR-04）──
+  // 判定口径与上方模块上下文注入同锚（quickFirstStep）：查询串用 guard.taskDescription 现成
+  // 读取（X-008——changeName 是 quick-<hash> 无语义）；命中追加「📚 命中知识」段到 prompt 末尾
+  // （top-3 同规则），并 appendKnowledgeHit 落 hits.jsonl；未命中零字节（prompt 与现状字节一致，
+  // 零命中静默）。全链 fail-soft：注入失败不阻断 quick 启动。
+  if (quickFirstStep) {
+    try {
+      const kiSpecBase = resolvePromptSpecBase(platformOpts, cwd)
+      const kiQuery = String(readQuickGuardField(changeName, kiSpecBase, 'taskDescription') || '')
+      if (kiQuery.trim() !== '') {
+        const ki = buildKnowledgeInjection({
+          knowledgeDir: join(kiSpecBase, 'knowledge'),
+          runtimeDir: join(kiSpecBase, '.runtime'),
+          change: changeName || '',
+          query: kiQuery,
+        })
+        if (ki.section) {
+          promptText = promptText + '\n\n' + ki.section
+        }
+      }
+    } catch { /* fail-soft：知识注入异常不阻断 quick step1 prompt 输出 */ }
+  }
+
   // ── 语义护栏进场注入（task-05，FR-03，D-001@v1 模块四）──
   // 判定口径独立：与上方模块上下文注入同锚（quickFirstStep——quick step1「理解任务」），不嵌进
   // {QUICK_CONTEXT_DIGEST} 占位符守卫内——模板改版去占位符时护栏静默失效（plan 审查 N2）。
@@ -1223,10 +1428,15 @@ 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 形态——
+  // 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 "你的摘要"`
+  // 意图断言（坑 execute-concurrent-done-skips-next-wave 终解）：execute 的 Wave 步骤是动态
+  // 步骤表，并发 --done 会落到错误 Wave 且用旧摘要静默完成——完成命令带 --step "<本步名>"
+  //（CLI 校验一致才放行），照抄命令即得并发防护。仅 execute 注入（quick/静态阶段测试断言
+  // 提示格式，且静态步骤名稳定无漂移风险）。
+  const stepAssertFlag = (stageName === 'execute' && step?.name) ? ` --step "${step.name}"` : ''
+  const doneCommand = `sillyspec run ${cmdStage} --done${confirmFlag}${stepAssertFlag}${changeFlag} --output "你的摘要"`
   if (requiresWait) {
     console.log(`本步骤必须等待用户输入，不能直接 --done：`)
     console.log(`sillyspec run ${cmdStage} --wait --reason "${step.waitReason || '等待用户输入'}" --options "${(step.waitOptions || ['确认']).join(',')}"${changeFlag} --output "你的问题/方案摘要"`)