sillyspec 3.33.7 → 3.33.9

package/src/checkpoint.js

@@ -0,0 +1,258 @@
+/**
+ * checkpoint.js — 任务级影子提交存档（tick 即快照，2026-10-28-shadow-checkpoint）
+ *
+ * 定位：断点恢复从「进度级」（tasks.md 记做到哪）升级到「内容级」（工作区长什么样）——
+ * task tick 成功翻格后落一个 git 影子提交到 refs/sillyspec/checkpoints/<change>，agent
+ * 跑歪/改崩时 git restore --source 一键读档。git 对象库本身是内容寻址存储：增量成本=
+ * 只哈希变化文件，相同内容全局一份——零新依赖即得 CAS 快照性质。
+ *
+ * 机制（多 agent 共享仓安全是第一约束）：
+ *   - 临时索引 GIT_INDEX_FILE=.git/sillyspec-cp-index-<session>（会话隔离）——read-tree HEAD
+ *     起底 → add -A（硬排除清单）→ write-tree → commit-tree 成链（父=上一存档，首档父=
+ *     当时 HEAD）→ update-ref。共享 index 全程零读写（staged 面不可能被卷走，规则 11 纪律）。
+ *   - 无变化 no-op：write-tree 结果与现 ref 树 SHA 相同即跳过（零对象零 ref 翻转）。
+ *   - fail-open 铁律：本模块任何失败只返回 skipped（reason 留痕），绝不抛出阻断 tick。
+ *
+ * 边界：worktree 会话跳过（v1 主仓形态——git-dir ≠ common-dir 判定）；未忽略 untracked
+ * 总量超阈值（缺省 200MB，checkpoint.maxUntrackedMB）早停跳过；.sillyspec/.runtime 与
+ * 常见产物目录/.env* 硬排除不进快照（gitignore 之外的第二道防线）。
+ */
+import { existsSync, readFileSync, rmSync, statSync } from 'fs'
+import { join, resolve as resolvePath } from 'path'
+import { git, gitQuiet } from './git-helper.js'
+
+const REF_PREFIX = 'refs/sillyspec/checkpoints/'
+const DEFAULT_MAX_UNTRACKED_MB = 200
+const SUBJECT_PREFIX = 'sillyspec-cp: '
+const NOOP_GUARD_TREE_TIMEOUT_MS = 60000
+
+/** 硬排除清单（add 后在临时索引上 reset 的路径）。目录用 glob 双星任意深度形态
+ * （:(glob) 魔法 + 前置双星斜杠 + 尾部斜杠双星——实证 2.45：缺尾部 /** 时零匹配，
+ * 根级与嵌套 packages/x/node_modules 一并排除，2026-10-28-cp-review-debt FR-01）；
+ * .env* 与 .sillyspec/.runtime 维持根级语义。 */
+const EXCLUDE_DIRS = ['node_modules', 'dist', 'build', 'target', '.venv', 'venv', '__pycache__', '.next', '.cache', 'coverage']
+const RESET_SPECS = [...EXCLUDE_DIRS.map((d) => `:(glob)**/${d}/**`), '.env', '.env.*', '.sillyspec/.runtime']
+
+/** 与 EXCLUDE_SPECS 同口径的 JS 判定（体积护栏用——只计真会进快照的文件）。 */
+function isHardExcluded(p) {
+  const segs = p.split('/')
+  if (segs.some((s) => EXCLUDE_DIRS.includes(s))) return true
+  const root = segs[0]
+  if (root === '.env' || /^\.env\..+$/.test(root)) return true
+  if (p === '.sillyspec/.runtime' || p.startsWith('.sillyspec/.runtime/')) return true
+  return false
+}
+
+const SAFE_CHANGE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+/**
+ * 读 .sillyspec/local.yaml 的 checkpoint 块（手解析单一键路径，沿 worktree supplyFiles
+ * 先例零 yaml 依赖）。fail-open：文件缺失/解析异常一律返回缺省（enabled=true）。
+ * @returns {{enabled: boolean, maxUntrackedMB: number}}
+ */
+export function readCheckpointConfig(repoRoot) {
+  const defaults = { enabled: true, maxUntrackedMB: DEFAULT_MAX_UNTRACKED_MB }
+  try {
+    const p = join(repoRoot, '.sillyspec', 'local.yaml')
+    if (!existsSync(p)) return defaults
+    const vals = {}
+    let inBlock = false
+    for (const rawLine of readFileSync(p, 'utf8').split(/\r?\n/)) {
+      const line = rawLine.replace(/\t/g, '  ')
+      if (/^checkpoint:\s*(#.*)?$/.test(line)) { inBlock = true; continue }
+      if (!inBlock) continue
+      if (/^\S/.test(line)) break // 出块：下一个顶层键
+      const m = line.match(/^\s+([\w.-]+):\s*(.*?)\s*(#.*)?$/)
+      if (m && m[2] !== '') vals[m[1]] = m[2]
+    }
+    const enabled = vals.enabled === undefined ? true : !/^(false|off|no|0)$/i.test(String(vals.enabled))
+    const mb = Number(vals.maxUntrackedMB)
+    return { enabled, maxUntrackedMB: Number.isFinite(mb) && mb > 0 ? mb : DEFAULT_MAX_UNTRACKED_MB }
+  } catch {
+    return defaults
+  }
+}
+
+/** 主仓判定：worktree 会话（git-dir ≠ common-dir）v1 跳过存档。 */
+function isWorktreeSession(repoRoot) {
+  const gitDir = gitQuiet(repoRoot, ['rev-parse', '--absolute-git-dir'])
+  const commonDir = gitQuiet(repoRoot, ['rev-parse', '--git-common-dir'])
+  if (!gitDir || !commonDir) return false // 探测失败不拦（留给后续 git 调用自然 fail-open）
+  if (commonDir === '.git') return false // 主仓：两者同指
+  try {
+    return resolvePath(repoRoot, gitDir) !== resolvePath(repoRoot, commonDir)
+  } catch {
+    return gitDir !== commonDir
+  }
+}
+
+/**
+ * 落一个影子提交（fail-open：任何失败返回 {kind:'skipped', reason}，绝不抛出）。
+ * @param {{repoRoot: string, changeName: string, session?: string, taskId?: string}} opts
+ * @returns {Promise<{kind:'created'|'noop'|'skipped', sha?: string, treeSha?: string,
+ *   parent?: string, files?: number, reason?: string, detail?: string}>}
+ */
+export async function createCheckpoint({ repoRoot, changeName, session, taskId }) {
+  const name = String(changeName || '')
+  if (!SAFE_CHANGE_NAME_RE.test(name)) return { kind: 'skipped', reason: 'invalid-change-name', detail: name }
+  const cfg = readCheckpointConfig(repoRoot)
+  if (!cfg.enabled) return { kind: 'skipped', reason: 'checkpoint-disabled' }
+  if (isWorktreeSession(repoRoot)) return { kind: 'skipped', reason: 'worktree-session' }
+
+  const ref = REF_PREFIX + name
+  const gitDir = gitQuiet(repoRoot, ['rev-parse', '--absolute-git-dir'])
+  if (!gitDir) return { kind: 'skipped', reason: 'not-a-git-repo' }
+  const sessionId = String(session || process.env.SILLYSPEC_SESSION_ID || 'anon').replace(/[^A-Za-z0-9._-]/g, '_')
+  const tmpIndex = join(gitDir, `sillyspec-cp-index-${sessionId}`)
+  // env 展开铁律（git-helper 终批-③）：裸替换丢 SystemRoot/TEMP 在 Windows 必炸
+  const idxEnv = { ...process.env, GIT_INDEX_FILE: tmpIndex }
+  const head = gitQuiet(repoRoot, ['rev-parse', 'HEAD'])
+  if (!head) return { kind: 'skipped', reason: 'no-head-commit' }
+
+  try {
+    rmSync(tmpIndex, { force: true }) // 清上次中断残留（同会话同路径幂等）
+    git(repoRoot, ['read-tree', 'HEAD'], { env: idxEnv })
+
+    // 体积护栏：只计真会进快照的 untracked（硬排除同口径），累计超限早停
+    const maxBytes = cfg.maxUntrackedMB * 1024 * 1024
+    const othersRaw = gitQuiet(repoRoot, ['ls-files', '--others', '--exclude-standard', '-z'])
+    if (othersRaw) {
+      let bytes = 0
+      for (const p of othersRaw.split('\0')) {
+        if (!p || isHardExcluded(p)) continue
+        try {
+          bytes += statSync(join(repoRoot, p)).size
+        } catch { /* 文件瞬失：计 0 不拦 */}
+        if (bytes > maxBytes) return { kind: 'skipped', reason: 'untracked-size-over-limit', detail: `${Math.round(bytes / 1048576)}MB > ${cfg.maxUntrackedMB}MB` }
+      }
+    }
+
+    // 裸 add -A（无 pathspec）：ignored 文件静默跳过——显式 pathspec 形态遇 gitignored
+    // 候选会整体报错拒加（"paths are ignored by .gitignore"，.sillyspec/ 被忽略的仓必炸）。
+    // 硬排除随后以 reset 收窄：临时索引上把排除路径退回 HEAD 态（不在 HEAD 的即整条移出）。
+    git(repoRoot, ['add', '-A'], { env: idxEnv, timeout: NOOP_GUARD_TREE_TIMEOUT_MS })
+    git(repoRoot, ['reset', '-q', '--', ...RESET_SPECS], { env: idxEnv })
+    const treeSha = git(repoRoot, ['write-tree'], { env: idxEnv })
+
+    const current = gitQuiet(repoRoot, ['rev-parse', '--verify', ref])
+    if (current) {
+      const currentTree = gitQuiet(repoRoot, ['rev-parse', `${ref}^{tree}`])
+      if (currentTree === treeSha) return { kind: 'noop', treeSha } // 无变化：零对象零翻转
+    }
+
+    const parent = current || head
+    const subject = `${SUBJECT_PREFIX}${name} ${taskId || '-'} ${new Date().toISOString()}`
+    const message = `${subject}\n\nshadow checkpoint for ${name}\ntask: ${taskId || '-'}\nsession: ${sessionId}\n`
+    // 身份兜底（沿 worktree baseline checkpoint 先例）：未配置 user.email 时注入临时身份，
+    // 已配置则用真实身份——存档提交可归属
+    const cpEnv = { ...process.env }
+    if (!gitQuiet(repoRoot, ['config', 'user.email'])) {
+      cpEnv.GIT_AUTHOR_NAME = 'sillyspec-checkpoint'
+      cpEnv.GIT_AUTHOR_EMAIL = 'checkpoint@sillyspec.local'
+      cpEnv.GIT_COMMITTER_NAME = 'sillyspec-checkpoint'
+      cpEnv.GIT_COMMITTER_EMAIL = 'checkpoint@sillyspec.local'
+    }
+    const sha = git(repoRoot, ['commit-tree', treeSha, '-p', parent, '-F', '-'], { input: message, env: cpEnv })
+    git(repoRoot, ['update-ref', ref, sha])
+
+    let files = 0
+    const changed = gitQuiet(repoRoot, ['diff-tree', '--no-commit-id', '--name-only', '-r', sha])
+    if (changed) files = changed.split('\n').filter(Boolean).length
+    return { kind: 'created', sha, treeSha, parent, files }
+  } catch (e) {
+    return { kind: 'skipped', reason: 'git-error', detail: e && e.message ? e.message : String(e) }
+  } finally {
+    try { rmSync(tmpIndex, { force: true }) } catch { /* 清理失败：同会话下次覆盖 */ }
+  }
+}
+
+/**
+ * 列出变更的存档链（按时间倒序；链尾混入主历史，按 subject 前缀过滤）。
+ * @returns {Promise<Array<{sha: string, taskId: string|null, ts: number, files: number}>>}
+ */
+export async function listCheckpoints({ repoRoot, changeName }) {
+  const name = String(changeName || '')
+  if (!SAFE_CHANGE_NAME_RE.test(name)) return []
+  const ref = REF_PREFIX + name
+  const log = gitQuiet(repoRoot, ['log', '--format=%H%x09%at%x09%s', '-n', '200', ref])
+  if (!log) return []
+  const out = []
+  for (const line of log.split('\n')) {
+    if (!line) continue
+    const [sha, at, subject] = line.split('\t')
+    if (!subject || !subject.startsWith(SUBJECT_PREFIX)) continue // 链尾以下的主历史止步
+    const m = /^sillyspec-cp: \S+ (task-\d+|-) /.exec(subject)
+    const files = gitQuiet(repoRoot, ['diff-tree', '--no-commit-id', '--name-only', '-r', sha])
+    out.push({ sha, taskId: m && m[1] !== '-' ? m[1] : null, ts: Number(at) * 1000, files: files ? files.split('\n').filter(Boolean).length : 0 })
+  }
+  return out
+}
+
+/**
+ * 恢复预览：工作区 vs 存档点的 diff（patch 与 stat 各一份）。
+ * @returns {Promise<{stat: string, patch: string}>}
+ */
+export async function previewRestore({ repoRoot, sha, paths = [] }) {
+  const spec = ['--', ...(paths && paths.length ? paths : ['.'])]
+  const stat = git(repoRoot, ['diff', '--stat', sha, ...spec])
+  const patch = git(repoRoot, ['diff', sha, ...spec])
+  return { stat, patch }
+}
+
+/**
+ * 链内校验（无上限）：subject 前缀过滤全链——不复用 listCheckpoints 的 -n 200 显示帽
+ * （截断解耦，2026-10-28-cp-review-debt FR-03：超帽旧档同样可读，主历史普通提交仍拒）。
+ */
+function isCheckpointInChain(repoRoot, ref, sha) {
+  const subjects = gitQuiet(repoRoot, ['log', '--format=%H %s', ref])
+  if (!subjects) return false
+  for (const line of subjects.split('\n')) {
+    if (!line) continue
+    const commitSha = line.slice(0, 40)
+    const subject = line.slice(41)
+    if (!subject.startsWith(SUBJECT_PREFIX)) break // 链尾以下为主历史，止步
+    if (commitSha === sha) return true
+  }
+  return false
+}
+
+/**
+ * 读档：git restore --source（仅写工作区，零触碰 index）。调用方负责 --yes 确认纪律。
+ * @param {{repoRoot: string, sha: string, paths?: string[], all?: boolean}} opts
+ * @returns {Promise<{ok: boolean, reason?: string, restored: string[]}>}
+ */
+export async function restoreCheckpoint({ repoRoot, sha, changeName, paths = [], all = false }) {
+  const name = String(changeName || '')
+  const ref = REF_PREFIX + name
+  if (!SAFE_CHANGE_NAME_RE.test(name) || !isCheckpointInChain(repoRoot, ref, sha)) {
+    return { ok: false, reason: 'sha 不在该变更存档链中（用 checkpoint --change 列出可用 SHA）', restored: [] }
+  }
+  const target = (all || !paths.length) ? ['.'] : paths
+  try {
+    git(repoRoot, ['restore', `--source=${sha}`, '--', ...target])
+    return { ok: true, restored: target }
+  } catch (e) {
+    return { ok: false, reason: e && e.message ? e.message : String(e), restored: [] }
+  }
+}
+
+/** 删除变更的存档 ref（change-delete 清理步用；best-effort 不抛出）。 */
+export function deleteCheckpointRef(repoRoot, changeName) {
+  const name = String(changeName || '')
+  if (!SAFE_CHANGE_NAME_RE.test(name)) return false
+  try {
+    git(repoRoot, ['update-ref', '-d', REF_PREFIX + name])
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** ref 存在性探测（dry-run 报告面用）。 */
+export function hasCheckpointRef(repoRoot, changeName) {
+  const name = String(changeName || '')
+  if (!SAFE_CHANGE_NAME_RE.test(name)) return false
+  return Boolean(gitQuiet(repoRoot, ['rev-parse', '--verify', REF_PREFIX + name]))
+}
+
+export default { createCheckpoint, listCheckpoints, previewRestore, restoreCheckpoint, deleteCheckpointRef, hasCheckpointRef, readCheckpointConfig }

package/src/config-schema.js

@@ -72,12 +72,33 @@ export const LOCAL_YAML_SCHEMA = {
         { path: 'commands.lint', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'runQuickTestLintGate (src/run/quick-audit.js)', 'validateCommands (src/scan-postcheck.js)'], desc: 'lint 命令——quick --done 触及 src/test 时 CLI 亲自执行（P0-2 门禁，失败阻断完成）。', example: 'npm run lint' },
         { path: 'commands.test_timeout_sec', type: 'number', optional: true, status: 'live', readers: ['resolveTestTimeoutMs (src/verify-postcheck.js)'], desc: 'commands.test 超时秒数（R9 实证 2026-09-23：全量套件实测可达 27min，固定 600s 帽必杀）——优先级 local.yaml 本键 > env SILLYSPEC_TEST_TIMEOUT_MS > 缺省 600。慢仓在此提帽，防真慢套件被当超时失败。', example: '2400' },
         { path: 'commands.lint_timeout_sec', type: 'number', optional: true, status: 'live', readers: ['runVerifyLintCheck (src/verify-postcheck.js)'], desc: 'commands.lint 超时秒数——优先级 显式调用参 > 本键 > env SILLYSPEC_LINT_TIMEOUT_MS > 缺省 180（快照内 junction I/O 慢，快照路径调用侧显式传 300）。', example: '600' },
+        { path: 'commands.metrics', type: 'string', optional: true, status: 'live', readers: ['runVerifyMetricsCheck (src/verify-postcheck.js)', 'runQuickTestLintGate (src/run/quick-audit.js)'], desc: '【2026-10-29-open-metrics-gate】可选指标门命令——收口实测在隔离快照内执行，非零退出=门红阻断收口；未配置或标 unavailable 跳过留痕（fail-open）。适合复杂度上限/重复率/死代码/覆盖率阈值类秒级检查：命令开放不绑定工具，生态/构建工具检查任务（npx 类零安装、mvn/gradle 检查目标等）或仓内自写脚本均可；执行时注入 SILLYSPEC_CHANGE_FILES（本变更文件清单，POSIX 相对路径换行分隔）供大仓增量门只扫变更面（历史存量债不拦新变更）；变异测试等慢工具建议提帽或放 pre-push/CI 层。', example: 'npx jscpd src' },
+        { path: 'commands.metrics_timeout_sec', type: 'number', optional: true, status: 'live', readers: ['runVerifyMetricsCheck (src/verify-postcheck.js)'], desc: 'commands.metrics 超时秒数——优先级 显式调用参 > 本键 > env SILLYSPEC_METRICS_TIMEOUT_MS（毫秒） > 缺省 180（快照内 junction I/O 慢，快照路径调用侧显式传 300）。', example: '600' },
         { path: 'commands.smoke', type: 'string', optional: true, status: 'live', readers: ['executeVerifyQualityScan (src/run/verify-quality-scan.js)'], desc: '接口冒烟命令——verify 阶段 CLI 亲跑（脚本自理服务生命周期：后台起服+轮询就绪+finally 杀），300s 超时帽，失败/超时只记失败态不阻断本步、触发 PASS 封顶（D-002）；指纹含此键，未变不重跑。', example: 'node scripts/smoke.mjs' },
         { path: 'commands.install', type: 'string', optional: true, status: 'live', readers: ['extractInstallCommand (src/worktree-deps.js)'], desc: '依赖安装命令（worktree 依赖 provisioning 用）。', example: 'npm install' },
         { path: 'commands.knowledge-gate', type: 'boolean', optional: true, status: 'live', readers: ['completeStep (src/run/complete.js)'], desc: '【2026-09-28-unclear-req-to-brainstorm FR-03/D-004】brainstorm 方案步（提出 2-3 种方案）--done 知识检索命中回显开关——缺省 true=开（对 --output 与 decisions.md 条目跑既有检索匹配器，命中 warn 回显「须 evidence 回应或说明不复潮」不阻断）；false（或 off）关回显，无命中时输出与现状一致。', example: 'false' },
         { path: 'commands.scan:check', type: 'string', optional: true, status: 'live', readers: ['scan 漂移检查（scripts/scan-drift-check.py 经 scan 流程调用）'], desc: '【2026-10-23-schema-registration-debt 平台仓 dogfood 补登】scan 产物漂移自检命令。', example: 'python scripts/scan-drift-check.py' },
       ],
     },
+    {
+      id: 'metrics_routes',
+      title: '指标门路由（多语言/monorepo）',
+      note: '【2026-10-29-metrics-routes】与 commands.metrics 单命令门共存：按变更文件面 ∩ gate.paths 路径前缀路由，仅执行命中 gate（串行）；语言中立（路径集合，不枚举语言/框架）。段未配置=零变化。',
+      keys: [
+        { path: 'metrics_routes.<name>.paths', type: 'array', optional: true, status: 'live', readers: ['extractMetricsRoutes (src/verify-postcheck.js)'], desc: 'gate 的路径前缀集合（仓根相对）——段全等匹配：frontend/ 不命中 frontend-v2/；引号数组 `["a/", "b/"]` 或逗分裸串均可。', example: '["frontend/", "packages/web/"]' },
+        { path: 'metrics_routes.<name>.command', type: 'string', optional: true, status: 'live', readers: ['runVerifyMetricsRoutesCheck (src/verify-postcheck.js)'], desc: 'gate 的指标门命令——gate 命中（变更文件面 ∩ paths 非空）才执行，非零退出=门红；gate 子进程注入 SILLYSPEC_CHANGE_FILES=该 gate 命中子集（gate 内工具可增量扫）。', example: 'npx --prefix frontend eslint . --max-warnings 0' },
+        { path: 'metrics_routes.<name>.timeout_sec', type: 'number', optional: true, status: 'live', readers: ['runVerifyMetricsRoutesCheck (src/verify-postcheck.js)'], desc: 'gate 级超时秒数——优先级 本键 > 调用侧快照帽 > commands.metrics_timeout_sec > env SILLYSPEC_METRICS_TIMEOUT_MS（毫秒）> 缺省 180。', example: '300' },
+      ],
+    },
+    {
+      id: 'checkpoint',
+      title: '影子存档（task tick 快照）',
+      note: '机制先落代码缺省（fail-open，缺省零回归）——键只用于仓主显式调优（2026-10-28-shadow-checkpoint）。',
+      keys: [
+        { path: 'checkpoint.enabled', type: 'boolean', optional: true, status: 'live', readers: ['readCheckpointConfig (src/checkpoint.js)'], desc: '影子存档开关——task tick 成功翻格后落 git 影子提交到 refs/sillyspec/checkpoints/<change>（临时索引零触碰共享暂存区，断点恢复从进度级升到内容级）。缺省 true；false 关闭（tick 照常）。解析失败 fail-open 取缺省。', example: 'false' },
+        { path: 'checkpoint.maxUntrackedMB', type: 'number', optional: true, status: 'live', readers: ['readCheckpointConfig (src/checkpoint.js)'], desc: '体积护栏——未忽略 untracked 总量超过该 MB 数时跳过本次存档并留痕（早停判定，不遍历全树；硬排除目录不计入）。缺省 200。', example: '50' },
+      ],
+    },
     {
       id: 'knowledge',
       title: '知识检索（平台向量语义召回）',
@@ -423,8 +444,23 @@ commands:
   # install: npm install   # worktree 依赖安装命令
   # test_timeout_sec: 2400   # commands.test 超时秒数（慢仓提帽；缺省 600，env SILLYSPEC_TEST_TIMEOUT_MS 同效）
   # lint_timeout_sec: 600    # commands.lint 超时秒数（缺省 180）
+  # metrics: npx jscpd src   # 可选指标门：收口实测非零退出阻断（复杂度/重复/死代码/覆盖率阈值类秒级检查；执行注入 SILLYSPEC_CHANGE_FILES=本变更文件清单可只扫变更面；变异测试类慢工具建议 pre-push/CI）
+  # metrics_timeout_sec: 600   # commands.metrics 超时秒数（缺省 180）
+# metrics_routes:             # 多语言/monorepo 路由门（与上面 metrics 单命令可共存；仅跑变更命中的 gate）
+#   web:
+#     paths: ["frontend/", "packages/web/"]   # 路径前缀集合（段全等：frontend/ 不蹭 frontend-v2/）
+#     command: npx --prefix frontend eslint . --max-warnings 0
+#   jvm:
+#     paths: ["backend/"]
+#     command: mvn -B -f backend/pom.xml pmd:check
+#     timeout_sec: 300         # gate 级超时（缺省 180）；gate 子进程注入 SILLYSPEC_CHANGE_FILES=命中子集
   # knowledge-gate: false    # 方案步 --done 知识检索命中回显开关（缺省 true 开；false 关回显）
 
+# ── 影子存档（task tick 快照；缺省开启零配置，仅在显式调优时写）──
+# checkpoint:
+#   enabled: true             # 影子存档开关（false 关闭，tick 照常）
+#   maxUntrackedMB: 200       # 体积护栏——未忽略 untracked 总量超此 MB 数跳过存档留痕
+
 # ── 知识检索（平台向量语义召回）──
 # 缺省（未写整段）跟随平台能力自动探测：端点在场自动启用、未部署自动跳过（部署后自动
 # 启用，零配置）。仅显式逃生阀时才需要写：

package/src/flow-parity.js

@@ -305,60 +305,20 @@ export function renderVerifyReceipt({ change, baseline, head, gateSummary, revie
 }
 
 /**
- * design 槽4（风险与死路）实质作答收割 → decisions.md（已有不覆盖）。
- * @returns {{harvested: boolean, reason?: string}}
+ * design 槽4（风险与死路）收割——已下线（2026-11-02-slot4-harvest-retire）。
+ *
+ * 历史动机（2026-09-25-thin-parity-assets）：轻量变更决策产出从零到一，合成底稿条目随蒸馏
+ * 链进 knowledge。4A 数据对账实证产物全是模板底稿（本仓 47 条、平台 173 条），标题模板化、
+ * 无真否决语义——底稿资格门（series-final-cleanup）已解决行为面（不占防复潮席位），本变更
+ * 根治数据面：不再合成伪决策条目。风险分析内容保留在 design.md 归档冻结件（信息零丢失）。
+ *
+ * 函数保留签名与导出（flow.js 调用点已摘除，anchorBackfillCandidate 同文件导出不能删）。
+ * @returns {{harvested: boolean, reason: string}} 恒 {harvested:false}
  */
 export function harvestSlot4Decision({ changeDir, change }) {
   const decPath = join(changeDir, 'decisions.md')
   if (existsSync(decPath)) return { harvested: false, reason: 'decisions.md 已在场（不覆盖）' }
-  let dText
-  try { dText = readFileSync(join(changeDir, 'design.md'), 'utf8') } catch { return { harvested: false, reason: '无 design.md' } }
-  const lines = dText.replace(/\r\n/g, '\n').split('\n')
-  let inSlot = false
-  const buf = []
-  for (const line of lines) {
-    if (/^<!--\s*AGENT:槽4/.test(line)) { inSlot = true; continue }
-    if (inSlot && (/^<!--/.test(line) || /^#{1,6}\s/.test(line))) break
-    if (inSlot) buf.push(line)
-  }
-  let answer = buf.join('\n').trim()
-  // v2 纯 markdown（2026-10-04-thin-docs-v2）：无槽标记时改读「风险与死路」节正文（复用
-  // flow-review 的 v2 节读取——剥离问题原文行；单一源 DESIGN_QUESTIONS 防镜像漂移）
-  if (!inSlot) {
-    const risksSec = DESIGN_QUESTIONS.sections.find((s) => s.key === 'risks')
-    answer = readV2SectionAnswer(dText, risksSec.heading, DESIGN_QUESTIONS)
-  }
-  if (!answer || /^不适用/.test(answer)) return { harvested: false, reason: '槽4 空/不适用' }
-  // 锚点自动回填（2026-10-15-decision-anchor-backfill 收割端）：风险段作答文本恰含一个
-  // 路径 token → 写入 - 锚点：行（源 decisions.md 是真相源，蒸馏自然带上、人可改）；
-  // 0/多候选不写（蒸馏端渲染时还会再兜底一次同款判定）。单一源 anchorBackfillCandidate。
-  const anchorCand = anchorBackfillCandidate(answer)
-  const anchorLine = anchorCand ? [`- 锚点：${anchorCand}`] : []
-  const text = [
-    '---',
-    `author: flow-machine-draft`,
-    `created_at: ${new Date().toISOString()}`,
-    '---',
-    `# 决策记录（Decisions）— ${change}`,
-    '',
-    // 标题自解释（2026-10-15-harvest-title-clarify）：读者面是 decisions 文档与 knowledge，
-    // 机制出处（槽4 收割）由 frontmatter author: flow-machine-draft 承载，标题只说内容与性质。
-    `## D-001@v1: 设计期风险与放弃方案（底稿）`,
-    `- 类型：process`,
-    `- 状态：confirmed`,
-    ...anchorLine,
-    // 类型/状态字段（2026-09-26-slot4-distill-fix）：蒸馏链入选要 status∈{confirmed|accepted|rejected}
-    // 且 type∈七类白名单，字段解析只认 `- 字段：值` 列表行形态——此前收割条目零字段致永不入选，
-    // 「随蒸馏链进 knowledge」断链（thin-agent-tasks 教训留档归档而 knowledge 零落地的实证）。
-    // 槽4 是定案的流程/方法论取舍，process+confirmed 语义成立。
-    `- 答案：${answer.replace(/\s*\n+\s*/g, ' ')}`,
-    // 正文用「答案」标签（同修）：distill 落盘「理由：」行取 entry.answer——此前「- 决策：」非白名单
-    // 字段，正文不随条目进 knowledge（骨架落盘内容丢失）。一行展平（评审 P1 清偿）：字段解析是
-    // 单行契约，多行槽4 作答经 \n 续行会静默丢后续行——收割端压平为单行（空格分隔）保全文。
-    '',
-  ].join('\n')
-  writeAtomicSync(decPath, text)
-  return { harvested: true }
+  return { harvested: false, reason: '底稿收割已下线（2026-11-02-slot4-harvest-retire）——风险分析保留在 design.md 归档件，不再合成伪决策条目' }
 }
 
 export default { reconcileModuleDocs, renderVerifyReceipt, harvestSlot4Decision, collectFreezeFiles, backfillGateSummary, motiveFromInput }

package/src/flow-review.js

@@ -303,6 +303,10 @@ export function renderReviewerTaskbook({ change, changeDir, head = null, probeLi
     `     没有任何声明边界时写「无声明边界」。未裁决=未审。`,
     `  4. 作答中的防护声明（如有）：声称的防护机制在代码里真实存在且生效？`,
     `  5. 生成物同步（如涉及）：类型/契约文件与实现对齐？`,
+    // 测试有效性与根因性（2026-10-29-open-metrics-gate task-04，ub-mode「Test Behavior, Not
+    // Implementation」/「Fix Root Causes」转写）：从「测试存在且绿」升级到「测试有效」——空实现
+    // 判据给评审员可操作的假测试检验法，根因判据拦「吞崩溃 guard 冒充修复」。
+    `  6. 测试有效性与根因性（假测试判据两问）：空实现判据——把绑定测试所测的实现改成全部返回空的空操作，若测试仍可能全绿则测试无效（断言须测可观察行为，mock 一切零断言的摆设测试按无效报）；根因判据——diff 中的修复是否只是吞崩溃/藏失败的 guard（兜底掩盖≠根因消除，须指出并按严重度裁决）。`,
     // 项目评审探针（2026-10-12-review-probe-injection）：local.yaml review_probes 数据驱动注入——
     // 检查单生产权收归 CLI 的项目特有面（dogfood 实证：主代理手写清单没想到的面无人查）。
     // 未配置零注入——本段缺省时任务书与历史形态逐字一致（零回归）。

package/src/flow.js

@@ -31,6 +31,7 @@ import { join, relative, dirname } from 'node:path'
 import { DatabaseSync } from 'node:sqlite'
 import yaml from 'js-yaml'
 import { git, gitQuiet } from './git-helper.js'
+import { scopeTelemetryRefs } from './knowledge-graph.js'
 import { writeAtomicSync } from './fs-atomic.js'
 import { resolveRuntimeRoot, triggerSync, triggerSyncTerminalStrict, assertDatedChangeName } from './run/shared.js'
 import { detectUiTouch, buildUiGuidanceLines, runUiVisualProbe, readUiVisualGate, UI_EVIDENCE_FILENAME } from './ui-visual.js'
@@ -308,6 +309,7 @@ export async function flowKnowledgeDigest({ specBase, change, changeDir, input,
       const alwaysRepo = [...scoped.always, ...scoped.repo]
       summary.scopedEntries = alwaysRepo.length
       scopedLines.push('   🧭 工具中立性（内置规约 00，每变更恒注入）：不枚举定义开放世界、不锁死开发语言/框架——配置与机制用 CLI 自有分类（批类别/路径集合），新增语言只加探测适配。')
+      scopedLines.push('   🧭 反例（任务词汇——违规现场词面相似即命中）：评测工具缺省写死两个仓的路径即违规——每条路径必须来自 --repo 参数或缺省当前仓；出现具体项目名/项目特定 env/硬编码仓表即违规（2026-11-02 用户原话纠正实证）。')
       for (const e of alwaysRepo.slice(0, 5)) {
         scopedLines.push(`   📌 [${e.scope}] ${e.id}：${e.summary}`)
       }
@@ -366,13 +368,42 @@ export async function flowKnowledgeDigest({ specBase, change, changeDir, input,
       const src = km.entries.slice(0, 3).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)).join('；')
       lines.push(`   📚 知识命中（INDEX 关键词，按需 Read）：${src}`)
     }
+    // routeHits 指针行（FR-04，2026-11-02-knowledge-rank-denoise）：entries 移出 fr/decisions
+    // 路由行后，implemented 决策与 FR 的可见性由这里承载（只指路不注入正文）。
+    if (km.matched && (km.routeHits || []).length > 0) {
+      const src = km.routeHits.slice(0, 3).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)).join('；')
+      lines.push(`   🧭 决策/FR 路由命中（专用通道，按需 Read）：${src}`)
+    }
+    // 融合增量（2026-11-02-knowledge-fusion FR-03）：scope 否决独立小节——路由 rejected top-5
+    // 不被热文件历史否决挤占（独立语义：触碰过的文件曾被否决/记死路）
+    const scopeRejected = (km.scopeDecisionHits || []).filter((h) => h.deathPath || h.status === 'rejected').slice(0, 3)
+    if (scopeRejected.length > 0) {
+      lines.push(`   🧭 触达文件关联否决（scope 视角——触碰过的文件曾被否决/记死路，防复潮——除非复潮条件满足勿重提）：`)
+      for (const h of scopeRejected) {
+        const note = h.status === 'rejected' ? (h.reason || '（未记录）') : `死路——${deathPathNote(h.reason)}`
+        lines.push(`   - ${h.id} ${h.title}（${h.file}｜${decisionChangeQualifier(h.change)}｜${h.via === 'two-hop' ? '两跳' : '直连'}）${h.status === 'rejected' ? '否决理由' : '⚰️'}：${note}`)
+      }
+    }
+    const scopeEntries = km.scopeEntries || []
+    if (scopeEntries.length > 0) {
+      const src = scopeEntries.slice(0, 3).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)).join('；')
+      lines.push(`   📚 触达文件关联手工条目（按需 Read）：${src}`)
+    }
     // 遥测导线（2026-10-15-thin-inject-telemetry）：轻量道注入此前不落 hits.jsonl——thin 常态化后
     // inject 事件流断流（本仓 10-09 后归零实证），knowledge stats 从未命中判定被盲区污染。
     // 分级字段（A2-lite）：injectedFiles=正文实际注入（thin 面恒空——只出按需 Read 行）、
     // mentionedFiles=显式展示给 agent 的锚点（📚 行 top-3）。既有 matchedFiles 口径不变
     // （knowledge-stats 消费面零回归）。仅命中面非空才落盘；fail-soft（R-04）不阻断注入。
-    const thinMatchedFiles = km.matched ? (km.entries || []).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)) : []
-    if (thinMatchedFiles.length > 0 || rejected.length > 0) {
+    const thinMatchedFiles = km.matched ? [...(km.entries || []), ...(km.routeHits || [])].map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)) : []
+    // scope 展示面遥测（FR-02）：独立字段 scopeMatchedFiles（不并入 matchedFiles——防 neverHit 失真）；
+    // mentionedFiles 按实际展示集合（📚 top3 + 🧭 top3 + scope top3+3，去重）
+    const scopeMatchedFiles = km.matched ? scopeTelemetryRefs(km) : []
+    const mentionedFiles = [...new Set([
+      ...(km.entries || []).slice(0, 3).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)),
+      ...(km.routeHits || []).slice(0, 3).map((e) => (e.anchor ? `${e.file}#${e.anchor}` : e.file)),
+      ...scopeMatchedFiles,
+    ])].slice(0, 12)
+    if (thinMatchedFiles.length > 0 || rejected.length > 0 || scopeMatchedFiles.length > 0) {
       try {
         const { appendKnowledgeHit } = await import('./knowledge-hits.js')
         appendKnowledgeHit(join(specBase, '.runtime'), {
@@ -381,7 +412,8 @@ export async function flowKnowledgeDigest({ specBase, change, changeDir, input,
           query: kmQuery,
           matchedFiles: thinMatchedFiles,
           injectedFiles: [],
-          mentionedFiles: thinMatchedFiles.slice(0, 3),
+          mentionedFiles,
+          ...(scopeMatchedFiles.length > 0 ? { scopeMatchedFiles } : {}),
           rejectedCount: rejected.length,
           source: 'thin-start',
         })
@@ -2710,13 +2742,8 @@ export async function cmdFlowDone({ change, cwd, specBase, runtimeRootOpt = null
   // requirements 永不进 knowledge/fr，知识复利在新默认道断流；轻量变更无 design.md，域路由
   // 以基线以来交付 diff 供 deliverableFiles，伪域回退同口径）
   if (st.substeps?.distill === 'done') { skip('distill') } else {
-    // 槽4收割（2026-09-25-thin-parity-assets：design「风险与死路」实质作答合成 decisions.md——
-    // 轻量变更决策产出从零到一；已有 decisions 不覆盖）
-    try {
-      const { harvestSlot4Decision } = await import('./flow-parity.js')
-      const h = harvestSlot4Decision({ changeDir, change })
-      if (h.harvested) console.log(`🌱 槽4（风险与死路）收割 → decisions.md（底稿——作答里的放弃方案请拆成 rejected 条目再收口；随蒸馏链进 knowledge）`)
-    } catch { /* 收割 best-effort */ }
+    // 槽4收割已下线（2026-11-02-slot4-harvest-retire）：design 风险段不再合成伪决策条目——
+    // 风险分析保留在 design.md 归档件（信息零丢失），底稿条目 4A 实证为纯模板噪声
     // 模块变更索引机械回写（2026-10-12-thin-module-gate-and-feed 二档）：命中模块的卡/sidecar
     // 追加一行本变更条目——零语义判断（日期/变更名/动机首行全已知），split-changelog 契约 sidecar
     // 优先、卡内「## 变更索引」节次之、变更名在场即跳过（断点续跑幂等）。moduleScope 由上方
@@ -2942,6 +2969,13 @@ async function cmdFlowVerifyDrafts({ change, cwd, specBase, runtimeRootOpt = nul
     for (const a of r.advisories) console.warn(`⚠️ [门柱漂移 advisory] ${a}（不阻断批准）`)
     if (r.degraded) console.log(`ℹ️ 自查降级：draft-ledger 不在此机（.runtime 机本位/存量变更）——空槽兜底校验通过（v2 纯 markdown 无法对锚校验，如实降级）`)
     console.log(`✅ spec 面自查通过（0 violations）——通过≠批准：请把摘要给用户看，用户确认后 sillyspec flow approve --change ${change}（批准留痕后动码）`)
+    // 重叠路由 advisory（2026-10-28-overlap-route FR-04）：批准前最后一个高频触点——当前
+    // 变更声明与他人活跃变更相交时一行分流提示。fail-open 静默：检测异常不拦批准不影响退出码。
+    try {
+      const { overlapAdvisoryFor } = await import('./overlap-detect.js')
+      const line = overlapAdvisoryFor(change, { cwd, specBase })
+      if (line) console.warn(line)
+    } catch { /* advisory 静默：检测失败不拦批准 */ }
   } else {
     for (const a of r.advisories) console.warn(`⚠️ [门柱漂移 advisory] ${a}（不阻断批准）`)
     if (hasViolations) {

package/src/foreign-declared.js

@@ -174,7 +174,8 @@ export function collectForeignDeclaredFiles(cwd, currentChangeName, opts = {}) {
  * （退回旧 foreign-first 行为，fail-closed 不放大放行面）。
  * @returns {Set<string>} 正斜杠归一后的声明路径集
  */
-function loadOwnDeclaredSet(specBase, runtimeRoot, currentChangeName) {
+// export 补齐（2026-10-28-overlap-route）：重叠检测复用声明加载单一源，防口径漂移
+export function loadOwnDeclaredSet(specBase, runtimeRoot, currentChangeName) {
   const set = new Set()
   if (!currentChangeName) return set
   const norm = (p) => String(p || '').replace(/\\/g, '/')