sillyspec 3.28.8 → 3.28.9

package/src/doctor-diagnostics.js

@@ -24,13 +24,15 @@
  */
 import { openDatabase, pluckGet, pluckAll } from './db-engine.js';
 import { safeGit } from './git-helper.js';
+import { createHash } from 'crypto';
 import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync, rmSync } from 'fs';
 import { join, relative, resolve, dirname } from 'path';
 import { gitQuiet } from './git-helper.js'
 import jsYaml from 'js-yaml';
 import { pruneTimestampedEntries } from './runtime-hygiene.js';
 import { CHECK_SEVERITY } from './constants.js';
-import { checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME, QUICK_SID_RE } from './run/shared.js';
+import { checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME, QUICK_SID_RE, resolveRuntimeRoot } from './run/shared.js';
+import { readFrictionLedger } from './friction-ledger.js';
 
 // db 角色标签
 const DB_ROLE = {
@@ -908,6 +910,221 @@ function detectDecisionDrift(cwd) {
   }
 }
 
+/**
+ * apply-manifest 漂移检测（task-03 / FR-04 / D-005@v1，2026-09-14-apply-conflict-hardening）。
+ *
+ * 背景：apply 落地的交付文件可被并行会话的工作区级 git 操作（restore/clean 类）冲掉
+ * （troubleshooting §64），apply 成功尾声由 writeApplyManifest 落 apply-manifest.json
+ * 指纹（文件→sha256），本检查消费该指纹做 apply 后丢失/篡改检测。
+ *
+ * 扫描面（R-03 对齐）：活跃 changes/<变更目录>/apply-manifest.json ∪ 归档
+ * changes/archive/<变更目录>/apply-manifest.json 两目录 glob 统一收集（目录移动即换
+ * 扫描桶，manifest 自身 change
+ * 字段仅作显示名），按 appliedAt 降序取前 5。
+ *
+ * 哈希口径（design 接口定义定案）：manifest 的 sha256 = staged blob 内容（LF 规范态）。
+ * staged 态 = git show :<path> 内容直接 sha256（与写侧天然同基）；worktree 态 =
+ * readFile 后 CRLF→LF 归一（latin1 往返保字节）再算——防 autocrlf=true 工作区 CRLF
+ * 与 blob LF 恒异误报。git blob hash 是 sha1，与指纹 sha256 异构不可直比，故两态均
+ * 自算内容 sha256。approx:true 条目（写侧 staged 不可用、指纹取自磁盘的 fail-open 面）
+ * 跳过 staged 比对——指纹基不是 staged，比了必然误报。
+ *
+ * 三分支判定（advisory / WARNING，不阻断 doctor 既有退出码语义）：
+ *   ①worktree≠manifest → 落盘面漂移（丢失/被改）；②staged≠manifest → 暂存面漂移
+ *   （index 被动过）；③盘上与暂存区皆无 → 丢失。
+ * 单文件/单 manifest 异常 fail-open 跳过（坏一个文件不炸整个 doctor）；无 manifest
+ * 零告警（skipped）；doctor 只读不写。
+ */
+function detectApplyManifestDrift(cwd, specDir) {
+  const base = { name: 'apply_manifest_drift', label: 'apply 交付指纹漂移', safe_actions: [] }
+  try {
+    if (!specDir) {
+      return { ...base, findings: ['无权威 spec 目录，跳过 apply 指纹面——skipped'], pass: true, severity: null, skipped: true }
+    }
+    // 两桶 glob 收集：活跃 changes/ + 归档 changes/archive/
+    const manifests = []
+    let malformed = 0
+    const buckets = [join(specDir, 'changes')]
+    for (const bucket of buckets) {
+      if (!existsSync(bucket)) continue
+      // 归档桶（R-03：归档后补 apply 的 manifest 写在 archive/ 下，一并入扫描面）
+      const scanDirs = [{ dir: bucket, skip: 'archive' }]
+      const archiveDir = join(bucket, 'archive')
+      if (existsSync(archiveDir)) scanDirs.push({ dir: archiveDir, skip: null })
+      for (const { dir, skip } of scanDirs) {
+        let entries
+        try { entries = readdirSync(dir, { withFileTypes: true }) } catch { continue }
+        for (const e of entries) {
+          if (!e.isDirectory() || (skip && e.name === skip)) continue
+          const manifestPath = join(dir, e.name, 'apply-manifest.json')
+          if (!existsSync(manifestPath)) continue
+          try {
+            const m = JSON.parse(readFileSync(manifestPath, 'utf8').replace(/^\uFEFF/, ''))
+            if (!m || !Array.isArray(m.files)) { malformed++; continue }
+            manifests.push({ dirName: e.name, change: typeof m.change === 'string' && m.change ? m.change : e.name, appliedAt: m.appliedAt, files: m.files })
+          } catch { malformed++; continue } // 单 manifest 坏（JSON/形状）→ fail-open 跳过
+        }
+      }
+    }
+    if (manifests.length === 0) {
+      const findings = ['无 apply-manifest.json（无 apply 指纹面）——skipped']
+      if (malformed > 0) findings.push(`${malformed} 份 manifest 不可解析已跳过`)
+      return { ...base, findings, pass: true, severity: null, skipped: true }
+    }
+    // appliedAt 降序取前 5（最新 apply 优先；不可解析时间戳沉底）
+    manifests.sort((a, b) => (Date.parse(b.appliedAt) || 0) - (Date.parse(a.appliedAt) || 0))
+    const scanned = manifests.slice(0, 5)
+    const findings = []
+    let checked = 0
+    for (const m of scanned) {
+      for (const ent of m.files) {
+        if (!ent || typeof ent.path !== 'string' || typeof ent.sha256 !== 'string') continue // 坏条目跳过
+        checked++
+        const short = (h) => (h || '').slice(0, 8)
+        // worktree 态：readFile 后 CRLF→LF 归一（latin1 往返保字节，防 autocrlf 误报）
+        let worktreeHash = null
+        try {
+          const raw = readFileSync(join(cwd, ent.path))
+          worktreeHash = createHash('sha256')
+            .update(Buffer.from(raw.toString('latin1').replace(/\r\n/g, '\n'), 'latin1'))
+            .digest('hex')
+        } catch { /* 盘上无 → 丢失分支候选 */ }
+        // staged 态：git show :<path> buffer 直接 sha256（staged blob 即 LF 规范态，与写侧同基）
+        let stagedHash = null
+        const blob = gitQuiet(cwd, ['show', `:${ent.path}`], { encoding: 'buffer', timeout: 15000 })
+        if (Buffer.isBuffer(blob)) stagedHash = createHash('sha256').update(blob).digest('hex')
+        const tag = `${m.change}×${ent.path}`
+        if (worktreeHash === null && stagedHash === null) {
+          findings.push(`${tag} 丢失（盘上与暂存区皆无；期望 ${short(ent.sha256)}）`)
+          continue
+        }
+        if (worktreeHash !== null && worktreeHash !== ent.sha256) {
+          findings.push(`${tag} 落盘面漂移（期望 ${short(ent.sha256)} 实际 ${short(worktreeHash)}）`)
+        }
+        if (!ent.approx && stagedHash !== null && stagedHash !== ent.sha256) {
+          findings.push(`${tag} 暂存面漂移（期望 ${short(ent.sha256)} 实际 ${short(stagedHash)}）`)
+        }
+      }
+    }
+    if (malformed > 0) findings.push(`${malformed} 份 manifest 不可解析已跳过`)
+    if (findings.length === 0) {
+      return { ...base, findings: [`apply 指纹面一致（最近 ${scanned.length} 份 manifest × ${checked} 文件零漂移）`], pass: true, severity: CHECK_SEVERITY.PASSED }
+    }
+    return {
+      ...base,
+      findings,
+      pass: false,
+      severity: CHECK_SEVERITY.WARNING,
+      safe_actions: [{
+        dimension: 'apply_manifest_drift',
+        action: 'inspect_drifted_files',
+        risk: 'manual_edit',
+        rationale: 'apply 落地文件与指纹不符（丢失/被改/暂存区被动过）',
+        next_step: '对照 worktree（唯一可信源）逐文件判定直拷/手并，落地后立即 git add -- <files> 提交锁定',
+      }],
+    }
+  } catch (e) {
+    return { ...base, findings: [`探测降级（${e?.message || e}）——skipped`], pass: true, severity: null, skipped: true }
+  }
+}
+
+// ══ 2026-09-15-tax-governance（task-02）：自维护税面 self_maintenance_tax（FR-03）══
+
+/** 税重阈值：单变更累计 total ≥3 记 WARNING（X-07 刻意拉状态——税重提示本就该拉状态） */
+const TAX_HEAVY_TOTAL = 3;
+/** 聚合窗口：近 90 天（archivedAt 口径；无 archivedAt = 变更未归档、摩擦是当前进行时，计入窗口） */
+const TAX_WINDOW_MS = 90 * 24 * 60 * 60 * 1000;
+/** 近窗口聚合展示条数 */
+const TAX_TOP_N = 5;
+/** 类型→中文标签（与 friction-tally.js FRICTION_LABELS 同枚举同序，此处本地复制不动其文件） */
+const TAX_TYPE_LABELS = [['gate_rollback', 'gate 回滚'], ['verify_run_failed', '验证失败'], ['review_rejected', '审查打回']];
+
+/**
+ * 自维护税面（FR-03，只读）：「哪个变更税重」从回忆变成可查数据。
+ *   ① 活跃变更非零 tally 列示（runtimeRoot 下 friction-tally-*.json——verify 收尾 consume 清零
+ *      后仍非零 = 有未消费的进行中摩擦）：纯信息不拉状态；
+ *   ② 台账聚合（friction-ledger.json）：近 90 天 total top5 + 累计总量：纯信息不拉状态；
+ *   ③ 仅单变更 total≥3 记 WARNING（X-07 刻意——detail 注明评估机制群简化/退役）；
+ *   ④ 台账缺失渲染「无台账数据（首次归档后生成）」不告警。
+ * severity 语义（Grill X-07）：聚合/列示 detail 走 pass:true，只有税重 WARNING 会拉低
+ * overall_status（formatDoctorJson 按 severity 计 warning）。runtimeRoot 与写入侧同源走
+ * resolveRuntimeRoot（X-08 平台模式防分裂，pointer.runtimeRoot 优先、同 gcUnstampedExecuteRuns
+ * 的 existsSync 前置门）。探测只读、全程 fail-soft 降级 skipped。
+ */
+export function detectSelfMaintenanceTax(cwd, authoritySpecDir) {
+  const base = { name: 'self_maintenance_tax', label: '自维护税面（摩擦信号台账）', safe_actions: [] };
+  try {
+    const pointer = resolvePointer(cwd);
+    const runtimeRoot = resolveRuntimeRoot(
+      { runtimeRoot: pointer.present && pointer.runtimeRoot && existsSync(pointer.runtimeRoot) ? pointer.runtimeRoot : null },
+      authoritySpecDir || join(cwd, '.sillyspec'),
+    );
+    const findings = [];
+    const warnings = [];
+
+    // ① 活跃非零 tally 列示（events:{type:{count,lastAt}}，X-10 结构）
+    try {
+      for (const f of readdirSync(runtimeRoot)) {
+        const m = f.match(/^friction-tally-(.+)\.json$/);
+        if (!m) continue;
+        let tally = null;
+        try { tally = JSON.parse(readFileSync(join(runtimeRoot, f), 'utf8')); } catch { continue; }
+        const events = tally && typeof tally === 'object' && tally.events && typeof tally.events === 'object' && !Array.isArray(tally.events) ? tally.events : {};
+        const segs = [];
+        let total = 0;
+        let lastAt = '';
+        for (const [type, label] of TAX_TYPE_LABELS) {
+          const n = Number(events[type] && events[type].count);
+          if (!Number.isFinite(n) || n <= 0) continue;
+          segs.push(`${label} ${n}`);
+          total += n;
+          const la = events[type] && typeof events[type].lastAt === 'string' ? events[type].lastAt : '';
+          if (la > lastAt) lastAt = la;
+        }
+        if (total <= 0) continue;
+        findings.push(`活跃摩擦：${m[1]}（${segs.join('、')}${lastAt ? `，最近 ${lastAt}` : ''}）`);
+        if (total >= TAX_HEAVY_TOTAL) warnings.push(`税重——评估该机制群简化/退役（对照其 decisions 退役判据）：${m[1]}（活跃 total ${total}）`);
+      }
+    } catch { /* runtimeRoot 不可读 → 无活跃数据，不误报 */ }
+
+    // ② 台账聚合（近 90 天 top5 + 累计总量）；④ 缺失渲染提示不告警
+    const ledger = readFrictionLedger(runtimeRoot);
+    if (ledger.length === 0) {
+      findings.push('无台账数据（首次归档后生成）');
+    } else {
+      const grandTotal = ledger.reduce((s, e) => s + (Number.isFinite(Number(e.total)) ? Number(e.total) : 0), 0);
+      findings.push(`台账累计：${ledger.length} 个变更 / 总摩擦 ${grandTotal} 次`);
+      const now = Date.now();
+      const recent = ledger.filter((e) => {
+        if (typeof e.archivedAt !== 'string' || !e.archivedAt) return true; // 未归档 = 当前进行时
+        const t = Date.parse(e.archivedAt);
+        return Number.isFinite(t) && now - t <= TAX_WINDOW_MS;
+      });
+      if (recent.length === 0) {
+        findings.push('近 90 天无台账条目');
+      } else {
+        const top = [...recent]
+          .sort((a, b) => (Number(b.total) || 0) - (Number(a.total) || 0))
+          .slice(0, TAX_TOP_N)
+          .map((e) => `${e.change}(${Number(e.total) || 0})`);
+        findings.push(`近 90 天税重 top${top.length}：${top.join('、')}`);
+      }
+      for (const e of ledger) {
+        if ((Number(e.total) || 0) >= TAX_HEAVY_TOTAL) {
+          warnings.push(`税重——评估该机制群简化/退役（对照其 decisions 退役判据）：${e.change}（total ${Number(e.total) || 0}）`);
+        }
+      }
+    }
+
+    if (warnings.length > 0) {
+      return { ...base, findings: [...warnings, ...findings], pass: false, severity: CHECK_SEVERITY.WARNING };
+    }
+    return { ...base, findings, pass: true, severity: CHECK_SEVERITY.PASSED };
+  } catch (e) {
+    return { ...base, findings: [`探测降级（${e?.message || e}）——skipped`], pass: true, severity: null, skipped: true };
+  }
+}
+
 /**
  * renderDoctorSummary（FR-01，全新输出契约——2026-09-09-doctor-noai）：逐维
  * ✅/⚠️/❌ + label + findings 首行 + safe_actions 提示行。顶层非 --json 命令与
@@ -955,7 +1172,12 @@ export async function runDoctorDiagnostics({ cwd }) {
   const worktreeHealth = detectWorktreeHealth(cwd)
   const buildEnv = detectBuildEnv(cwd)
   const mcpEndpoints = detectMcpEndpoints(cwd)
-  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain, lifecycleDoc, worktreeHealth, buildEnv, mcpEndpoints];
+  // task-03（2026-09-14-apply-conflict-hardening）：apply-manifest 漂移（advisory，
+  // 扫描面走权威 specDir 定位链，git/文件内容比对走 cwd 主仓面）
+  const applyManifestDrift = detectApplyManifestDrift(cwd, authoritySpecDir)
+  // task-02（2026-09-15-tax-governance）：自维护税面（活跃 tally 列示 + 台账聚合 + 税重阈值，只读）
+  const selfMaintenanceTax = detectSelfMaintenanceTax(cwd, authoritySpecDir)
+  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain, lifecycleDoc, worktreeHealth, buildEnv, mcpEndpoints, applyManifestDrift, selfMaintenanceTax];
 
   return {
     dimensions,

package/src/friction-ledger.js

@@ -0,0 +1,171 @@
+/**
+ * friction-ledger.js — 摩擦幸存台账数据层（2026-09-15-tax-governance 方案 B / FR-02）
+ *
+ * 定位：摩擦历史此前「归档即失忆」——friction tally 在 verify 收尾被 consumeFrictionHint
+ * 删除（计数清零），归档时 prune 只见残余，无任何幸存记录，「哪个变更税重」全凭回忆。
+ * 本模块把 consume 到的 counts 按 change 滚动合并进 <runtimeRoot>/friction-ledger.json
+ * （JSON 数组，D-001@v2），doctor 的 self_maintenance_tax 维度据此做聚合展示与阈值提示。
+ *
+ * 两个滚动点（design.md 方案 B，Grill P1-1 修订）：
+ *   - 主滚动：complete.js 两处 verify 收尾（consumeFrictionHint 返回 counts 后）走
+ *     mergeFrictionEntry（withFileLock + writeAtomicSync 读改写，锁先例 friction-tally.js:180-193）
+ *   - 兜底滚动：complete-handlers.js pruneArchivedChangeRuntime 删 tally 前读残余
+ *     events[type].count 走 mergeFrictionEntrySync 并落 archivedAt——prune 是同步契约
+ *     （既有 {ok, removed} 消费方与测试直调），拿不了 async 锁；无锁读改写的并发丢失
+ *     风险按 design R-02 P3 容忍（writeAtomicSync 保证无半截文件，坏文件按空数组起）。
+ *
+ * merge-by-change（Grill P1-1 核心）：同 change 已有条目按类型累加合并非双计——verify 可
+ * --reopen 重跑，二次 consume 的 counts 累进同一条目；archivedAt 仅 prune 侧落定，主滚动
+ * 不落、已有值不冲掉。条目结构（design 接口定义）：
+ *   { change: string, archivedAt?: string, counts: { gate_rollback, verify_run_failed,
+ *     review_rejected }, total: number }
+ * 台账 ≤200 条掐头留最新（rollLedger——防病态体量，不承载完整审计）；被 merge 的既有条目
+ * 挪到尾部（最近活跃者优先幸存掐头）。
+ *
+ * 落点红线（同 friction-tally D-002/R-04）：台账只落 .runtime 树内（本模块只接收
+ * runtimeRoot，调用方经 run/shared.js resolveRuntimeRoot 同源解析——X-08 平台模式防分裂），
+ * **永不落 changes/**。
+ *
+ * fail-soft 红线（design）：台账是旁路数据，写失败绝不阻断任何收尾/归档——全程 try/catch
+ * 返回 { ok:false } 不抛；文件缺失/坏 JSON 按空数组起（全量重启为容忍立场，D-001@v2）。
+ * 本模块自身不打印任何输出。
+ */
+import { readFileSync, mkdirSync } from 'fs'
+import { dirname, join } from 'path'
+import { writeAtomicSync } from './fs-atomic.js'
+import { withFileLock } from './quicklog.js'
+
+/** 摩擦事件三类型（与 friction-tally.js FRICTION_TYPES 同枚举；固定序即 counts 键序） */
+const FRICTION_TYPES = ['gate_rollback', 'verify_run_failed', 'review_rejected']
+
+/** 台账条目上限：超出掐头（最旧）留最新 200 条 */
+const LEDGER_CAP = 200
+
+/** 台账文件名（runtimeRoot 下单文件，JSON 数组） */
+const LEDGER_FILENAME = 'friction-ledger.json'
+
+function ledgerFilePath(runtimeRoot) {
+  return join(runtimeRoot, LEDGER_FILENAME)
+}
+
+/**
+ * 读台账。文件不存在 / 坏 JSON / 非数组 → []（容忍立场：全量重启重新累计，不修复不报错，
+ * 同 readFrictionTally）。仅过滤无 change 键的脏条目，其余原样返回（total/counts 由 merge
+ * 侧重算，doctor 侧读取时数值兜底）。
+ * @param {string} runtimeRoot .runtime 根目录
+ * @returns {Array<{change: string, archivedAt?: string, counts: object, total: number}>}
+ */
+export function readFrictionLedger(runtimeRoot) {
+  try {
+    const raw = JSON.parse(readFileSync(ledgerFilePath(runtimeRoot), 'utf8'))
+    if (!Array.isArray(raw)) return []
+    return raw.filter((e) => e && typeof e === 'object' && !Array.isArray(e) && typeof e.change === 'string' && e.change !== '')
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 掐头留下最新：超过 LEDGER_CAP 条时丢最旧（数组头部），保尾部（最新 append / 最近 merge
+ * 挪尾）。纯函数。
+ */
+export function rollLedger(entries) {
+  if (!Array.isArray(entries)) return []
+  return entries.length > LEDGER_CAP ? entries.slice(entries.length - LEDGER_CAP) : entries
+}
+
+/** counts 入参清洗：只收三枚举类型且为有限正数（consumeFrictionHint 只回非零键，容忍宽松输入） */
+function sanitizeDelta(counts) {
+  const delta = {}
+  if (!counts || typeof counts !== 'object') return delta
+  for (const type of FRICTION_TYPES) {
+    const n = Number(counts[type])
+    if (Number.isFinite(n) && n > 0) delta[type] = n
+  }
+  return delta
+}
+
+/** 条目 counts 三键定形（缺失/脏型按 0），total 重算 */
+function shapeEntry(change, counts, archivedAt) {
+  const shaped = {
+    change,
+    counts: {
+      gate_rollback: counts.gate_rollback || 0,
+      verify_run_failed: counts.verify_run_failed || 0,
+      review_rejected: counts.review_rejected || 0,
+    },
+  }
+  shaped.total = shaped.counts.gate_rollback + shaped.counts.verify_run_failed + shaped.counts.review_rejected
+  if (archivedAt) shaped.archivedAt = archivedAt
+  return shaped
+}
+
+/**
+ * merge-by-change 纯核心：同 change 已有条目按类型累加（total 重算）非双计，新 change
+ * append；archivedAt 有值时落定、无值时保留既有（主滚动不冲掉 prune 已落的归档时间）；
+ * 被 merge 的既有条目挪到数组尾部（最近活跃者优先幸存掐头）。返回新数组，不改入参。
+ */
+function applyMergeEntry(entries, { change, counts, archivedAt }) {
+  const delta = sanitizeDelta(counts)
+  const idx = entries.findIndex((e) => e.change === change)
+  if (idx === -1) return [...entries, shapeEntry(change, delta, archivedAt)]
+  const prev = entries[idx]
+  const mergedCounts = {}
+  for (const type of FRICTION_TYPES) {
+    const p = Number(prev.counts && prev.counts[type])
+    mergedCounts[type] = (Number.isFinite(p) ? p : 0) + (delta[type] || 0)
+  }
+  const keepArchivedAt = archivedAt || (typeof prev.archivedAt === 'string' && prev.archivedAt ? prev.archivedAt : null)
+  return [...entries.slice(0, idx), ...entries.slice(idx + 1), shapeEntry(change, mergedCounts, keepArchivedAt)]
+}
+
+/**
+ * 同步滚动一条台账（读 → merge-by-change → 掐头 → writeAtomicSync 落盘），供同步契约调用
+ * 方（pruneArchivedChangeRuntime）使用；async 主入口 mergeFrictionEntry 的锁内临界区也是
+ * 本函数（单一实现，锁只是外壳）。
+ *
+ * 空 counts（三键任一都非正）跳过写盘——干净收尾/零残余归档不落空文件（FR-02 验收）。
+ * fail-soft：任何异常（只读目录/路径非法/坏 JSON）吞掉返回 { ok:false } 绝不抛。
+ * @param {string} runtimeRoot .runtime 根目录
+ * @param {{ change: string, counts?: object, archivedAt?: string }} entry
+ * @returns {{ ok: boolean, skipped?: boolean, entry?: object }}
+ *   成功 { ok:true, skipped:false, entry }；空 delta 跳过 { ok:true, skipped:true }；失败 { ok:false }
+ */
+export function mergeFrictionEntrySync(runtimeRoot, entry) {
+  try {
+    if (!runtimeRoot || typeof runtimeRoot !== 'string') return { ok: false, skipped: true }
+    const change = entry && typeof entry.change === 'string' ? entry.change : ''
+    if (!change) return { ok: false, skipped: true }
+    if (Object.keys(sanitizeDelta(entry.counts)).length === 0) return { ok: true, skipped: true }
+    const merged = applyMergeEntry(readFrictionLedger(runtimeRoot), {
+      change,
+      counts: entry.counts,
+      archivedAt: typeof entry.archivedAt === 'string' && entry.archivedAt ? entry.archivedAt : null,
+    })
+    const rolled = rollLedger(merged)
+    const path = ledgerFilePath(runtimeRoot)
+    mkdirSync(dirname(path), { recursive: true })
+    writeAtomicSync(path, JSON.stringify(rolled, null, 2))
+    return { ok: true, skipped: false, entry: rolled[rolled.length - 1] }
+  } catch {
+    return { ok: false }
+  }
+}
+
+/**
+ * 台账滚动主入口（complete.js 两处 verify 收尾 consume 后调用）：withFileLock 串行化
+ * 读改写（锁先例 friction-tally.js:180-193——台账会被收尾/归档进程并发读改，无锁交错
+ * 丢更新；坏文件/写失败仍按空数组起 / fail-soft）。锁内即 mergeFrictionEntrySync。
+ * @param {string} runtimeRoot .runtime 根目录（调用方 resolveRuntimeRoot 同源解析）
+ * @param {{ change: string, counts?: object, archivedAt?: string }} entry
+ * @returns {Promise<{ ok: boolean, skipped?: boolean, entry?: object }>} 失败 { ok:false } 不抛
+ */
+export async function mergeFrictionEntry(runtimeRoot, entry) {
+  try {
+    if (!runtimeRoot || typeof runtimeRoot !== 'string') return { ok: false, skipped: true }
+    const path = ledgerFilePath(runtimeRoot)
+    return await withFileLock(path + '.lock', () => mergeFrictionEntrySync(runtimeRoot, entry))
+  } catch {
+    return { ok: false }
+  }
+}

package/src/hooks/worktree-guard.js

@@ -203,6 +203,14 @@ function shouldBlockScanDocOverwrite(filePath, projectRoot) {
   const guard = readScanGuard(scanDocInfo, projectRoot)
   if (!guard || guard.forceRescan) return { blocked: false }
 
+  // 增量刷新会话态前置分支（2026-09-14-scan-incremental-refresh D-007@v1）：refresh ①拍写入
+  // mode='scan-refresh' + refreshDocs 白名单——白名单内=本次刷新工单面，agent 手术编辑放行；
+  // 白名单外的 scan 文档继续走原保护（非本次刷新面不放松）。存量 guard（无 mode 字段）不受影响。
+  if (guard.mode === 'scan-refresh' && Array.isArray(guard.refreshDocs)) {
+    const refreshRel = toPosixPath(path.relative(scanDocInfo.specRoot, filePath))
+    if (guard.refreshDocs.includes(refreshRel)) return { blocked: false }
+  }
+
   let frontmatter = {}
   try {
     frontmatter = parseFrontmatter(readFileSync(filePath, 'utf8'))
@@ -211,7 +219,11 @@ function shouldBlockScanDocOverwrite(filePath, projectRoot) {
   }
 
   const relPath = toPosixPath(path.relative(projectRoot, filePath))
-  if (frontmatter.source_commit && guard.sourceCommit && frontmatter.source_commit !== guard.sourceCommit) {
+  // 归一化比对（D-007@v1 顺带修复）：guard 写入方用 40 位全哈希（run/stage.js rev-parse HEAD）、
+  // frontmatter 盖章用 7 位短哈希（scan-postcheck.js --short）——旧精确比对恒不等，guard 存在
+  // 即恒拦。两侧截 7 位后恢复「同基线放行 / 异基线拦截」设计本意。
+  if (frontmatter.source_commit && guard.sourceCommit
+    && String(frontmatter.source_commit).slice(0, 7) !== String(guard.sourceCommit).slice(0, 7)) {
     return {
       blocked: true,
       reason: [