sillyspec 3.28.8 → 3.28.9

package/src/run/complete.js

@@ -23,6 +23,7 @@ import { writeAtomicSync } from '../fs-atomic.js'
 import { gitQuiet } from '../git-helper.js'
 import { withFileLock } from '../quicklog.js'
 import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir } from './shared.js'
+import { isExplicitReviewWrite } from '../task-review.js'
 
 // auto 模式 brainstorm 步骤表感知解析（2026-09-08 E2E 实证 bug：--done/--wait 推进主模式 8 步表，
 // 与 runAutoMode getAutoSteps 的 4 步 auto 表双轨互踩——ensureAutoStage 判非 auto 表重种清零，
@@ -119,7 +120,7 @@ export function synthesizeStepOutput({ stageName, stepName, cwd }) {
 }
 
 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, quickFiles = [] } = options
+  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false, isNoDocs = false, isSkipApply = false, sessionFlag = null, quickFiles = [] } = options
   // specRoot(平台) > specDriftAnchor(worktree 漂移锚定主仓) > cwd/.sillyspec(本地)——
   // 与 prompt.js resolvePromptSpecBase 同序：--done 收尾的 user-inputs.md/超长 artifact 落盘
   // 必须与 prompt 渲染同一根，否则写进 worktree 副本目录、随 cleanup 整目录删除。
@@ -494,7 +495,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   // archive「确认归档」收尾：--confirm 门控 + archiveChangeDirectory 移动 + 推荐文档校验
   // （抽成 handleArchiveConfirmStep；缺 --confirm 时返回 early-return 对象，completeStep 透传）
   {
-    const _archiveEarlyReturn = await handleArchiveConfirmStep({ stageName, steps, currentIdx, confirm, outputText, pm, cwd, progress, changeName, specBase, platformOpts })
+    const _archiveEarlyReturn = await handleArchiveConfirmStep({ stageName, steps, currentIdx, confirm, outputText, pm, cwd, progress, changeName, specBase, platformOpts, isSkipApply, sessionFlag })
     if (_archiveEarlyReturn) return _archiveEarlyReturn
   }
 
@@ -568,8 +569,10 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       console.log(`   恢复：sillyspec run ${stageName} --continue --answer "用户回答"${changeName ? ` --change ${changeName}` : ''}`)
       return { stageCompleted: false, currentIdx, nextPendingIdx: -1 }
     }
-    // quick 收尾（W6 Step6b 抽至 complete-handlers.js handleQuickStageCompletion）
-    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, platformOpts, pm, quickFiles })
+    // quick 收尾（W6 Step6b 抽至 complete-handlers.js handleQuickStageCompletion）；
+    // isNoDocs（task-02）--no-docs 豁免随链透传进 auditQuickCompletion options；
+    // sessionFlag（task-03）--session 随链透传进 quick 轻量归档链所有权校验
+    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, isNoDocs, sessionFlag, platformOpts, pm, quickFiles })
 
     // ── reopen --done 回填（坑 brainstorm-reopen-step-state-desync）──
     // nextPendingIdx === -1 且无 waiting，说明要进阶段完成分支。此时若存在 stale 步骤
@@ -675,7 +678,16 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
         const { consumeFrictionHint } = await import('../friction-tally.js')
         const r = await consumeFrictionHint({ cwd, changeName, platformOpts })
         if (r && r.hint) console.log(`\n${r.hint}`)
-      } catch { /* 摩擦提示失败不影响收尾 */ }
+        // 台账滚动（2026-09-15-tax-governance FR-02 主滚动点）：consume 得到的非零 counts 按
+        // change 滚动合并进 <runtimeRoot>/friction-ledger.json 幸存台账（merge-by-change——
+        // --reopen 重跑二次 consume 累加非双计）；空 counts 跳过写（防干净收尾落空文件）；
+        // archivedAt 此时不落（prune 侧落定）；runtimeRoot 与 consume 同源（specBase 同变量
+        // + resolveRuntimeRoot 单点）。台账写失败 fail-soft 在既有 try/catch 内，绝不阻断收尾。
+        if (changeName && r && r.counts && Object.keys(r.counts).length > 0) {
+          const { mergeFrictionEntry } = await import('../friction-ledger.js')
+          await mergeFrictionEntry(resolveRuntimeRoot(platformOpts, specBase), { change: changeName, counts: r.counts })
+        }
+      } catch { /* 摩擦提示/台账失败不影响收尾 */ }
     }
 
     if (stageName === 'execute') {
@@ -834,7 +846,7 @@ async function printExecuteScopeAudit({ cwd, changeName, specBase, platformOpts,
     if (typeof frozenPatch === 'string') {
       const patchText = frozenPatch.endsWith('\n') ? frozenPatch : frozenPatch + '\n'
       writeFileSync(join(changeDir, 'scope-audit.patch'), patchText)
-      snap.patchSha256 = createHash('sha256').update(patchText, 'utf8').digest('hex')
+      snap.patchSha256 = createHash('sha256').update(patchText.replace(/\r\n/g, '\n'), 'utf8').digest('hex')
       snap.patchStatus = 'ok'
     } else if (frozenPatch === null) {
       snap.patchStatus = 'failed'
@@ -975,35 +987,49 @@ function prefetchDiffFileSet(ctx) {
  * changedFiles 非空且 git diff 实测非空。防 allowed_paths 误归属他人 diff 或陈旧 review.json 导致
  * 空任务被自动勾选/批量放行。ctx 缺省时保持现行判定（向后兼容）。
  *
- * @param {{ok?:boolean, review?:{specVerdict?:string, qualityVerdict?:string, reviewerNotes?:string, changedFiles?:string[]}}} r readReview 结果
+ * ql-20260915-001 修复②（坑 review-write-draft-marker-stuck，2026-09-14 用户实证：文档面任务
+ * 反复「草稿 changedFiles 为空，跳过自动勾选」断链）：显式 CLI 写入（writeTaskReview 通道，
+ * writtenBy 锚定，带 agent 供给 verdict）一律按非草稿处理——不受 changedFiles 空/实测 diff 空
+ * 限制（.sillyspec/ 文档面任务归因被滤、纯验证任务零 diff 是合法形态；agent 已用
+ * review write --force --changed-files 显式表态，verdict 即结论）。草稿守卫警告同步改为
+ * 可行动：含 task 名与解锁命令示例，不再只报现象。
+ *
+ * @param {{ok?:boolean, review?:{specVerdict?:string, qualityVerdict?:string, reviewerNotes?:string, changedFiles?:string[], task?:string, writtenBy?:string}}} r readReview 结果
  * @param {boolean} endToEnd 是否端到端/deployment-critical task
  * @param {{gitDir?:string, base?:string, head?:string}|null} [ctx] 实测 diff 上下文；缺省保持现行判定
+ * @param {string} [changeName] 变更名（草稿守卫警告里解锁命令示例用）
  * @returns {boolean}
  */
-export function shouldAutoCheckTask(r, endToEnd, ctx = null) {
+export function shouldAutoCheckTask(r, endToEnd, ctx = null, changeName = '') {
   if (!r?.ok) return false
   const spec = r.review?.specVerdict
   const quality = r.review?.qualityVerdict
   if (spec === 'fail' || quality === 'fail') return false
   if (endToEnd) return spec === 'pass' && quality === 'pass'
 
+  // ql-20260915-001 修复②：显式 CLI 写入（review write 通道）按非草稿处理，直接勾——
+  // verdict 非 fail 已过上面守卫，文档面/纯验证任务的空 changedFiles 不再拦截
+  if (isExplicitReviewWrite(r.review)) return true
+
   // W2 task-04 草稿零 diff 守卫（FR-03）
   // ctx 给定且 review 为自动草稿时，要求 changedFiles 非空且实测 diff 非空
   if (ctx && r.review?.reviewerNotes && r.review.reviewerNotes.includes('auto-generated draft')) {
+    const taskId = r.review.task || 'task-NN'
+    const unlockCmd = `sillyspec review write${changeName ? ` --change ${changeName}` : ' --change <变更名>'} --task ${taskId} --spec pass --quality pass --force --changed-files <文件>`
     const changedFiles = r.review.changedFiles || []
     if (changedFiles.length === 0) {
-      console.warn(`⚠️ 草稿 review changedFiles 为空，跳过自动勾选`)
+      console.warn(`⚠️ 草稿 review changedFiles 为空，跳过自动勾选（task=${taskId}）——解锁：${unlockCmd}（纯验证任务用 --changed-files "" + --evidence "<验证说明>"）`)
       return false
     }
     if (!ctx.gitDir || !ctx.base || !ctx.head) {
-      console.warn(`⚠️ ctx 信息不完整（gitDir=${ctx.gitDir}, base=${ctx.base}, head=${ctx.head}），跳过草稿 diff 校验，保守不勾`)
+      console.warn(`⚠️ ctx 信息不完整（gitDir=${ctx.gitDir}, base=${ctx.base}, head=${ctx.head}），跳过草稿 diff 校验，保守不勾（task=${taskId}）——解锁：${unlockCmd}`)
       return false
     }
     // 预取路径：一次全量 diff 文件集内存归属（autoCheckPlanFromReviews/批量路径已 prefetch）
     if (ctx.diffFileSet) {
       const hit = changedFiles.filter(f => ctx.diffFileSet.has(f))
       if (hit.length === 0) {
-        console.warn(`⚠️ 草稿 review 实测 diff 为空（base=${ctx.base.slice(0, 8)}, head=${ctx.head.slice(0, 8)}, files=${changedFiles.length}），跳过自动勾选`)
+        console.warn(`⚠️ 草稿 review 实测 diff 为空（task=${taskId}, base=${ctx.base.slice(0, 8)}, head=${ctx.head.slice(0, 8)}, files=${changedFiles.length}），跳过自动勾选——解锁：${unlockCmd}`)
         return false
       }
       console.log(`   ✓ 草稿 diff 校验通过（实测 ${hit.length}/${changedFiles.length} 个声明文件有改动）`)
@@ -1014,12 +1040,12 @@ export function shouldAutoCheckTask(r, endToEnd, ctx = null) {
       // 用数组参数避免 shell 拆词，复用 git-helper 安全模式
       const diffResult = gitQuiet(ctx.gitDir, ['diff', '--name-only', `${ctx.base}..${ctx.head}`, '--', ...changedFiles], { trim: true })
       if (!diffResult || diffResult.trim() === '') {
-        console.warn(`⚠️ 草稿 review 实测 diff 为空（base=${ctx.base.slice(0,8)}, head=${ctx.head.slice(0,8)}, files=${changedFiles.length}），跳过自动勾选`)
+        console.warn(`⚠️ 草稿 review 实测 diff 为空（task=${taskId}, base=${ctx.base.slice(0,8)}, head=${ctx.head.slice(0,8)}, files=${changedFiles.length}），跳过自动勾选——解锁：${unlockCmd}`)
         return false
       }
       console.log(`   ✓ 草稿 diff 校验通过（${diffResult.trim().split('\n').length} 个文件有改动）`)
     } catch (e) {
-      console.warn(`⚠️ 草稿 diff 校验失败（${e && e.message ? e.message : e}），保守不勾`)
+      console.warn(`⚠️ 草稿 diff 校验失败（task=${taskId}: ${e && e.message ? e.message : e}），保守不勾——解锁：${unlockCmd}`)
       return false
     }
   }
@@ -1079,7 +1105,7 @@ export async function autoCheckPlanFromReviews({ stageName, changeName, cwd, pla
           && r.review?.qualityVerdict !== 'fail'
         const endToEnd = verdictUsable
           && isEndToEndTaskText(match + ' ' + readTaskCardText(changeDir, taskNum))
-        if (shouldAutoCheckTask(r, endToEnd, ctx)) {
+        if (shouldAutoCheckTask(r, endToEnd, ctx, changeName)) {
           checkedCount++
           return `${p1}x${p2}`   // 勾选
         }
@@ -1175,7 +1201,10 @@ async function detectExecuteBatchFinish({ pm, stageName, changeName, cwd, specBa
       }
 
       // review 存在：判定是否为自动草稿且零 diff
-      if (review?.reviewerNotes && review.reviewerNotes.includes('auto-generated draft')) {
+      // （ql-20260915-001 修复②：显式 CLI 写入（writeTaskReview 通道）按非草稿处理——不阻断
+      // 批量，与勾选层 shouldAutoCheckTask 同口径；agent 已显式给 verdict 的 review 不该因
+      // notes 字面残留 'auto-generated draft' 被当草稿拦截）
+      if (!isExplicitReviewWrite(review) && review?.reviewerNotes && review.reviewerNotes.includes('auto-generated draft')) {
         const changedFiles = review.changedFiles || []
         // 草稿且 changedFiles 为空 → 阻断
         if (changedFiles.length === 0) {
@@ -1527,7 +1556,16 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
         const { consumeFrictionHint } = await import('../friction-tally.js')
         const r = await consumeFrictionHint({ cwd, changeName, platformOpts })
         if (r && r.hint) console.log(`\n${r.hint}`)
-      } catch { /* 摩擦提示失败不影响收尾 */ }
+        // 台账滚动（2026-09-15-tax-governance FR-02 主滚动点）：consume 得到的非零 counts 按
+        // change 滚动合并进 <runtimeRoot>/friction-ledger.json 幸存台账（merge-by-change——
+        // --reopen 重跑二次 consume 累加非双计）；空 counts 跳过写（防干净收尾落空文件）；
+        // archivedAt 此时不落（prune 侧落定）；runtimeRoot 与 consume 同源（specBase 同变量
+        // + resolveRuntimeRoot 单点）。台账写失败 fail-soft 在既有 try/catch 内，绝不阻断收尾。
+        if (changeName && r && r.counts && Object.keys(r.counts).length > 0) {
+          const { mergeFrictionEntry } = await import('../friction-ledger.js')
+          await mergeFrictionEntry(resolveRuntimeRoot(platformOpts, specBase), { change: changeName, counts: r.counts })
+        }
+      } catch { /* 摩擦提示/台账失败不影响收尾 */ }
     }
     // 阶段完成后明确下一步（agent 常卡：stageData completed 但不知要 run <下一阶段> 推进 currentStage）
     const nextStageHint = { brainstorm: 'plan', plan: 'execute', execute: 'verify', verify: 'archive' }[stageName]

package/src/run/concurrent-detect.js

@@ -12,6 +12,7 @@
  * 纯函数无副作用：不写盘、不 console（console 留给调用点 task-02/03）。
  */
 import { safeGit, parsePorcelainPath, isQuickMetadata } from './shared.js'
+import { basename } from 'node:path'
 
 /**
  * 内联解析 .sillyspec/changes/<dir>/ 路径取 <dir>。
@@ -154,3 +155,100 @@ export function formatConcurrentWarning(detected) {
   lines.push('提交请用显式 pathspec 隔离本变更文件，勿 git add . 扫入他者工作（execute task 内建议 sillyspec wt-commit 串行提交）。')
   return lines.join('\n')
 }
+
+// ── 坑 mixed-baseline-drift-hint（ql-20260915-004）committed-drift 混合基线检测 ──
+// 背景（用户 2026-09-15 实证）：并行会话合并断言不同步——worktree 内基于旧快照写的测试断言
+// （旧 id），主仓已合入 id 统一修复 → verify 测试门红——测试源=worktree 快照、被测源=主仓
+// HEAD 的混合基线漂移此前无任何提示。本函数算「主仓自本变更基点后的已提交推进 ∩ 本变更
+// 相关文件」，交两挂点（worktree-apply 成功尾声 / gates.js verify 测试门前）advisory 提示。
+
+/** 测试形态文件名：foo.test.mjs / foo.spec.js（与探针 7 isProbe7TestPath 的 .test. 口径同族） */
+const DRIFT_TEST_FORM_RE = /\.(?:test|spec)\.[A-Za-z0-9]+$/
+
+/** git 路径反斜杠归一（detectCommittedDrift 内部用，与 normalizeGitPath 同义独立小函数） */
+function toPosix(p) {
+  return String(p || '').replace(/\\/g, '/')
+}
+
+/**
+ * 文件名 stem 键：剥扩展名与 .test./.spec. 中缀（foo.js → foo；foo.test.mjs → foo；
+ * foo_test.js → foo_test——下划线形不在变体口径内，仅精确匹配兜底）。小写归一。
+ */
+function driftStemKey(p) {
+  const name = basename(toPosix(p))
+  const m = name.match(/^(.+?)\.(?:test|spec)\.[A-Za-z0-9]+$/)
+  if (m) return m[1].toLowerCase()
+  const dot = name.lastIndexOf('.')
+  return (dot > 0 ? name.slice(0, dot) : name).toLowerCase()
+}
+
+/**
+ * 检测混合基线漂移（非阻断 advisory 用）：主仓 `git diff --name-only <baseHash>..<head>`
+ * （基点后已提交推进面）∩ 本变更 touchedFiles（或其同 basename 的 .test./.spec. 变体）非空
+ * → drift。变体口径：stem 相同且至少一侧为测试形态（src/foo.js ↔ test/foo.test.mjs）——
+ * 换位覆盖两方向（他者推进我的源文件的测试变体 / 他者推进我测试文件对应的源文件）。
+ *
+ * fail-open：baseHash 缺失 / git 异常 → 返回 null（调用方视为未检测，零输出零阻断）；
+ * diff 空（基点后无推进）→ { drift:false, files:[] }。
+ *
+ * @param {{ projectRoot: string, baseHash: string, touchedFiles: string[],
+ *           excludeFiles?: string[], head?: string }} opts
+ *   - baseHash：worktree 基点（meta.baselineCommit || baseHash）
+ *   - touchedFiles：本变更交付文件面（apply-manifest files / changedFiles）
+ *   - excludeFiles：从推进面剔除的文件（verify 挂点传本变更自身面——apply 已提交时
+ *     baseHash..HEAD 含自身交付，不剔会把「自己合自己」误报成他者推进；apply 挂点用
+ *     精确 preMergeHead，无需剔除）
+ *   - head：推进面终点 ref（缺省 HEAD；merge 路径传 merge 前 HEAD）
+ * @returns {{ drift: boolean, files: string[], hint?: string }|null}
+ */
+export function detectCommittedDrift({ projectRoot, baseHash, touchedFiles, excludeFiles = [], head = 'HEAD' }) {
+  if (!projectRoot || !baseHash) return null
+  const touched = (Array.isArray(touchedFiles) ? touchedFiles : []).map(toPosix).filter(Boolean)
+  if (touched.length === 0) return null
+  // FR fail-open（与 detectConcurrentChanges 同族）：git 读不到不崩不误报
+  const diff = safeGit(projectRoot, ['diff', '--name-only', `${baseHash}..${head}`], { timeout: 30000 })
+  if (diff.error) return null
+  if (!diff.value) return { drift: false, files: [] }
+
+  const excl = new Set((Array.isArray(excludeFiles) ? excludeFiles : []).map(toPosix).filter(Boolean))
+  const touchedSet = new Set(touched)
+  const touchedStems = new Set(touched.map(driftStemKey).filter(Boolean))
+  const touchedHasTestForm = touched.some(f => DRIFT_TEST_FORM_RE.test(basename(f)))
+
+  const files = []
+  for (const raw of diff.value.split('\n').map(s => s.trim()).filter(Boolean)) {
+    const p = toPosix(raw)
+    if (excl.has(p)) continue
+    const exact = touchedSet.has(p)
+    // 变体：非精确命中时，stem 相同且至少一侧为测试形态（防 docs/foo.md ↔ test/foo.test.mjs
+    // 之外的松散同名误报——两侧都非测试形态的不同目录同名不算相关）
+    const variant = !exact
+      && touchedStems.has(driftStemKey(p))
+      && (DRIFT_TEST_FORM_RE.test(basename(p)) || touchedHasTestForm)
+    if (exact || variant) files.push(p)
+  }
+  if (files.length === 0) return { drift: false, files: [] }
+  return {
+    drift: true,
+    files,
+    hint: `主仓自基点 ${String(baseHash).slice(0, 8)} 后已合入触及 ${files.length} 个本变更相关文件的推进（${files.slice(0, 5).join('、')}${files.length > 5 ? ' 等' : ''}）——worktree 快照内验证过的断言可能漂移，建议合并态复跑相关测试`,
+  }
+}
+
+/**
+ * committed-drift 检测结果 → 多行 ⚠️ 提示串（两挂点共用文案，与 formatConcurrentWarning 同族）。
+ * @param {{ drift: boolean, files?: string[], hint?: string }|null} drift detectCommittedDrift 产物
+ * @param {{ tailNote?: string }} [opts] tailNote 追加在首行末的挂点语境注（如 verify 挂点的
+ *   「实测若红先做合并态归因」）；缺省无
+ * @returns {string|null} 无漂移/未检测返回 null
+ */
+export function formatCommittedDriftWarning(drift, opts = {}) {
+  if (!drift || !drift.drift) return null
+  const files = Array.isArray(drift.files) ? drift.files : []
+  const note = opts.tailNote ? `（${opts.tailNote}）` : ''
+  return [
+    '⚠️ 混合基线提示：主仓自本变更基点后已合入触及以下本变更相关文件的推进'
+      + `（${files.length} 个）——worktree 快照内验证过的断言可能漂移，建议合并态复跑相关测试${note}：`,
+    ...files.map(f => `  - ${f}`),
+  ].join('\n')
+}

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'
@@ -643,6 +643,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 不可用 → 照旧
@@ -1151,13 +1173,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 +1194,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 +1380,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) {

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,6 +225,95 @@ 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 单向）。
 /**
@@ -754,9 +848,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 +872,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 + ')')
     }
@@ -1108,6 +1214,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）。