sillyspec 3.31.0 → 3.32.1

package/src/run/gates.js

@@ -34,6 +34,7 @@ import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, unlinkSync,
 import { writeAtomicSync } from '../fs-atomic.js'
 import { triggerSync, resolveChangeDir, resolveRuntimeRoot } from './shared.js'
 import { runValidators } from '../stage-contract.js'
+import { computeGateFingerprint, lookupGreenCache, storeGreenCache, greenCacheNotice } from './green-cache.js'
 import { handleScanStageCompleted, handleExecuteWorktreeCleanup } from './complete-handlers.js'
 
 /**
@@ -956,6 +957,19 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
       if (consult.reuse) ledgerReuse = consult
     } catch { /* 账本咨询异常 → 真跑 */ }
     }
+    // ── R8 green-cache 第二层复用（2026-09-30-verify-done-green-reuse）：--done 收敛循环防重复
+    //    真跑。同指纹（HEAD+代码脏面+local.yaml，文档面剔除——green-cache.js 单点口径）30min 内
+    //    真跑绿 → 免重跑。实证：multi-agent-platform 2026-09-30 tool-report-activation 收敛循环
+    //    码态恒定（12:59-14:15 零 commit）下 test 实测 10 轮 ×~290s 全真跑——P2 账本 miss 即裸奔，
+    //    本层兜住。指纹取主仓 cwd/specBase（非快照根：快照目录每轮不同，入指纹永不命中；快照
+    //    内容 = HEAD+变更文件 overlay，主仓指纹等价描述）。优先级：P2 账本（三键精确）>
+    //    P0-1 质量扫描复用 > 本层 > 真跑；fail-open：指纹/缓存任何异常一律回退真跑。──
+    let greenHit = null
+    let gateFingerprint = null
+    try {
+      gateFingerprint = computeGateFingerprint({ cwd, specBase })
+      if (gateFingerprint) greenHit = lookupGreenCache({ runtimeRoot: resolveRuntimeRoot(platformOpts, specBase), scope: changeName, kind: 'test', fingerprint: gateFingerprint })
+    } catch { /* fail-open：缓存链异常回退真跑 */ }
     if (ledgerReuse) {
       testCheck = {
         status: 'passed',
@@ -970,6 +984,16 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
       testCheck = reusableScan.testResult
       console.log(`\n♻️ Verify 测试对账：复用 noAI 质量扫描步的实测结果（代码指纹匹配，免重跑；实测于 ${reusableScan.ranAt || '本变更 verify 期间'}${testCheck.resultPath ? `，台账 ${testCheck.resultPath}` : ''}）`)
       printVerifyTestCheck(testCheck)
+    } else if (greenHit) {
+      testCheck = {
+        status: 'passed',
+        reason: greenCacheNotice(greenHit, 'verify-test'),
+        command: '(green-cache 同指纹复用)',
+        exitCode: 0, durationMs: 0, outputTail: null,
+        resultPath: null, strategy: null, cached: true,
+      }
+      console.log(`\n♻️ Verify 测试对账：green-cache 同指纹复用（HEAD+代码脏面+local.yaml 全等，近期真跑绿——P2 账本未命中时的第二层免重跑；SILLYSPEC_GREEN_CACHE_OFF=1 可关闭）`)
+      printVerifyTestCheck(testCheck)
     } else {
       // 测试实测是同步 execSync，长套件可跑 2~10min 且中途无输出——先预告避免 agent 误判卡死
       console.log(`\n⏳ Verify 测试对账：CLI 亲自执行 local.yaml 的 commands.test（同步，耗时可能较长，请等待…）`)
@@ -1039,6 +1063,12 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
         }
       } catch { /* 记账异常不影响门禁（下次仍真跑） */ }
       }
+      // green-cache 记绿（R8 接线，与 P2 同口径：只有通过结果入缓存——失败永不缓存）
+      if (testCheck && testCheck.status === 'passed' && gateFingerprint) {
+        try {
+          storeGreenCache({ runtimeRoot: resolveRuntimeRoot(platformOpts, specBase), scope: changeName, kind: 'test', fingerprint: gateFingerprint, result: { status: 'passed', exitCode: 0 } })
+        } catch { /* 写缓存失败不影响门禁（下次真跑） */ }
+      }
     }
     // ── trace 晋升（2026-09-24-fr-test-bindings task-04，fr-test-binding §3.2/D-003@v1）：
     //    verify 门通过点按矩阵判定列晋升 candidate→active（covered/covered-service→active+
@@ -1112,8 +1142,16 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     const { runVerifyLintCheck, printVerifyLintCheck } = await import('../verify-postcheck.js')
     // P0-1 指纹复用：noAI 质量扫描记录同指纹时 lint 一并复用（lint tally 只记真实执行次数）
     let lintCheck = (reusableScan && reusableScan.lintResult) || null
+    let lintGreenHit = null
+    try {
+      lintGreenHit = gateFingerprint ? lookupGreenCache({ runtimeRoot: resolveRuntimeRoot(platformOpts, specBase), scope: changeName, kind: 'lint', fingerprint: gateFingerprint }) : null
+    } catch { /* fail-open：缓存链异常回退真跑 */ }
     if (lintCheck) {
       console.log(`\n♻️ Verify lint 对账：复用 noAI 质量扫描步的实测结果（代码指纹匹配，免重跑）`)
+    } else if (lintGreenHit) {
+      // R8 green-cache 第二层（同 test 段口径）：近期同指纹真跑绿免重跑；tally 只记真实执行
+      lintCheck = { status: 'passed', exitCode: 0, durationMs: 0, failureFiles: [], cached: true, reason: greenCacheNotice(lintGreenHit, 'verify-lint') }
+      console.log(`\n♻️ Verify lint 对账：green-cache 同指纹复用（HEAD+代码脏面+local.yaml 全等，近期真跑绿免重跑；SILLYSPEC_GREEN_CACHE_OFF=1 可关闭）`)
     } else {
       lintCheck = runVerifyLintCheck({ cwd: gateCwd, specBase: gateSpecBase, timeoutMs: verifyGateSnap ? 5 * 60 * 1000 : undefined })
     // 快照 lint 超时回退主仓（2026-09-12 dogfood 两连实证：junction I/O 病态慢，3min/5min 均被
@@ -1123,6 +1161,12 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
         console.warn('⚠️ 快照 lint 超时（node_modules junction I/O 慢）→ 主仓复跑 lint（并行噪声可能混入——失败先做归属鉴定）')
         lintCheck = runVerifyLintCheck({ cwd, specBase })
       }
+      // green-cache 记绿（R8 接线：passed 才缓存——失败永不缓存；快照超时回退的主仓复跑同记）
+      if (lintCheck.status === 'passed' && gateFingerprint) {
+        try {
+          storeGreenCache({ runtimeRoot: resolveRuntimeRoot(platformOpts, specBase), scope: changeName, kind: 'lint', fingerprint: gateFingerprint, result: { status: 'passed', exitCode: 0 } })
+        } catch { /* 写缓存失败不影响门禁（下次真跑） */ }
+      }
       if (lintCheck.status !== 'skipped') {
         console.log(`\n⏳ Verify lint 对账：CLI 亲自执行 local.yaml 的 commands.lint…`)
       }
@@ -1527,9 +1571,20 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           console.warn(`\n⚠️ module-impact.md「更新结果」表有 ${execPendingRows.length} 个 pending/待办项（文档同步债）——verify 阶段会硬拦：`)
           for (const row of execPendingRows) console.warn(`   - ${row}`)
           console.warn('   建议 execute 收尾就完成模块文档同步并回填 done/skipped（说明原因），别把债拖到 verify 末尾。')
+          console.warn('   批量跳过不同步行可一键回填：sillyspec module-impact --change <变更名> --fill-skipped --reason "<真实原因>"')
         }
       }
     } catch { /* 提示失败不阻断 execute */ }
+    // UI 视觉证据前置 advisory（2026-10-07-flow-friction-batch3 task-05）：证据应执行期随手落盘、
+    // verify 收口才执法（postmortem 实证发现时机太晚）。warn 级不阻断 execute；fail-soft。
+    try {
+      const uiChangeDir = resolveChangeDir(cwd, progress, platformOpts?.specRoot)
+      if (uiChangeDir) {
+        const { uiEvidenceExecuteAdvisory } = await import('../ui-visual.js')
+        const uiAdv = uiEvidenceExecuteAdvisory({ changeDir: uiChangeDir, specBase })
+        if (uiAdv) console.warn(`\n⚠️ ${uiAdv}`)
+      }
+    } catch { /* advisory 失败不阻断 execute */ }
   }
 
   // ── Execute Task Review Gate 已退役（2026-09-26-task-review-retire）──
@@ -1697,10 +1752,11 @@ export function validateFileLocations(cwd, stageName, progress, changeName, spec
   if (!existsSync(changeDir)) return
 
   // 每个阶段完成后预期存在的文件
-  // brainstorm:scale=small(小变更)只必产 design.md;large/未标 scale → 四件套全。
-  // 与 validateBrainstormOutputs 的 BRAINSTORM_RULES condition(scale≠small)同源,避免对合法 small 变更
-  // 误报"⬜ proposal/requirements/tasks 未找到"(本检查仅 advisory 打印不 gate,但误导输出仍要消除)。
-  const brainstormExpected = readDesignScale(specBase, effectiveChange) === 'small'
+  // brainstorm:scale=small/未标(收编轻量道,2026-09-29-brainstorm-exit-thin-default 起未标默认 small)只必产
+  // design.md;显式 large → 四件套全。避免对合法收编变更误报"⬜ proposal/requirements/tasks 未找到"
+  // (本检查仅 advisory 打印不 gate,但误导输出仍要消除)。注:stage-contract 硬门条件(ne:small)在并行
+  // 变更在途面,未标仍轻推补值——忘写 scale 的 agent 被门推向显式落值,v1 可接受。
+  const brainstormExpected = readDesignScale(specBase, effectiveChange) !== 'large'
     ? ['design.md']
     : ['design.md', 'proposal.md', 'requirements.md', 'tasks.md']
   const expectedFiles = {

package/src/run/prompt.js

@@ -19,12 +19,45 @@
  *   - loadModuleContextIndex/buildModuleContextInjection 内 require('fs'/'path') 改顶部静态 import
  */
 import { basename, dirname, join } from 'node:path'
-import { existsSync, readFileSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, mkdirSync, readdirSync, writeFileSync, rmSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import jsYaml from 'js-yaml'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { stageRegistry } from '../stages/index.js'
 import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, parsePorcelainPath, WAIT_MARKER_RE, QUICK_SID_RE, triggerStepStartSync } from './shared.js'
+
+/**
+ * step-guide 旧指纹清理（2026-10-06-verify-docs-prefill task-05）：guide 文件名 =
+ * `${stage}-step${idx}-${指纹8位}.md` 跨变更共享、旧指纹永不清理——同步骤多版本共存会让自行
+ * ls/glob 目录的 agent 读到旧版本指引。白名单 = keepAbsPaths（本次新写的 guide）∪ 仍被任一
+ * 变更 state 文件（`${stage}-step${idx}-*.json`）引用的 guidePath；白名单外的同前缀文件删除。
+ * 纯目录操作 fail-soft：目录缺失/坏 state 均不抛，返回清理计数。
+ * @param {{ guideRoot: string, stateRoot: string, stageName: string, stepIndex: number, keepAbsPaths: string[] }} opts
+ * @returns {number} 实际删除的文件数
+ */
+export function pruneStaleStepGuides({ guideRoot, stateRoot, stageName, stepIndex, keepAbsPaths = [] }) {
+  const prefix = `${stageName}-step${stepIndex}-`
+  const keep = new Set((keepAbsPaths || []).map(String))
+  try {
+    for (const sf of readdirSync(stateRoot)) {
+      if (!sf.startsWith(prefix)) continue
+      try {
+        const st = JSON.parse(readFileSync(join(stateRoot, sf), 'utf8'))
+        if (st && typeof st.guidePath === 'string') keep.add(st.guidePath)
+      } catch { /* 坏 state 不参与白名单（其指向的文件按无引用清理——复入时 existsSync 回退全量重印，fail-soft） */ }
+    }
+  } catch { /* stateRoot 缺失 → 空白名单 */ }
+  let pruned = 0
+  try {
+    for (const gf of readdirSync(guideRoot)) {
+      if (!gf.startsWith(prefix) || !gf.endsWith('.md')) continue
+      const abs = join(guideRoot, gf)
+      if (keep.has(abs)) continue
+      try { rmSync(abs, { force: true }); pruned++ } catch { /* 单文件删除失败继续 */ }
+    }
+  } catch { /* guideRoot 缺失 → 0 */ }
+  return pruned
+}
 import { materializeStageTemplates } from '../stage-templates.js'
 import { renderSemanticGuardBlock, readSemanticGuardEnabled } from '../semantic-guard.js'
 
@@ -33,7 +66,7 @@ import { renderSemanticGuardBlock, readSemanticGuardEnabled } from '../semantic-
 // （漏登会令指纹误变——退化后果只是多一次全量重印，不产生错误指引；多登同理只多印）。
 const VOLATILE_PLACEHOLDER_RES = [
   /<now-datetime>/g, /<now-timestamp>/g, /<now-date>/g, /<now-iso-datetime>/g, /<git-head-short>/g, /<quicklog-id>/g,
-  /{SCAN_STALENESS}/g, /{SCAN_FACTS}/g, /{QUICK_CONTEXT_DIGEST}/g, /{DECISION_HITS}/g,
+  /{SCAN_STALENESS}/g, /{SCAN_FACTS}/g, /{QUICK_CONTEXT_DIGEST}/g, /{DECISION_HITS}/g, /{UI_VISUAL_GUIDANCE}/g,
   /{KNOWLEDGE_HIT_REPORT}/g, /{DOCS_DEBT}/g, /{MODULE_RESOLVE_TABLE}/g, /{REVIEW_MATERIALS}/g,
   /{EXECUTE_RUN_ID}/g, /{STAGE_REVIEW_RUN_ID}/g, /{PROGRESS_SNAPSHOT}/g, /{TASK_COMPLETION_REPORT}/g,
   /{WORKTREE_META}/g, /{WORKTREE_BASELINE_INFO}/g, /{TASKS_CHECKBOX}/g, /{GIT_DIRTY}/g,
@@ -392,6 +425,88 @@ export function buildQuickSemanticGuardInjection({ specBase, cwd, changeName } =
 export const KNOWLEDGE_INJECT_MAX_FILES = 3
 export const KNOWLEDGE_INJECT_MAX_LINES = 40
 
+// {FR_INDEX_DIGEST} 注入截断上限（2026-09-29-rot-retire-inject-cap）：brainstorm step8 写作期
+// 现行 FR 清单 top-N + 指针行——与 flow start 注入口径（flow.js slice(0,8)）同数。大域/unmapped
+// 整池倾倒实证：digest 源遥测 11/11 次 count=723@unmapped。
+export const FR_INDEX_DIGEST_MAX_ENTRIES = 8
+
+/**
+ * {FR_INDEX_DIGEST} 段构建（brainstorm step8 写作期现行 FR 清单）——2026-09-29-rot-retire-inject-cap
+ * 从注入装配内联块抽出为可单测函数，并修两缺口：① 滤 unmapped（停车场非行为域，原不滤致整池倾倒
+ * ——遥测 11/11 次 count=723@unmapped 实证）；② top-8 截断 + 指针行（原无上限，与 flow start /
+ * module-inject 两个注入口径对齐）。截断先截条目再追加尾部承接指引 blockquote（naive slice 会把
+ * 指引一起截掉）。遥测 count 保持全量口径（L3 指标①），另加 rendered/truncated/unmappedFiltered。
+ * @param {object} opts
+ * @param {string} opts.frSpecBase - spec 根（.sillyspec）
+ * @param {string} opts.changeName - 变更名（域路由读其 design.md 交付清单；遥测 change 字段）
+ * @returns {Promise<{text: string, telemetry: object}>} text=替换值；telemetry=fr-inject 事件负载（异常时 null）
+ */
+export async function buildFrIndexDigestSection({ frSpecBase, changeName }) {
+  try {
+    const { discoverModuleIndex } = await import('../decision-distill.js')
+    const { resolveTouchedDomains, readActiveFrDigest, rankFrDigestForInjection, deliverableFilesFromDesignText } = await import('../fr-index.js')
+    const frChangeDir = join(frSpecBase, 'changes', String(changeName || ''))
+    const knowledgeRoot = join(frSpecBase, 'knowledge')
+    const domainsAll = resolveTouchedDomains(frChangeDir, discoverModuleIndex(knowledgeRoot))
+    // unmapped 是未归类停车场非行为域，不进写作 prompt——与 flowKnowledgeDigest / frDupGateFlow 同口径
+    const domains = domainsAll.filter((d) => d !== 'unmapped')
+    const entries = domains.length > 0 ? readActiveFrDigest(knowledgeRoot, domains) : []
+    // 注入排序（2026-10-03-fr-inject-relevance-rank）：TierA 覆盖命中（🎯）置前、TierB 日期新→旧
+    // ——取代文件序前 N（域增长后注入面恒为最老 N 条，新立规格永不可见）。触碰文件面与域路由
+    // 同源（design 交付清单）；fail-soft：清单缺席=纯 TierB。
+    let tierAIds = new Set()
+    let ranked = entries
+    if (entries.length > 0) {
+      try {
+        const touched = deliverableFilesFromDesignText(readFileSync(join(frChangeDir, 'design.md'), 'utf8'))
+        if (touched.length > 0) {
+          ({ ranked, tierAIds } = rankFrDigestForInjection({ archiveRoot: join(frSpecBase, 'changes', 'archive'), frs: entries, changed: touched }))
+        }
+      } catch { /* design 缺席/不可读=无触碰面，保持文件序 */ }
+    }
+    // 骨架门（2026-10-03-fr-skeleton-gate）：纯骨架条目不占注入席位（TierA 命中例外）；指针行
+    // 披露骨架数。查重/rot/绑定面不滤。
+    const injectable = ranked.filter((e) => !e.skeleton || tierAIds.has(e.id))
+    const skeletonHidden = entries.filter((e) => e.skeleton && !tierAIds.has(e.id)).length
+    const truncated = Math.max(0, injectable.length - FR_INDEX_DIGEST_MAX_ENTRIES)
+    let text
+    if (domains.length === 0) {
+      // 零路由命中两态：有交付清单但零命中（unmapped 兜底被滤）→ 指停车场；无清单 → 通用空态。
+      // 注意 unmapped 是 resolveTouchedDomains 的零命中兜底，真域命中时不与之并存。
+      let hasDeliverableRows = false
+      try {
+        hasDeliverableRows = deliverableFilesFromDesignText(
+          readFileSync(join(frChangeDir, 'design.md'), 'utf8')).length > 0
+      } catch { /* design 缺席/不可读=无清单态 */ }
+      text = domainsAll.length > 0 && hasDeliverableRows
+        ? '（触达域仅剩 unmapped（未归类停车场，不注入）——存量条目需要时自查 knowledge/fr/unmapped.md；本变更交付文件建议登记进模块卡 paths，让后续变更路由到真域）'
+        : '（触达域暂无 active FR 索引条目——本变更大概率是这些域的首批需求，照常写作）'
+    } else if (entries.length === 0) {
+      text = '（触达域暂无 active FR 索引条目——本变更大概率是这些域的首批需求，照常写作）'
+    } else {
+      const renderedEntries = injectable.slice(0, FR_INDEX_DIGEST_MAX_ENTRIES)
+      const hiddenCount = entries.length - renderedEntries.length
+      const lines = renderedEntries.map((e) => `- ${e.id}${tierAIds.has(e.id) ? ' 🎯' : ''} ${e.title}（来源 ${e.change}${e.scenarios.length ? '；场景：' + e.scenarios.slice(0, 3).join('，') : ''}${(e.decisions || []).length ? '；依据：' + e.decisions.slice(0, 3).join('、') : ''}）`)
+      if (hiddenCount > 0) lines.push(`（+${hiddenCount} 条见 knowledge/fr/ 对应域文件——未尽条目按需 Read${skeletonHidden > 0 ? `；纯骨架 ${skeletonHidden} 条不注入` : ''}）`)
+      lines.push('')
+      lines.push('> 域解析自本变更 design.md 文件清单（漏域先核对清单）。改写/取代已有行为 → 对应 FR 块加承接行；新行为 → 新 FR 块。superseded 条目默认不列（历史回溯自行读 knowledge/fr/）。依据决策（L2）= 当年取舍锚——翻案须先读 knowledge/decisions/<域>.md 的否决理由，满足复潮条件走 D-xxx@vN+1，不得静默改行为。承接行可带退役理由：`承接: FR-<域>-NNN（退役理由：一句话）`——归档时写进被取代条目（理由内禁逗号）；条目正文是截断摘要，全文锚（全文：<归档路径>#FR-NN）由 CLI 自动落。' + (tierAIds.size > 0 ? '🎯=与本次触碰文件有覆盖交集（TierA 优先注入）。' : ''))
+      text = lines.join('\n')
+    }
+    return {
+      text,
+      telemetry: {
+        type: 'fr-inject', change: changeName, domains, count: entries.length, source: 'digest',
+        rendered: Math.min(injectable.length, FR_INDEX_DIGEST_MAX_ENTRIES), truncated,
+        unmappedFiltered: domainsAll.length !== domains.length,
+        tierA: tierAIds.size,
+        skeletonHidden,
+      },
+    }
+  } catch (e) {
+    return { text: `（FR 索引注入失败：${e && e.message ? e.message : e}——可自行读 {SPEC_ROOT}/knowledge/fr/）`, telemetry: null }
+  }
+}
+
 /** top-N 选取：按 entries 出现序（INDEX 行序）取前 N 个不同 file（matchKnowledge 布尔 filter
  *  无相关度排序，X-009——出现序即唯一稳定序），每 file 取首个命中 entry 作代表。 */
 function pickTopKnowledgeEntries(entries, maxFiles) {
@@ -1215,32 +1330,16 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
 
   // ①c {FR_INDEX_DIGEST}（2026-09-18-fr-index-l1 L1，D-004）：brainstorm step8 的触达域现行 FR 注入
   // ——写作期防重复 FR 的确定性清单（superseded 默认藏）；无触达域索引/索引空 → 段消隐。
-  // fr-inject 遥测（L3 证据发生器指标①）fail-soft；token 本体在 stages/brainstorm.js step8 模板。
+  // 段构建与收敛口径（滤 unmapped + top-8）在 buildFrIndexDigestSection（可单测）；遥测 fail-soft。
   if (stageName === 'brainstorm' && promptText.includes('{FR_INDEX_DIGEST}')) {
-    try {
-      const frSpecBase = resolvePromptSpecBase(platformOpts, cwd)
-      const { discoverModuleIndex } = await import('../decision-distill.js')
-      const { resolveTouchedDomains, readActiveFrDigest } = await import('../fr-index.js')
-      const frChangeDir = join(frSpecBase, 'changes', String(changeName || ''))
-      const knowledgeRoot = join(frSpecBase, 'knowledge')
-      const domains = resolveTouchedDomains(frChangeDir, discoverModuleIndex(knowledgeRoot))
-      const entries = readActiveFrDigest(knowledgeRoot, domains)
-      if (entries.length === 0) {
-        substitute(/\{FR_INDEX_DIGEST\}/g, '（触达域暂无 active FR 索引条目——本变更大概率是这些域的首批需求，照常写作）')
-      } else {
-        const lines = entries.map((e) => `- ${e.id} ${e.title}（来源 ${e.change}${e.scenarios.length ? '；场景：' + e.scenarios.slice(0, 3).join('，') : ''}${(e.decisions || []).length ? '；依据：' + e.decisions.slice(0, 3).join('、') : ''}）${e.needsReview ? ` ⚠️ 待复核（${e.needsReview}）——该 FR 覆盖的代码近期被 quick 触达，行为可能已变；本变更若触及同域先核对现状再决定承接/新写` : ''}`)
-        lines.push('')
-        lines.push('> 域解析自本变更 design.md 文件清单（漏域先核对清单）。改写/取代已有行为 → 对应 FR 块加承接行；新行为 → 新 FR 块。superseded 条目默认不列（历史回溯自行读 knowledge/fr/）。依据决策（L2）= 当年取舍锚——翻案须先读 knowledge/decisions/<域>.md 的否决理由，满足复潮条件走 D-xxx@vN+1，不得静默改行为。承接行可带退役理由：`承接: FR-<域>-NNN（退役理由：一句话）`——归档时写进被取代条目（理由内禁逗号）；条目正文是截断摘要，全文锚（全文：<归档路径>#FR-NN）由 CLI 自动落。')
-        substitute(/\{FR_INDEX_DIGEST\}/g, lines.join('\n'))
-      }
+    const frSpecBase = resolvePromptSpecBase(platformOpts, cwd)
+    const sec = await buildFrIndexDigestSection({ frSpecBase, changeName })
+    substitute(/\{FR_INDEX_DIGEST\}/g, sec.text)
+    if (sec.telemetry) {
       try {
         const { appendKnowledgeHit } = await import('../knowledge-hits.js')
-        appendKnowledgeHit(join(frSpecBase, '.runtime'), {
-          type: 'fr-inject', change: changeName, domains, count: entries.length, source: 'digest',
-        })
+        appendKnowledgeHit(join(frSpecBase, '.runtime'), sec.telemetry)
       } catch { /* 遥测 fail-soft */ }
-    } catch (e) {
-      substitute(/\{FR_INDEX_DIGEST\}/g, `（FR 索引注入失败：${e && e.message ? e.message : e}——可自行读 {SPEC_ROOT}/knowledge/fr/）`)
     }
   }
 
@@ -1290,21 +1389,24 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   // 全降级不抛（异常 → 单行说明）。
   if (stageName === 'brainstorm' && promptText.includes('{DECISION_HITS}')) {
     try {
-      const { matchKnowledge } = await import('../knowledge-match.js')
+      const { matchKnowledgeHybrid } = await import('../knowledge-vector.js')
+      const { deathPathNote } = await import('../knowledge-match.js')
       const decSpecBase = resolvePromptSpecBase(platformOpts, cwd)
       const decKnowledgeDir = join(decSpecBase, 'knowledge')
       // taskContext：changeName（brainstorm Step2 时 tasks.md 尚未生成，变更名是唯一稳定任务
       // 语料；与 execute 分支的 changeName 基底同口径）
-      const decResult = matchKnowledge(decKnowledgeDir, changeName || '')
-      const rejectedHits = (decResult.decisionHits || []).filter(h => h.status === 'rejected')
+      const decResult = await matchKnowledgeHybrid(decKnowledgeDir, changeName || '', { cwd })
+      // 防复潮面 = 死路注记 ∪ 有主题重叠的 rejected（与 flow 注入段/knowledge-gate 同口径；
+      // score 零 rejected 不弹——2026-09-28-knowledge-gate-denoise）
+      const rejectedHits = (decResult.decisionHits || []).filter(h => h.deathPath || (h.status === 'rejected' && h.score > 0))
       let decInjected = ''
       if (rejectedHits.length > 0) {
         const lines = [
-          '⚠️ 否决决策提示（历史已否决，防复潮）——下列决策此前已被否决。看到否决理由后，除非复潮条件明确满足，不要在本次方案中重新提出；若认为复潮条件已满足，须在本变更 decisions.md 记录新版本条目（D-xxx@vN+1）说明依据：'
+          '⚠️ 否决决策/死路注记提示（历史已否决或已记死路，防复潮）——下列决策此前已被否决或已记死路。看到理由后，除非复潮条件明确满足，不要在本次方案中重新提出；若认为复潮条件已满足，须在本变更 decisions.md 记录新版本条目（D-xxx@vN+1）说明依据：'
         ]
-        for (const h of rejectedHits) {
-          lines.push(`- ${h.id} ${h.title}（${h.file}）`)
-          lines.push(`  - 否决理由：${h.reason || '（未记录）'}`)
+        for (const h of rejectedHits.slice(0, 5)) {
+          lines.push(`- ${h.id} ${h.title}（${h.file}）${h.status === 'rejected' ? '' : ' ⚰️死路注记'}`)
+          lines.push(`  - ${h.status === 'rejected' ? '否决理由' : '死路'}：${h.status === 'rejected' ? (h.reason || '（未记录）') : deathPathNote(h.reason)}`)
           lines.push(`  - 复潮条件：${h.revisitWhen || '（未记录）'}`)
         }
         decInjected = '\n\n' + lines.join('\n')
@@ -1319,6 +1421,26 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     }
   }
 
+  // {UI_VISUAL_GUIDANCE} → UI 触达检测命中时注入「UI 变更执行须知」（2026-09-28-guidance-principles：
+  // 原型诞生地在头脑风暴的方案对比步——frontend-apple-style 会话实证手绘定稿原型因缺开工引导；
+  // 与 flow start 注入同源同文案，检测语料=变更目录 proposal 与 requirements + 变更名）。无命中
+  // 替换空串零输出；fail-soft 异常单行说明，不留残留占位符。
+  if (stageName === 'brainstorm' && promptText.includes('{UI_VISUAL_GUIDANCE}')) {
+    try {
+      const { detectUiTouch, buildUiGuidanceLines } = await import('../ui-visual.js')
+      const uiSpecBase = resolvePromptSpecBase(platformOpts, cwd)
+      let corpus = changeName || ''
+      for (const name of ['proposal.md', 'requirements.md']) {
+        try {
+          corpus += '\n' + readFileSync(join(uiSpecBase, 'changes', changeName, name), 'utf8')
+        } catch { /* 缺席跳过 */ }
+      }
+      substitute(/\{UI_VISUAL_GUIDANCE\}/g, detectUiTouch(corpus) ? '\n' + buildUiGuidanceLines().join('\n') + '\n' : '')
+    } catch (e) {
+      substitute(/\{UI_VISUAL_GUIDANCE\}/g, `[ui-guidance] UI 须知注入异常（${e.message}），跳过`)
+    }
+  }
+
   // Knowledge hit report: execute 阶段注入匹配结果
   // 2026-09-14-knowledge-loop-close task-04（FR-04，X-004 升级既有机制）：命中清单报告 → 命中
   // 正文注入——命中时占位符替换为「📚 命中知识」段（top-3 不同 file + 首 40 行截断，段头保留
@@ -2001,6 +2123,12 @@ ${maskVolatileForGuide(guideTemplate)}
 `, 'utf8')
       mkdirSync(stateRoot, { recursive: true })
       writeFileSync(stateFile, JSON.stringify({ fingerprint, guidePath: guideFile, changeName: changeName || null, stage: stageName, stepIndex, at: new Date().toISOString() }, null, 1) + '\n', 'utf8')
+      // 旧指纹清理（2026-10-06-verify-docs-prefill task-05）：同步骤旧指纹 guide 永久共存会让
+      // 自行 ls/glob 目录的 agent 读到旧版本指引（厚流程 step5/step6 错位疑云）。白名单 =
+      // 新写的 guide ∪ 仍被任一变更 state 引用的 guide（他变更复入短输出依赖 existsSync 回退，
+      // 被引用文件误删只退化全量重印但无谓）；清理 fail-soft 且静默——步骤输出是字节中立面
+      // （knowledge-inject A/B 对比、guidance-output-neutrality），运维日志不进 prompt 流。
+      try { pruneStaleStepGuides({ guideRoot, stateRoot, stageName, stepIndex, keepAbsPaths: [guideFile] }) } catch { /* 清理 best-effort */ }
       }
     } catch { /* guide/state 落盘 best-effort：失败仅退化回全量重印，不阻断步骤输出 */ }
   }

package/src/run/quick-audit.js

@@ -12,7 +12,7 @@
  *     启动路径（实测冷加载 100-150ms），而 checkbox 仅"≥2 活跃变更 + TTY"分支用到
  */
 import { join, dirname } from 'node:path'
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, cpSync, rmSync, renameSync } from 'node:fs'
 import { parsePorcelainPath, safeGit } from './shared.js'
 import { collectRecentForeignDelivery, detectAssertionRewrites, readSemanticGuardEnabled } from '../semantic-guard.js'
 
@@ -555,6 +555,14 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
     } catch { /* 快照链路异常 → 主仓现行为 */ }
     }
   }
+  // failed/test/lint 提升到 try 外（坑 flowdone-lint-fail-no-output 排障顺带发现 + 收编评审 P1）：
+  // 此前三者均声明在 try 块内（块级作用域），finally 的快照回拷读 failed.length、resultPath
+  // 重映射读 [test, lint] 各抛 ReferenceError 被空 catch 吞掉——P6b 回拷 + 重映射自 2026-09-28
+  // 落地即死代码（快照 FAIL 时结果文件随临时目录蒸发、FAIL 三件套的结果文件路径恒死链）。
+  // 收编首版只提升了 failed（重映射引用的 test/lint 仍死）——评审 P1 抓出后三变量齐提升。
+  const failed = []
+  let test = null
+  let lint = null
   try {
     // ── P2 三键账本（D-001@v1，batch3 task-01）：同码同环境免重跑（fail-closed——无记录/
     //    键不等/分量不可得=真跑，行为不变）。quick 会话名 per-change 天然隔离账本文件。──
@@ -577,7 +585,7 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
       // 「零信息误判」主因）。
       console.log(`⏳ 开始 test+lint 实测${snapshot ? '（隔离快照内）' : ''}——大仓全量可达 15-20 分钟，期间无输出属正常；后台跑 + 长容忍（≥20 分钟），勿按超时杀进程（杀掉不丢进度，但每轮重建沙箱重跑实测耗时成倍）。`)
     }
-    let test = testLedgerReuse
+    test = testLedgerReuse
       ? { status: 'passed', reason: `♻️ P2 三键账本复用（代码×测试面×环境全等；实测于 ${testLedgerReuse.result.ranAt}）`, command: `${testLedgerReuse.runPlan?.[0]?.runner || 'npm test'} (ledger-reuse)`, exitCode: 0, durationMs: 0, outputTail: null }
       // restrictFiles = 本会话声明文件（坑 quick-gate-并行全流程变更脏文件误伤）：模块选择
       // 与 deps(auto) 只取「实际变更 ∩ 本会话声明」，并行全流程变更 WIP 不再挡死本会话
@@ -603,7 +611,7 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
         })
       } catch { /* 记账异常不影响门禁（下次仍真跑） */ }
     }
-    let lint = runVerifyLintCheck({ cwd: gateCwd, specBase: gateSpecBase, timeoutMs: snapshot ? 5 * 60 * 1000 : undefined })
+    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：主仓复跑保硬门，
     // 并行噪声混入时失败输出带归属鉴定提示）
@@ -611,7 +619,6 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
       console.warn('⚠️ 快照 lint 超时（node_modules junction I/O 慢）→ 主仓复跑 lint（并行噪声可能混入——失败先做归属鉴定）')
       lint = runVerifyLintCheck({ cwd, specBase })
     }
-    const failed = []
     // 哨兵断言（2026-09-25-sentinel-wiring，与 flow done 同判）：tasks.md 全勾但零完成
     // 证据（区间提交消息标题与正文均无 task-NN token 且无对应 review.json）→ 计入 failed 拒收。
     // 证据面=整条提交消息（2026-09-25-thin-done-gate-calibration 坑2，同 flow 侧 %B%x1e 口径）。
@@ -621,8 +628,11 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
       const tasksDir = changeName ? join(specBase, 'changes', changeName, 'tasks.md') : null
       if (tasksDir && existsSync(tasksDir)) {
         const _log = safeGit ? safeGit(cwd, ['log', '--format=%B%x1e', 'HEAD~10..HEAD']) : null
-        const commitMsgs = String((_log && !_log.error) ? _log.value : '') || ''
-        if (commitMsgs) {
+        const _logOk = !!(_log && !_log.error)
+        const commitMsgs = _logOk ? String(_log.value) || '' : ''
+        if (_logOk) { // 空串（区间零提交）照跑——零提交不豁免，哨兵从严
+          // 证据判据统一（2026-10-07-thin-tasks-v3）：已勾任务一律按 per-task 证据判（提交 token /
+          // review.json），镜像豁免与基线读取退役（quick 道本就无基线快照面）。
           const sent = detectFakeCheckCompletion({ changeDir: dirname(tasksDir), tasksMd: readFileSync(tasksDir, 'utf8'), commits: commitMsgs.split('\x1e').map((x) => x.trim()).filter(Boolean) })
           if (sent.status === 'fake') {
             console.error(`\n🚫 哨兵断言拒收：tasks.md 全勾（${sent.checked}/${sent.claimTotal}）但 ${sent.missing.length} 个任务零完成证据（区间提交标题与正文均无 token）：${sent.missing.join('、')}`)
@@ -678,6 +688,16 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
         printSnapshotFailureHint({ snapshotRoot: snapshot.snapshotRoot, changeFileCount: snapshot.overlaid, sourceRoot: snapshot.sourceRoot || null }, { offEnv: 'SILLYSPEC_QUICK_GATE_SNAPSHOT_OFF' })
       } catch { /* 提示失败不影响门禁语义 */ }
     }
+    // lint 结果持久化（坑 flowdone-lint-fail-no-output，2026-10-03）：runVerifyLintCheck 全程
+    // 静默、tally 只记一句退出码——lint 结果对象并入 test 的 test-result.json（modules 并列
+    // 一节）；test 无结果文件（skipped）而 lint 实跑时独立落盘（kind: 'lint'）。快照模式下
+    // 并入写在快照路径、随 P6b FAIL 回拷回主仓（失败恰是排障需要它的时点）。
+    try {
+      if (lint && (lint.status === 'passed' || lint.status === 'failed')) {
+        const { persistLintResult } = await import('../verify-postcheck.js')
+        lint.resultPath = persistLintResult({ specBase, changeName: typeof changeName === 'string' ? changeName : null, testResultPath: test && test.resultPath, lint }) || lint.resultPath || null
+      }
+    } catch { /* 持久化 best-effort，不影响门禁语义 */ }
     return {
       action: failed.length > 0 ? 'fail' : 'pass',
       failed,
@@ -690,8 +710,47 @@ export async function runQuickTestLintGate({ cwd, specBase, changedFiles = [], d
       semanticGuard,
     }
   } finally {
-    if (snapshot) { try { snapshot.cleanup() } catch { /* 清理失败不连坐门禁结论 */ } }
+    if (snapshot) {
+      // 快照证据回拷（2026-09-28-split-guard-and-gate-report，P6b）：快照内 verify-runs 结果
+      // 落快照临时目录、收尾即清——测试/lint FAIL 时先回拷主仓 .runtime 再清理，排障证据不蒸发。
+      try {
+        if (failed.length > 0) {
+          const copied = copySnapshotVerifyRuns(gateSpecBase, specBase)
+          // 结果路径重映射（评审 P1 清偿）：快照内写下的 resultPath 指向快照临时目录——清理后
+          // existsSync 恒 false，flow done 的 FAIL 三件套会静默失效。回拷后把 test/lint 的
+          // resultPath 改写为主仓路径（对象即返回值，finally 在 return 落地前变异生效）。
+          for (const r of [test, lint]) {
+            if (r && typeof r.resultPath === 'string' && r.resultPath.startsWith(gateSpecBase)) {
+              r.resultPath = specBase + r.resultPath.slice(gateSpecBase.length)
+            }
+          }
+        }
+      } catch { /* 回拷 best-effort，不连坐门禁结论 */ }
+      try { snapshot.cleanup() } catch { /* 清理失败不连坐门禁结论 */ }
+    }
+  }
+}
+
+/** 快照 .runtime/verify-runs 全量回拷主仓（同名目录不覆盖——主仓自己的结果优先；临时名+原子改名，崩溃残端可续拷）。 */
+function copySnapshotVerifyRuns(fromSpecBase, toSpecBase) {
+  const fromDir = join(fromSpecBase, '.runtime', 'verify-runs')
+  const toDir = join(toSpecBase, '.runtime', 'verify-runs')
+  if (!existsSync(fromDir)) return 0
+  let copied = 0
+  for (const d of readdirSync(fromDir)) {
+    const src = join(fromDir, d)
+    const dst = join(toDir, d)
+    if (existsSync(dst)) continue
+    // 评审 P3 清偿：cpSync 非原子——中途失败留下残缺 dst 且同名跳过阻断续拷自愈。改为
+    // 临时名整拷 + renameSync 原子落位；崩溃只留 .part 残端，重跑时先清再拷（可续拷）。
+    const part = dst + '.part'
+    rmSync(part, { recursive: true, force: true })
+    cpSync(src, part, { recursive: true })
+    renameSync(part, dst)
+    copied++
   }
+  if (copied > 0) console.warn(`📎 快照实测证据已回拷主仓：${copied} 个 verify-runs 目录（排障读主仓 .runtime 即可）`)
+  return copied
 }
 
 /**

package/src/run/shared.js

@@ -81,7 +81,10 @@ export function assertSafeChangeName(name, label = '变更名') {
 // 历史 DB/目录已存在的旧变更不追诉（归档里 auto-flow-optimization 等 10 个无前缀名照常可读）。
 // 豁免：quick-<8hex> 会话 key 与 default 兜底 key 是系统生成名，非 agent 自拟描述名。
 // 日期只校验形状（月 01-12 日 01-31），不校验「当天」——跨天续跑/次日重命名不应被拦。
-const DATED_CHANGE_NAME_RE = /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])-[a-zA-Z0-9][\w.\-]*$/
+// slug 首字符放宽含 CJK（一-鿿，与 flow 族 validateChangeName 同字符集）：flow start 2026-09-28
+// 起复用本校验器，中文名（平台键 2026-09-25-中文名-a1b2c3 形态）是 flow 族既有测试特性；
+// run 族不受影响——其上游 assertSafeChangeName 仅放行 ASCII [\w.\-]，中文在到达本门之前已被拦。
+const DATED_CHANGE_NAME_RE = /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])-[a-zA-Z0-9一-鿿][\w.\-一-鿿]*$/
 export function assertDatedChangeName(name, label = '变更名') {
   if (name == null) return
   const s = String(name)
@@ -1872,16 +1875,8 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
               type: 'fr-rot-suspect', change: guard.changeName || null,
               domains: [...touchedDomains], count: frs.length, source: 'quick-done',
             })
-            // 地图诚实升级（2026-09-20-quick-asset-tail FR-02/D-003）：遥测之外给条目打
-            // 待复核标记——下一次 brainstorm 注入行带 ⚠️，承接翻链时清除。fail-open 同块。
-            const markRef = guard.changeName || 'recent-quick'
-            try {
-              const { markFrNeedsReview } = await import('../fr-index.js')
-              const mr = markFrNeedsReview(join(specBase, 'knowledge'), frs.map(f => f.id), markRef)
-              if (mr.marked > 0) {
-                console.warn(`⚠️ [FR 待复核标记] ${mr.marked} 条 active FR 已标「待复核：${markRef}」——下次 brainstorm 注入可见，承接翻链时自动清除`)
-              }
-            } catch { /* 标记失败不影响遥测/审计 */ }
+            // 持久打标已拆（2026-09-29-rot-retire-inject-cap：371 条零消费实证）——
+            // 遥测 + 当场 warn 即止，不留账。fail-open 同块。
             console.warn(`⚠️ [FR 腐烂 suspect·advisory] 本次 quick 触达 ${[...touchedDomains].join('、')} 域的 ${frs.length} 条 active FR——quick 不走归档，若改动影响这些行为，索引不会自动 supersede（L3 声明义务；盲区：unmapped 文件/map 漂移不报警）`)
           }
         }

package/src/run/stage.js

@@ -416,7 +416,11 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
       // 注：CLI 进程入口的新会话已被 index.js refuseRetiredQuickFreshStart 预门拦下，本门兜底
       // 进程内直调 runCommand 的入口（测试/编程调用）与 --change 指向不存在会话的形态。
       console.error(`❌ quick 通道已退役，无法启动 quick 会话（若带 --change 则该会话不存在或已清理）。`)
-      console.error(`   新工作请走轻量变更：sillyspec flow start --change <名> --input "<动机与背景；随后独立一行『成功标准：』；再每行一条『- <可验证标准>』>"`)
+      console.error(`   新工作请走轻量变更（--input 引号内换行合法，可照抄）：`)
+      console.error('   sillyspec flow start --change <YYYY-MM-DD-名> --input "<动机与背景>')
+      console.error('')
+      console.error('   成功标准：')
+      console.error('   - <可验证标准>"')
       console.error(`   升级前进行中的 quick 会话仍可收尾：sillyspec run quick --change <会话ID> 续跑 / --done 收口 / --cancel 取消。`)
       // 进程内路径幻影残留清理（best-effort）：CLI 入口已被 index.js 预门拦下；进程内直调
       // runCommand 的新会话形态在 command.js 已生成 sid + owner.json + current-quick-run-id +