sillyspec 3.28.7 → 3.28.9

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'
@@ -485,8 +485,14 @@ export async function enforceReviewJsonGate(stageName, cwd, changeName, step, st
  * 若校验失败不回滚，DB 会与真实产物不一致（hook/doctor/下游阶段全部误判），
  * 且所有步骤都是 completed 时 agent 无法重新 --done（"没有待完成的步骤"）。
  * 此处将 stage 回滚为 in-progress，最后一步重置为 pending，供修复产物后重做。
+ *
+ * 批量乐观标记一并回滚（坑 execute-batch-rollback-half-state，2026-08-29 用户实证）：execute
+ * 批量完成（detectExecuteBatchFinish）把剩余步骤批量标 completed 后任一收尾 gate 失败，原先只
+ * 回滚 currentIdx → 落库「步骤 11 pending + 12-16 completed」半套状态，步骤序倒挂、要再补一次
+ * --done 才对齐。批量标记打 _batchAligned 戳（内存字段不落库），gate 失败 = 批量完成整体不成立，
+ * 戳上的步骤随当前步一起回滚 pending，下次 --done 满足条件再重新批量标记。
  */
-function rollbackStageCompletion(stageData, steps, currentIdx) {
+export function rollbackStageCompletion(stageData, steps, currentIdx) {
   // 辅助阶段在 validator 前已被重置为 pending（steps 也换成了新数组），不要覆盖
   if (stageData.status === 'completed') {
     stageData.status = 'in-progress'
@@ -496,6 +502,14 @@ function rollbackStageCompletion(stageData, steps, currentIdx) {
     steps[currentIdx].status = 'pending'
     steps[currentIdx].completedAt = null
   }
+  for (const s of steps) {
+    if (!s) continue
+    if (s._batchAligned && s.status === 'completed') {
+      s.status = 'pending'
+      s.completedAt = null
+    }
+    s._batchAligned = false
+  }
 }
 
 /**
@@ -511,7 +525,7 @@ function rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx,
   // friction 尾参（friction-signal-hint task-02）：gate 失败摩擦埋点标签 {type, detail}——各调用点
   // 按所属 gate 段传来源标签（审查两段走 review_rejected），未传兜底通用 gate-cascade。
   // recordFrictionEvent 自带静默降级（非法类型/写失败返回 null），不影响回滚/返回语义。
-  recordFrictionEvent({ cwd, changeName, platformOpts, ...(friction || { type: 'gate_rollback', detail: 'gate-cascade' }) })
+  void recordFrictionEvent({ cwd, changeName, platformOpts, ...(friction || { type: 'gate_rollback', detail: 'gate-cascade' }) })
   rollbackStageCompletion(stageData, steps, currentIdx)
   progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })
   pm._write(cwd, progress, changeName)
@@ -629,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 不可用 → 照旧
@@ -646,7 +682,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
         const { createVerifyGateSnapshot } = await import('./gate-snapshot.js')
         verifyGateSnap = await createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts })
         if (verifyGateSnap) {
-          console.log(`🧪 Verify 实测隔离快照：HEAD + 本变更 ${verifyGateSnap.changeFileCount} 个文件${verifyGateSnap.sourceRoot ? '（overlay 自 worktree——本变更分支内容定向跑）' : ''}（并行会话脏文件不参与门判定）`)
+          console.log(`🧪 Verify 实测隔离快照（根：${verifyGateSnap.snapshotRoot}）：HEAD + 本变更 ${verifyGateSnap.changeFileCount} 个文件${verifyGateSnap.sourceRoot ? '（overlay 自 worktree——本变更分支内容定向跑）' : ''}（并行会话脏文件不参与门判定）`)
         }
       } catch { /* 快照链路异常 → 主仓现行为 */ }
     }
@@ -679,7 +715,11 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
       }
     } catch { /* fail-soft：回填失败不影响门禁 */ }
     if (testCheck.status === 'failed') {
-      if (verifyGateSnap) { try { verifyGateSnap.cleanup() } catch {} ; verifyGateSnap = null }
+      if (verifyGateSnap) {
+        try { const { printSnapshotFailureHint } = await import('./gate-snapshot.js')
+          printSnapshotFailureHint(verifyGateSnap) } catch { /* 提示失败不影响阻断 */ }
+        try { verifyGateSnap.cleanup() } catch {} ; verifyGateSnap = null
+      }
       console.error('\n❌ verify 阶段被阻断：verify-result.md 自报告通过，但 CLI 实测测试失败。')
       // 并行 WIP 归因鉴别（坑 verify-reconcile-foreign-wip）：单一实现迁至 verify-quality-scan.js
       // renderVerifyTestAttribution（P0-1 前置二：noAI 质量扫描失败路径与本 --done 路径共用，
@@ -700,13 +740,21 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     if (lintCheck) {
       console.log(`\n♻️ Verify lint 对账：复用 noAI 质量扫描步的实测结果（代码指纹匹配，免重跑）`)
     } else {
-      lintCheck = runVerifyLintCheck({ cwd: gateCwd, specBase: gateSpecBase })
+      lintCheck = runVerifyLintCheck({ cwd: gateCwd, specBase: gateSpecBase, timeoutMs: verifyGateSnap ? 5 * 60 * 1000 : undefined })
+    // 快照 lint 超时回退主仓（2026-09-12 dogfood 两连实证：junction I/O 病态慢，3min/5min 均被
+    // 超时杀——主仓 60~110s 正常。按用户建议「自动回退」而非假败/advisory：主仓复跑保硬门，
+    // 并行噪声混入时失败输出带归属鉴定提示）
+      if (verifyGateSnap && lintCheck.status === 'failed' && /超时/.test(String(lintCheck.reason || ''))) {
+        console.warn('⚠️ 快照 lint 超时（node_modules junction I/O 慢）→ 主仓复跑 lint（并行噪声可能混入——失败先做归属鉴定）')
+        lintCheck = runVerifyLintCheck({ cwd, specBase })
+      }
       if (lintCheck.status !== 'skipped') {
         console.log(`\n⏳ Verify lint 对账：CLI 亲自执行 local.yaml 的 commands.lint…`)
       }
     }
     // 快照收尾（test+lint 两检查都已完成；parity/删除探针走主仓 git 事实不依赖快照）
     const usedSnapshot = Boolean(verifyGateSnap)
+    const usedSnapInfo = verifyGateSnap ? { snapshotRoot: verifyGateSnap.snapshotRoot, changeFileCount: verifyGateSnap.changeFileCount, sourceRoot: verifyGateSnap.sourceRoot } : null
     if (verifyGateSnap) { try { verifyGateSnap.cleanup() } catch {} ; verifyGateSnap = null }
     printVerifyLintCheck(lintCheck)
     // lint 硬门（2026-09-09 升硬：观察期 14 次 5 败全真阳性，pre-push 本就硬拦——fail-fast 前移；
@@ -714,6 +762,10 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     const { shouldBlockVerifyLint } = await import('../verify-postcheck.js')
     if (shouldBlockVerifyLint(lintCheck)) {
       console.error('\n❌ verify 阶段被阻断：CLI 亲自实测 lint 失败（agent 的 lint 自报告与实测不符时以实测为准）。')
+      if (usedSnapInfo) {
+        try { const { printSnapshotFailureHint } = await import('./gate-snapshot.js')
+          printSnapshotFailureHint(usedSnapInfo) } catch { /* 提示失败不影响阻断 */ }
+      }
       if (lintCheck.outputTail) {
         const tail = lintCheck.outputTail.split('\n').slice(-8).join('\n')
         console.error('   输出（末尾）：')
@@ -1121,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 })) {
@@ -1138,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`)
+  }
 }
 
 /**
@@ -1309,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

@@ -22,13 +22,18 @@ import { basename, join } from 'node:path'
 import { existsSync, readFileSync, mkdirSync, readdirSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { stageRegistry } from '../stages/index.js'
-import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, parsePorcelainPath, WAIT_MARKER_RE, QUICK_SID_RE } from './shared.js'
+import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, parsePorcelainPath, WAIT_MARKER_RE, QUICK_SID_RE, triggerStepStartSync } from './shared.js'
 import { renderSemanticGuardBlock, readSemanticGuardEnabled } from '../semantic-guard.js'
 import { renderStageContract } from '../stage-contract-spec.js'
 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 单向）。
 /**
@@ -309,6 +403,14 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     return false
   }
 
+  // X3 渲染侧接线（2026-08-29-change-delete-closure-and-spec-pull 遗留活跃坑收口；曾因并行
+  // 会话提交丢弃一次，2026-09-12 复检重接）：步骤 prompt 渲染即步骤起点——补推一次 progress
+  // 刷新平台 last_pushed_at（停滞判定不再把长步骤误报为「停滞」）。不 await：prompt 渲染不被
+  // 网络阻塞；未连接平台静默 / quick 会话降级跳过 / 8s 熔断 / 失败只 warn，契约全在
+  // triggerStepStartSync 内（shared.js docstring 即本接线点的说明），Node 事件循环保证在飞
+  // POST 落地后进程才退出。
+  triggerStepStartSync(cwd, changeName, platformOpts)
+
   // ── 首个 agent 可见步索引（「首步一次建立」类注入的锚点）──
   // step0 为 noAI（brainstorm/execute/verify 的 step1「进度确认」，2026-09-07）时不渲染 prompt，
   // persona/护栏/完成契约/铁律/平台路径约束等 step0 专属注入须顺延到首个渲染步，否则整段丢失
@@ -746,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）
@@ -766,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 + ')')
     }
@@ -1100,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）。

package/src/run/quick-audit.js

@@ -137,6 +137,17 @@ export function printQuickAuditReview(review) {
     }
     console.warn(`   quick 不强制文档同步，欠账已随本条 QUICKLOG「审计：」行落盘（可事后追溯）。若改动触及接口/契约，建议顺手同步模块文档。`)
   }
+  // spec 共享面他者噪声（坑 foreign-spec-churn-fail-closed）：并行会话归档移动/文档收尾的
+  // 删除与 EOL-only 假 M——软警告点名归因，不再逼 --allow-delete/--allow-new 解锁。
+  if (review.foreignSpecChurn && review.foreignSpecChurn.length > 0) {
+    console.warn(`⚠️ spec 共享面 ${review.foreignSpecChurn.length} 个非本会话声明的删除（.sillyspec/ docs/，疑似并行会话归档移动/收尾——归其会话收口，本会话不阻断）：`)
+    for (const f2 of review.foreignSpecChurn.slice(0, 6)) console.warn(`   - ${f2}`)
+    if (review.foreignSpecChurn.length > 6) console.warn(`   … 共 ${review.foreignSpecChurn.length} 个`)
+  }
+  if (review.eolOnlyFiles && review.eolOnlyFiles.length > 0) {
+    console.warn(`⚠️ ${review.eolOnlyFiles.length} 个文件仅行尾重写（内容零变化，gen:types/编辑器 CRLF 假 M——已剔出本会话审计）：${review.eolOnlyFiles.slice(0, 5).join('、')}${review.eolOnlyFiles.length > 5 ? ' 等' : ''}`)
+    console.warn(`   根治：.gitattributes 声明 text=auto eol=lf（或按文件类型钉死），生成器重写不再制造假 M`)
+  }
   if (review.docsCheckHint && review.docsCheckHint.invalid > 0) {
     console.warn(`\n📎 文档引用失效（docs check）：本次改动的文档含 ${review.docsCheckHint.invalid}/${review.docsCheckHint.total} 处失效 file:line 引用。`)
     // 逐条指名（2026-09-11 用户实证：只报计数不指名哪处，四轮复现才定位——门禁输出
@@ -167,14 +178,97 @@ export function printQuickAuditReview(review) {
       else console.warn(`   行号漂移 → 更新到当前源码；跑 sillyspec docs check 可看建议行号。`)
     }
   }
+
+  // ── [gate] 分级门禁 advisory 块（FR-03，2026-09-14-quick-exit-tiered-gates task-02）：L1/L2 画像
+  // 打印级别/跨度/模块清单/风险命中/检查项 + --no-docs 指引，L0 零输出。全部 advisory：不改 status
+  // 三态与 exit code（D-003）；窗口内未声明脏文件维持既有归属分流（上方 ⚖️/🔍 块），不并入文档
+  // 认领判定（D-005）；数据源 = review.gateProfile（auditQuickCompletion 挂载，scope-audit 重放同源）。
+  const gate = review.gateProfile
+  if (gate && (gate.level === 'L1' || gate.level === 'L2')) {
+    const isL2 = gate.level === 'L2'
+    const spanTxt = gate.degraded
+      ? 'module-map 缺失（降级档：按文件数判级）'
+      : `跨 ${gate.moduleSpan} 模块${Array.isArray(gate.modules) && gate.modules.length > 0 ? `（${gate.modules.map(m => m.id).join(' · ')}）` : ''}`
+    console.warn(`\n${isL2 ? '🛑' : '🚧'} [gate] ${gate.level} 规模门（${spanTxt} · ${gate.fileCount} 文件：${gate.codeFileCount} 代码 / ${gate.testFileCount} 测试）——advisory 提示不阻断：`)
+    if (Array.isArray(gate.unmappedFiles) && gate.unmappedFiles.length > 0) {
+      console.warn(`   ⚠️ ${gate.unmappedFiles.length} 个文件未命中 module-map（${gate.unmappedFiles.slice(0, 5).join(', ')}${gate.unmappedFiles.length > 5 ? ' 等' : ''}）`)
+    }
+    if (!isL2) {
+      // L1 检查项：每文件注记（--file-notes 覆盖率）+ 测试增量（机械规则）
+      console.warn(`   - 每文件注记检查：${gate.checks?.perFileNotes ? '✅ --file-notes 已覆盖全部变更文件' : `❌ 缺失——补 --file-notes "path1::注 || path2::注"（覆盖变更文件全集）`}`)
+      const td = gate.checks?.testDelta
+      console.warn(`   - 测试增量检查：${td === 'missing' ? `❌ missing——${gate.codeFileCount} 个代码文件改动无测试文件（补 test 改动进本会话）` : td === 'ok' ? '✅ 已含测试改动' : '— 不适用（≤1 代码文件）'}`)
+    } else {
+      // L2 检查项：模块文档认领（claimed/missing/exempt-no-docs）+ 风险命中的运行时证据要求
+      const dc = gate.checks?.docClaim
+      const noClaimable = gate.degraded || !Array.isArray(gate.modules) || gate.modules.length === 0
+      if (dc === 'exempt-no-docs') {
+        console.warn(`   - 模块文档认领：🛡️ 已 --no-docs 显式豁免（豁免已留痕 QUICKLOG 审计行）`)
+      } else if (noClaimable) {
+        // degraded / 无触及模块：computeGateProfile 空真 claimed——如实显示不适用，不出「已认领」误导
+        console.warn(`   - 模块文档认领：— 不适用（${gate.degraded ? '无 module-map' : '触及文件均未命中模块'}，无可认领卡片）`)
+      } else if (dc === 'claimed') {
+        console.warn(`   - 模块文档认领：✅ 触及模块的卡片文件已在改动集`)
+      } else {
+        console.warn(`   - 模块文档认领：❌ missing——触及模块（${Array.isArray(gate.modules) && gate.modules.length > 0 ? gate.modules.map(m => m.id).join(' · ') : '—'}）的卡片文件不在改动集`)
+        console.warn(`     ➜ 同步模块卡进本次改动，或确认无需文档落盘时 --done 带 --no-docs 显式豁免（豁免留痕，不阻断完成）`)
+      }
+      if (Array.isArray(gate.riskHits) && gate.riskHits.length > 0) {
+        console.warn(`   - 风险命中 ${gate.riskHits.length} 处（运行时证据要求——风险路径改动需在 --result「结果：」附运行验证说明，advisory 不等待）：`)
+        for (const h of gate.riskHits.slice(0, 8)) {
+          console.warn(`       ⚠️ ${h.pattern} ← ${h.file}`)
+        }
+        if (gate.riskHits.length > 8) console.warn(`       … 共 ${gate.riskHits.length} 处`)
+      }
+    }
+  }
 }
 
 /**
- * quick 阶段多变更交互式选择关联变更。
- * - 0 活跃变更 → []（仅记 QUICKLOG，不关联）
- * - 1 活跃变更 → 默认关联它（保持现状友好，不弹交互）
+ * [gate] 分级门禁 auditNote 组装（FR-03 task-02，gate-audit-note）：L1/L2 → 单行 `[gate]` 注记
+ * （随 complete-handlers 既有 auditNotes 通道落 QUICKLOG，--no-docs 豁免同通道留痕）；
+ * L0 / 无画像 → null（零落账，验收「L0 无 gate 落账行」）。纯函数、与上方 [gate] 打印块同一
+ * review.gateProfile 数据源；单独导出为可测（buildSemanticGuardHits 同款考量——避开
+ * handleQuickStageCompletion 的 quicklog 重机件直测组装层）。
+ * @param {object|null} gate review.gateProfile（auditQuickCompletion 产物；null/异常形状 → null）
+ * @returns {string|null}
+ */
+export function buildGateAuditNote(gate) {
+  if (!gate || typeof gate !== 'object' || (gate.level !== 'L1' && gate.level !== 'L2')) return null
+  const span = gate.degraded
+    ? 'module-map 缺失（降级档按文件数判级）'
+    : `跨 ${gate.moduleSpan} 模块`
+  const seg = [`[gate] ${gate.level}（${span} · ${gate.fileCount} 文件：${gate.codeFileCount} 代码/${gate.testFileCount} 测试）advisory`]
+  if (gate.level === 'L1') {
+    seg.push(`每文件注记${gate.checks?.perFileNotes ? '已全覆盖' : '缺失（--file-notes 覆盖变更文件全集）'}`)
+    const td = gate.checks?.testDelta
+    seg.push(`测试增量${td === 'ok' ? '已含' : td === 'missing' ? `缺失（${gate.codeFileCount} 个代码文件无测试改动）` : '不适用（≤1 代码文件）'}`)
+  } else {
+    const dc = gate.checks?.docClaim
+    const noClaimable = gate.degraded || !Array.isArray(gate.modules) || gate.modules.length === 0
+    seg.push(dc === 'exempt-no-docs' ? '模块文档认领已 --no-docs 显式豁免'
+      : noClaimable ? '模块文档认领不适用（无可认领模块）'
+        : dc === 'claimed' ? '模块文档认领已覆盖（模块卡在改动集）'
+          : '模块文档认领缺失（同步模块卡进改动集，或 --no-docs 显式豁免）')
+    if (Array.isArray(gate.riskHits) && gate.riskHits.length > 0) {
+      seg.push(`风险命中 ${gate.riskHits.length} 处（${gate.riskHits.slice(0, 5).map(h => `${h.pattern}←${h.file}`).join('、')}${gate.riskHits.length > 5 ? ' 等' : ''}）需运行时证据`)
+    }
+  }
+  return seg.join('；')
+}
+
+/**
+ * quick 阶段关联变更解析（含单候选信号门控）。
+ * - 0 活跃变更 → 不关联
+ * - 1 活跃变更 → 跑 recommendChanges 双信号打分：命中（score>0）→ 自动关联 + 大声提示
+ *   + autoLinked 溯源；未命中 → 不关联 + 提示。坑 quick-single-change-auto-link（2026-09-14
+ *   实证）：原实现无条件 `return [activeChanges[0]]`——多 agent 仓库里唯一活跃变更常是他者
+ *   会话遗留，挂载污染 tasks.md 且 --done 僵尸清理通道可误归档他者变更；单候选还绕过
+ *   recommend 的 quick-<hex8> 会话过滤（新 quick 互挂另一活跃 quick）。
  * - ≥2 活跃变更 + 交互 → checkbox 多选（推荐项默认勾，空选 = 不关联）
- * - ≥2 活跃变更 + 非交互 → []（不关联）+ 提示用 --change a,b
+ * - ≥2 活跃变更 + 非交互 → 不关联 + 提示用 --change a,b
+ * @returns {Promise<{changes: string[], autoLinked: string[]}>} changes=最终关联清单；
+ *   autoLinked=其中机器自动关联的子集（guard 落 linkedChangesAuto 溯源，--done 归档闸消费）
  */
 export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles, taskDescription, nonInteractive }) {
   let activeChanges = []
@@ -183,13 +277,7 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
   } catch {
     activeChanges = []
   }
-  if (activeChanges.length === 0) return []
-  if (activeChanges.length === 1) return [activeChanges[0]]
-
-  if (nonInteractive || !process.stdin.isTTY) {
-    console.log('💡 非交互环境，已默认不关联变更；如需关联请用 --change a,b')
-    return []
-  }
+  if (activeChanges.length === 0) return { changes: [], autoLinked: [] }
 
   // 脏文件（推荐信号之一）。safeGit 带 safe.directory，避免 linked worktree/容器/挂载点下裸
   // `git status` 抛错致推荐信号静默丢失（multi-agent-review Q3 同类）。推荐非关键路径，失败回退 []。
@@ -203,7 +291,7 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
       .filter(f => !f.startsWith('.sillyspec/'))
   }
 
-  // 推荐打分（脏文件 + 任务描述双信号）
+  // 推荐打分（脏文件 + 任务描述双信号）——单候选也跑（信号门控），非仅 ≥2 交互推荐用
   let recommendations = []
   try {
     // quick-recommend.js 在 src/，本模块在 src/run/ → 退一层（真环依赖，保留动态 import）
@@ -212,6 +300,26 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
   } catch {
     recommendations = activeChanges.map(name => ({ name, score: 0, reasons: [] }))
   }
+
+  // 单候选信号门控（坑 quick-single-change-auto-link）：有真实信号（脏文件命中 design 清单 /
+  // 任务描述命中 proposal）才自动关联，且大声提示可反悔；无信号一律不关联。quick-<hex8> 会话
+  // 行已被 recommendChanges 过滤 → recommendations 无该候选 → 不关联（防会话互挂）。
+  if (activeChanges.length === 1) {
+    const name = activeChanges[0]
+    const rec = recommendations.find(r => r.name === name)
+    if (rec && rec.score > 0) {
+      console.log(`🔗 唯一活跃变更 ${name} 命中关联信号（${rec.reasons.slice(0, 2).join('；')}）——已自动关联；无关请带 --linked-changes none 重启`)
+      return { changes: [name], autoLinked: [name] }
+    }
+    console.log(`💡 唯一活跃变更 ${name} 未命中关联信号（任务描述/脏文件无重叠）——默认不关联；如需关联请带 --linked-changes ${name} 重启`)
+    return { changes: [], autoLinked: [] }
+  }
+
+  if (nonInteractive || !process.stdin.isTTY) {
+    console.log('💡 非交互环境，已默认不关联变更；如需关联请用 --change a,b')
+    return { changes: [], autoLinked: [] }
+  }
+
   const scoreMap = new Map(recommendations.map(r => [r.name, r.score]))
   const reasonMap = new Map(recommendations.map(r => [r.name, r.reasons]))
   const recommendedSet = new Set(recommendations.filter(r => r.score > 0).map(r => r.name))
@@ -238,7 +346,8 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
   // 动态 import：@inquirer/prompts 只在本交互分支加载，不进 run 命令通用启动路径
   const { checkbox } = await import('@inquirer/prompts')
   const selected = await checkbox({ message: '关联变更（空格切换，回车确认）', choices })
-  return selected
+  // 用户在 TTY 上亲手勾选确认 = 显式协作声明，不进 autoLinked
+  return { changes: selected, autoLinked: [] }
 }
 
 // ============ quick --done test+lint 硬门禁（2026-09-02 跨 agent 工单 P0-2）============
@@ -338,16 +447,28 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
       if (snapshot) {
         gateCwd = snapshot.snapshotRoot
         gateSpecBase = join(snapshot.snapshotRoot, '.sillyspec')
-        console.log(`🧪 门禁隔离快照：HEAD + 本会话 ${snapshot.overlaid} 个文件（并行会话脏文件不参与判定）`)
+        console.log(`🧪 门禁隔离快照（根：${snapshot.snapshotRoot}）：HEAD + 本会话 ${snapshot.overlaid} 个文件（并行会话脏文件不参与判定）`)
       }
     } catch { /* 快照链路异常 → 主仓现行为 */ }
   }
   try {
     const test = runVerifyTestCheck({ cwd: gateCwd, specBase: gateSpecBase, changeName })
-    const lint = runVerifyLintCheck({ cwd: gateCwd, specBase: gateSpecBase })
+    let lint = runVerifyLintCheck({ cwd: gateCwd, specBase: gateSpecBase, timeoutMs: snapshot ? 5 * 60 * 1000 : undefined })
+    // 快照 lint 超时回退主仓（2026-09-12 dogfood 两连实证：junction I/O 病态慢，3min/5min 均被
+    // 超时杀——主仓 60~110s 正常。按用户建议「自动回退」而非假败/advisory：主仓复跑保硬门，
+    // 并行噪声混入时失败输出带归属鉴定提示）
+    if (snapshot && lint.status === 'failed' && /超时/.test(String(lint.reason || ''))) {
+      console.warn('⚠️ 快照 lint 超时（node_modules junction I/O 慢）→ 主仓复跑 lint（并行噪声可能混入——失败先做归属鉴定）')
+      lint = runVerifyLintCheck({ cwd, specBase })
+    }
     const failed = []
     if (test.status === 'failed') failed.push('test')
     if (lint.status === 'failed') failed.push('lint')
+    if (failed.length > 0 && snapshot) {
+      try { const { printSnapshotFailureHint } = await import('./gate-snapshot.js')
+        printSnapshotFailureHint({ snapshotRoot: snapshot.snapshotRoot, changeFileCount: snapshot.overlaid, sourceRoot: snapshot.sourceRoot || null }, { offEnv: 'SILLYSPEC_QUICK_GATE_SNAPSHOT_OFF' })
+      } catch { /* 提示失败不影响门禁语义 */ }
+    }
     return {
       action: failed.length > 0 ? 'fail' : 'pass',
       failed,