agentic-flow-kit 1.8.7 → 2.0.0

package/templates/engine/.agents/scripts/quote-grounding.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// quote-grounding — --delegated 引文接地校验（2026-10-22 delegated-quote-grounding）
+//
+// 为什么需要：`--delegated "<用户原话>"` 是免 TTY 的委托代录形态，quote 是**事后对质的唯一证据**。
+// 但历史台账暴露该证据可空洞化——quote 与目标文档毫无指涉关系（如代录 spec 却记「提交并关单」，
+// 或把 A 件的话记到 B 件头上），此时「用户确认过这份文档」无法被证伪，确认门退化成 AI 自证。
+//
+// 判据（三层，任一成立即接地）：
+//   ① 逐字命中：规范化后 quote 整体是目标文档（含同名家族）的子串；
+//   ② 逐字锚点：与目标文档的最长逐字公共片段 ≥ GROUND_ANCHOR_MIN（默认 8 字）——
+//      足以证明 quote 谈的是这份文档的具体内容，而不是「随便哪件都能说」的话；
+//   ③ 纯放行语：剥掉 RELEASE_LEXICON（放行/工序/收尾通用词）后残余 ≤ RESIDUAL_TOLERANCE
+//      （默认 2）——quote 不含可被误配的具体内容，无从「伪造指向」，放行不损失证据力。
+// 三层都不成立 → 残余内容在目标文档里找不到落点 = 引文说的不是这份文档，判为**不接地**
+// （默认 advisory 放行并留痕；`--strict-quote` 才拒绝落账——见下方实测取舍）。
+//
+// 实测（2026-10-22，temp/probe26–29 回放 873 行历史委托）——**为什么默认只 WARN 不硬拦**：
+//   K=8：真文档通过 90.0%，但同一引文对**无关文档**也通过 71.2%（判别力仅 19pt）；
+//        且 L2/L3 误杀 17.9%、L1 误杀 8.2%。
+//   K=4：误杀降到 3.4%，但无关文档通过率 91.2% —— 几乎零判别力。
+//   结论：中文口语是**复述**而非引用（「多条MTO单明细手动代用…定额记录」这类真原话对不上任何
+//   8 字逐字串），词面判据无法在「误杀合规口语」与「放过误配」之间同时成立。故：
+//     · 默认 advisory（WARN + 台账行记 quoteGrounding，供事后审计与趋势）；
+//     · 客观缺陷才硬拦：quote 空、目标文档在活跃目录与归档里都不存在；
+//     · 需要收硬时由调用方显式 `--strict-quote`（策略选择，不是默认）。
+//   换言之：**能机器证伪的只有「quote 是不是空/指向不存在的文档」；「quote 是否真的授权了这份文档」
+//   机器证不了**——那半边靠 review/design/test 的强制独立复核兜。
+//
+// 设计取舍（刻意不做的事）：
+// - **不做模糊相似度**（n-gram 覆盖率 / token 比例 / LCS 长度比）：历史 873 条委托行的实测
+//   （tmp/probe19–24）显示这类判据在中文短句上要么放过几乎全部误配，要么误杀大量合规短句，
+//   单独使用只提供「跑过了」的错觉。逐字锚点是唯一可对质的证据形态。
+// - **不做跨文档反查**（「残余命中他件即判误配」）：同名家族外的命中无法区分「用户顺口提了邻件」
+//   与「真的记串了」，误报代价高于收益。
+// - **不回溯历史行**：本校验只在写入时把关；存量 quote 一字不改（check-loop 不据此追责）。
+//
+// 家族范围：同名 intent/spec/plan/incident 整族，且**跨 workflow/archive/** 解析——归档不是失效
+// （spec 生命周期口径 2026-10-16），实测 208 条「目标文档不存在」的委托行里 205 条只是被归档改名。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// 最长逐字锚点下限（规范化后字符数）。取 8：中文里 8 字连续逐字相同，偶然重合概率可忽略，
+// 同时容得下「确认第三点库存扣减口径」这类短指涉。
+export const GROUND_ANCHOR_MIN = 8;
+
+// 残余容忍（剥通用词后仍剩下的字符数上限）。只为吸收「即 / 就 / 的」这类残留语气字，
+// 不作为放宽闸口——真正的门槛是「残余必须能在文档里找到落点」。
+export const RESIDUAL_TOLERANCE = 2;
+
+
+// 通用放行 / 工序 / 收尾词表：这些词在仓库任何一份 workflow 文档里都可能出现，不构成指涉。
+// 按**最长优先**匹配剥除（「提交并关单」先于「提交」「关单」）。
+export const RELEASE_LEXICON = [
+  // 放行本身
+  '可以可以', '可以', '好', '行', '没问题', '没意见', '同意', '通过', '放行', '准了',
+  '可', '好的', '行吧', '就', '即', '那就', '那么', '这', '那', '这么', '你要',
+  '确认', '已确认', '确定', '批准', '认可', '继续', '接着', '往下', '开干', '干活', '动手',
+  '进入', '动工', '开工', '开始',
+  // 提交 / 收尾 / 分支 / 合入
+  '提交并关单', '提交并', '提交', '推送', '合入', '合并', '收尾', '关单', '落态', '记账', '记一笔',
+  '上推', '推上去', '分支', '主干', '远程', '到',
+  '不要推送', '不推送', '不用推送', '不用合并', '不要合并', '不合并', '不必合并',
+  '不要提交', '不用提交', '不必',
+  // 验证 / 工序
+  '测试', '自测', '实测', '复测', '全量', '门禁', '门', '静态', '验证', '校验', '检查',
+  '验收', '证据', '对照', '回归', '冒烟', '绿', '红',
+  '由我自己测试', '由我测试', '我自己测', '自己测', '我来测', '我测', '由我',
+  '去除', '去掉', '移除', '删掉', '删',
+  // 指代文档 / 工作物
+  '文档', '文件', '代码', '改动', '变更', '修改', '问题', '需求', '方案', '页面', '功能',
+  '事项', '任务', '内容', '清单', '记录', '台账', '结论', '笔记', '小节', '章节',
+  '阶段', '流程', '确认后', '放行后', '同源同批',
+  // 文档类型名（用户说「plan 确认」时不构成对具体某一份的指涉）
+  'plan', 'spec', 'intent', 'incident', 'design', 'build', 'review', 'test', 'deploy',
+  // 时间 / 顺序 / 数量
+  '现在', '马上', '立即', '直接', '顺便', '一起', '然后', '之后', '先', '再', '按', '照',
+  '第一', '第二', '第三', '第四', '点', '步', '共', '全部', '所有', '都', '也', '并',
+  '一份', '两份', '三份', '两件', '三处', '两处', '一次', '两次',
+  '完毕', '完成', '做完', '改完', '修完', '补充', '补齐', '落地', '处理', '修', '补', '改',
+  '走', '跑', '执行', '照做', '照此', '依旧', '按此',
+  // 结构助词 / 语气
+  '的话', '了', '吧', '呀', '啊', '嗯', '对', '是', '要', '想', '请', '帮我', '帮忙',
+  '们', '我们', '你', '我', '他', '其',
+];
+
+// normalizeQuote(s)：小写 + 去空白 + 去中英标点/引号/括号（保留字母数字汉字）。
+// 不做同义/繁简/拼音归一——归一越狠，锚点越容易被「看起来像」骗过。
+export function normalizeQuote(s) {
+  return String(s ?? '')
+    .toLowerCase()
+    .replace(/[\s\u3000]+/g, '')
+    .replace(/[!-/:-@[-`{-~\u2000-\u206f\u3001-\u303f\uff01-\uff0f\uff1a-\uff20\uff3b-\uff40\uff5b-\uff65]/g, '');
+}
+
+// longestCommonAnchor(a, b)：最长公共**连续**子串长度（规范化入参，O(n*m) 时间 / O(min) 空间）。
+// 引文短（<200 字）、文档 ~40KB，单次确认一份文档，成本可忽略；取滚动一维 DP 避免二维分配。
+export function longestCommonAnchor(a, b) {
+  const s = String(a ?? '');
+  const t = String(b ?? '');
+  if (!s || !t) return 0;
+  const n = s.length;
+  let prev = new Uint32Array(n + 1);
+  let cur = new Uint32Array(n + 1);
+  let best = 0;
+  for (let j = 1; j <= t.length; j++) {
+    const tc = t.charCodeAt(j - 1);
+    for (let i = 1; i <= n; i++) {
+      if (s.charCodeAt(i - 1) === tc) {
+        const v = prev[i - 1] + 1;
+        cur[i] = v;
+        if (v > best) best = v;
+      } else {
+        cur[i] = 0;
+      }
+    }
+    const tmp = prev; prev = cur; cur = tmp;
+    cur.fill(0);
+  }
+  return best;
+}
+
+// hasAnchorAtLeast(q, hay, k)：q 的任一 k-gram 是否出现在 hay 里（等价于「最长逐字锚点 ≥ k」，
+// 但用原生 indexOf 判存在、不建二维表）。等价性：长度 ≥k 的公共连续片段必含一个 q 的 k-gram。
+export function hasAnchorAtLeast(q, hay, k) {
+  if (k <= 0 || !q || !hay) return false;
+  for (let i = 0; i + k <= q.length; i++) {
+    if (hay.includes(q.slice(i, i + k))) return true;
+  }
+  return false;
+}
+
+// stripRelease(q)：按最长优先把 RELEASE_LEXICON 从规范化引文里剥掉，返回残余（已归一）。
+export function stripRelease(normalized) {
+  const sorted = [...RELEASE_LEXICON].sort((x, y) => y.length - x.length);
+  let out = String(normalized ?? '');
+  for (const w of sorted) {
+    if (!w) continue;
+    const nw = normalizeQuote(w);
+    if (nw) out = out.split(nw).join('');
+  }
+  // 剥完剩下的编号（「第 1 点」/「方案 2」/「①-③」）不构成指涉
+  return out.replace(/[0-9]+/g, '').replace(/[\u2460-\u2473\u2474-\u2487]/g, '');
+}
+
+// groundQuote({quote, docText, familyTexts})：接地裁决（纯函数，无 IO）。
+// 返回 { ok, reason: 'empty'|'verbatim'|'anchor'|'generic'|'ungrounded', anchor, residual }。
+// reason 供调用方给出可执行的拒绝提示（不只是一个 false）。
+export function groundQuote({ quote, docText, familyTexts = [] } = {}) {
+  const q = normalizeQuote(quote);
+  if (!q) return { ok: false, reason: 'empty', anchor: 0, residual: '' };
+
+  const haystacks = [normalizeQuote(docText), ...familyTexts.map((t) => normalizeQuote(t))]
+    .filter(Boolean);
+
+  // ① 逐字命中
+  for (const hay of haystacks) {
+    if (hay.includes(q)) return { ok: true, reason: 'verbatim', anchor: q.length, residual: '' };
+  }
+
+  // ② 最长逐字锚点（先判存在，命中即止；未命中才在失败路径精确算长度供诊断）
+  if (haystacks.some((hay) => hasAnchorAtLeast(q, hay, GROUND_ANCHOR_MIN))) {
+    return { ok: true, reason: 'anchor', anchor: GROUND_ANCHOR_MIN, residual: '' };
+  }
+  let anchor = 0;
+  for (const hay of haystacks) {
+    const len = longestCommonAnchor(q, hay);
+    if (len > anchor) anchor = len;
+  }
+
+  // ③ 纯放行语
+  const residual = stripRelease(q);
+  if (residual.length <= RESIDUAL_TOLERANCE) {
+    return { ok: true, reason: 'generic', anchor, residual };
+  }
+
+  return { ok: false, reason: 'ungrounded', anchor, residual };
+}
+
+// resolveDocText(root, doc)：目标文档正文；活跃路径缺失时回落到同名归档件。
+// 返回 { text, archived } 或 null。归档回落是关键：208 条「目标文档不存在」的委托行里
+// 205 条只是被 archive-on-close 归档改名，按「缺档」处理会误杀合规历史。
+export function resolveDocText(root, doc) {
+  const relDoc = String(doc || '').replace(/\\/g, '/');
+  try {
+    return { text: fs.readFileSync(path.join(root, relDoc), 'utf8'), archived: false };
+  } catch {
+    const base = path.basename(relDoc, '.md');
+    if (!base) return null;
+    const archiveRoot = path.join(root, 'workflow', 'archive');
+    let batches = [];
+    try { batches = fs.readdirSync(archiveRoot, { withFileTypes: true }); } catch { return null; }
+    for (const b of batches.filter((x) => x.isDirectory())) {
+      for (const t of ['intents', 'specs', 'plans', 'incidents']) {
+        try {
+          const p = path.join(archiveRoot, b.name, t, `${base}.md`);
+          return { text: fs.readFileSync(p, 'utf8'), archived: true };
+        } catch { /* 继续找 */ }
+      }
+    }
+    return null;
+  }
+}
+
+// resolveFamilyTexts(root, doc)：读同名家族正文（四类型 + 全归档批次），排除目标文档自身。
+// 只读、缺失容忍。家族=同一主题的 intent/spec/plan/incident，引文指向族内任一都是「同一件事」。
+export function resolveFamilyTexts(root, doc) {
+  const base = path.basename(String(doc || ''), '.md');
+  if (!base) return [];
+  const relDoc = String(doc || '').replace(/\\/g, '/');
+  const out = [];
+  const seen = new Set();
+
+  const push = (abs) => {
+    const rel = path.relative(root, abs).replace(/\\/g, '/');
+    if (rel === relDoc || seen.has(rel)) return;
+    seen.add(rel);
+    try { out.push(fs.readFileSync(abs, 'utf8')); } catch { /* 缺失容忍 */ }
+  };
+
+  for (const t of ['intents', 'specs', 'plans', 'incidents']) {
+    push(path.join(root, 'workflow', t, `${base}.md`));
+  }
+  const archiveRoot = path.join(root, 'workflow', 'archive');
+  let batches = [];
+  try { batches = fs.readdirSync(archiveRoot, { withFileTypes: true }); } catch { return out; }
+  for (const b of batches.filter((x) => x.isDirectory())) {
+    for (const t of ['intents', 'specs', 'plans', 'incidents']) {
+      push(path.join(archiveRoot, b.name, t, `${base}.md`));
+    }
+  }
+  return out;
+}

package/templates/engine/.agents/scripts/regen-ledgers.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// regen-ledgers.mjs — 工作流台账一键重生成（2026-10-20 消「每合并必冲突」配套件）
+//
+// 背景：workflow/INDEX.md、metrics.md、verify-evidence.md、delegations.md 是每个任务必写的
+// 共享计数器/生成物，两条并行分支各自推进后合并必在计数行撞车（结构性，非偶然）。2026-10-20 起
+// .gitattributes 为四文件配了合并策略：三个生成物 merge=ours（保留本侧），delegations.md
+// 行级并集（手工行纯追加）——合并后跑本脚本即可把四件重生成出含两侧事实的正确版本。
+//
+// 用法：
+//   node .agents/scripts/regen-ledgers.mjs            # 四件全量重生成（合并 develop / 解台账冲突后跑）
+//   node .agents/scripts/regen-ledgers.mjs --check    # 仅校验各生成器 --check/--dry-run 口径（支持者跑，不支持者跳过）
+//
+// 真值源不在本脚本：INDEX ← workflow 文档树；metrics ← 各 done 文档与台账；
+// verify-evidence ← .agents/verifications.jsonl（合并侧经 jsonl-union 已含两侧绿凭证）；
+// delegations 快照 ← 手工行区。因此「任取一侧 + 重生成」恒等于两侧并集的正确版本。
+// stale 兜底：INDEX/metrics 漂移会被 verify 的 wiki 三方一致性 / 台账不变量门拦下（实证 2026-10-20）。
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// 重生成步骤（单源：本函数被 CLI 与测试共用）
+export function buildSteps() {
+  return [
+    { name: 'workflow/INDEX.md', args: ['.agents/scripts/gen-workflow-index.mjs'] },
+    { name: 'workflow/metrics.md', args: ['.agents/scripts/gen-workflow-metrics.mjs'] },
+    { name: 'workflow/verify-evidence.md', args: ['.agents/scripts/gen-verify-evidence.mjs'] },
+    { name: 'workflow/delegations.md 月度快照', args: ['.agents/scripts/agg-delegations.mjs', '--write'] },
+  ];
+}
+
+// 步骤执行（spawn 注入缝：测试用假 spawn 记录调用，CLI 用真 spawnSync）
+export function runSteps(steps, spawnFn = spawnSync, nodeBin = process.execPath) {
+  const results = [];
+  for (const step of steps) {
+    const r = spawnFn(nodeBin, step.args, { cwd: ROOT, stdio: 'inherit' });
+    const ok = r.status === 0;
+    results.push({ ...step, ok });
+    console.log(`${ok ? '✅' : '❌'} ${step.name}${ok ? '' : `（exit ${r.status}）`}`);
+    if (!ok) break; // fail-fast：下游台账可能依赖上游产物
+  }
+  return results;
+}
+
+function main() {
+  const results = runSteps(buildSteps());
+  const failed = results.filter((r) => !r.ok);
+  if (failed.length > 0) {
+    console.error(`\n[regen-ledgers] ${failed.length}/${results.length} 步失败——先修上游再重跑`);
+    process.exit(1);
+  }
+  console.log('\n[regen-ledgers] 四台账已重生成（含两侧事实）。建议随后跑 node .agents/scripts/verify.mjs 复核。');
+}
+
+if (process.argv[1] && process.argv[1].endsWith('regen-ledgers.mjs')) {
+  main();
+}

package/templates/engine/.agents/scripts/rewrite-file.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// rewrite-file.mjs — 按行字面替换 + 响亮失败（silent-noop-loud-failure）
+// 背景（workflow/papercuts.md 2026-10-06 行，两次假落账实证）：
+//   `node -e "fs.writeFileSync(p, s.replace(A, B))"` 对 **CRLF 检出文件**用 `\n` 锚串定位时
+//   **静默无操作**，脚本照样打印「落账 OK」——假成功比响亮失败危险得多（台账/文档被以为改了）。
+// 本工具把该形态的三个失效点逐一堵死：
+//   ① 按行处理并保留原行尾（`/\r?\n/` 切分 + 检出 EOL 回写）——不再有「\n 锚串匹配不上 CRLF」这一类
+//   ② 替换数必须与 --expect 相符（默认 1）——0 命中即非零退出，**文件不写**，绝不存在「以为改了」
+//   ③ 写后回读校验（新锚已在、旧锚已零、行数不变、EOL 未变）——全过才打印成功；任一不过即非零退出
+// 另防两类自伤：find === replace（无操作却报成功）与目标文件不存在（fail-loud，不静默建文件）。
+// 原子写：同目录临时文件 + rename——中途崩溃不留半写文件（沿 git-merge-jsonl.mjs / compact-ledgers.mjs 惯例）。
+// 用法：node .agents/scripts/rewrite-file.mjs <文件> --find <字面串> --replace <字面串>
+//         [--expect N] [--allow-multi] [--dry-run] [--root <仓库根>]
+//   ⚠ 仅支持行内等行数替换（2026-11-06 配方回收：增/删行的多行改写本工具行数校验必拦，
+//     直接改用宿主 Edit 工具，勿反复重试）
+//   --expect N    期望命中数（默认 1）；实际 ≠ N → 非零退出且不写盘
+//   --allow-multi 显式声明允许多命中（等价 --expect 的宽松形态：N ≥ 1 即过，用于批量同串替换）
+//   --dry-run     只打印将发生的替换与校验预览，不写盘
+// 测试面已随引擎减重退役（2026-10-28，owner 决策），本脚本现无测试兜底
+// 沿革：2026-10-12 立档（优先级 3：把「静默无操作」改成响亮失败）
+import fs from 'node:fs';
+import path from 'node:path';
+
+const argv = process.argv.slice(2);
+const argOf = (k) => {
+  const i = argv.indexOf(k);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : '';
+};
+const DRY = argv.includes('--dry-run');
+const MULTI = argv.includes('--allow-multi');
+let file = '';
+let find = null;
+let replace = null;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--find') find = argv[++i] ?? null;
+  else if (a === '--replace') replace = argv[++i] ?? null;
+  else if (a === '--expect') { /* 下面统一解析 */ }
+  else if (a === '--root') { /* 仅为与其它脚本口令一致，路径按 cwd 解析 */ i++; }
+  else if (a === '--dry-run' || a === '--allow-multi') { /* 旗标已处理 */ }
+  else if (!a.startsWith('--') && !file) file = a;
+}
+const expectRaw = argOf('--expect');
+
+const USAGE = `用法：node .agents/scripts/rewrite-file.mjs <文件> --find <字面串> --replace <字面串> [--expect N] [--allow-multi] [--dry-run]`;
+const die = (msg) => { console.error(`❌ rewrite-file: ${msg}\n${USAGE}`); process.exit(1); };
+if (argv.includes('--help') || argv.includes('-h')) { console.log(USAGE); process.exit(0); }
+if (!file) die('缺目标文件');
+if (find === null || replace === null) die('--find 与 --replace 必须成对给出');
+if (find === '') die('--find 不能为空串（空串会命中每一行，属误用）');
+if (find === replace) die(`--find 与 --replace 相同（「${find.slice(0, 40)}」）——无操作却会报成功，正是本工具要堵的形态`);
+let expect = 1;
+if (expectRaw !== '') {
+  if (!/^\d+$/.test(expectRaw)) die(`--expect 须为非负整数（现 ${expectRaw}）`);
+  expect = Number(expectRaw);
+}
+if (MULTI && expectRaw !== '') die('--allow-multi 与 --expect 互斥（一个宽松一个严格，同给无法裁决）');
+
+const abs = path.resolve(process.cwd(), file);
+if (!fs.existsSync(abs)) die(`目标文件不存在：${file}（不静默创建新文件——路径写错时应响亮失败）`);
+let raw;
+try { raw = fs.readFileSync(abs, 'utf8'); } catch (err) { die(`读取失败：${file}（${err.message}）`); }
+
+// ---- 按行处理 + EOL 保全 ----
+const crlf = raw.includes('\r\n');
+const eol = crlf ? '\r\n' : '\n';
+const hadTrailingNewline = /\r?\n$/.test(raw);
+const lines = raw.split(/\r?\n/);
+// 末行是「 trailing newline 产生的空串」时不计入可替换行集合（避免把 EOF 空串当一行改）
+const bodyLines = hadTrailingNewline ? lines.slice(0, -1) : lines;
+
+let hits = 0;
+const changedIdx = [];
+const newBody = bodyLines.map((l, i) => {
+  if (!l.includes(find)) return l;
+  const n = l.split(find).length - 1;
+  hits += n;
+  changedIdx.push(i + 1);
+  return l.split(find).join(replace);
+});
+
+if (hits === 0) {
+  console.error(`❌ rewrite-file: 0 命中——未写盘（文件保持原样）`);
+  console.error(`   文件：${file}`);
+  console.error(`   行尾：${crlf ? 'CRLF（仓库 autocrlf 检出态）' : 'LF'}｜总行数：${bodyLines.length}`);
+  console.error(`   锚串（前 80 字符）：${JSON.stringify(find.slice(0, 80))}`);
+  console.error(`   常见成因：① 锚串与文件实际内容不一致（空格/全角/标点）；② 用 \\n 跨行锚串去匹配 CRLF 文件——本工具按行匹配，跨行锚请拆成单行锚或改用 Edit 工具；③ 文件已被前一次改动写过。`);
+  process.exit(1);
+}
+if (MULTI) {
+  if (hits < 1) die('内部不变式违反：hits < 1');
+} else if (hits !== expect) {
+  console.error(`❌ rewrite-file: 命中数 ${hits} ≠ 期望 ${expect}——未写盘（文件保持原样）`);
+  console.error(`   文件：${file}｜命中行号：${changedIdx.join(', ')}`);
+  console.error(`   含义：锚串不是唯一命中——要么目标不唯一（应加 --expect ${hits} 或 --allow-multi 明示），要么文件已被改过。`);
+  process.exit(1);
+}
+
+const out = newBody.join(eol) + (hadTrailingNewline ? eol : '');
+if (newBody.length !== bodyLines.length) die('内部不变式违反：行数发生变化');
+
+if (DRY) {
+  console.log(`[dry-run] ${file}：将替换 ${hits} 处（行 ${changedIdx.join(', ')}），行尾 ${crlf ? 'CRLF' : 'LF'}，未写盘`);
+  process.exit(0);
+}
+
+// ---- 原子写 ----
+const tmp = `${abs}.rewrite-tmp`;
+try {
+  fs.writeFileSync(tmp, out, 'utf8');
+  fs.renameSync(tmp, abs);
+} catch (err) {
+  try { fs.unlinkSync(tmp); } catch { /* tmp 可能尚未创建 */ }
+  die(`写入失败：${file}（${err.message}）——原文件应保持原样，请核对后重试`);
+}
+
+// ---- 写后回读校验（③）：任一不过即非零退出，绝不打印成功 ----
+const problems = [];
+let back;
+try { back = fs.readFileSync(abs, 'utf8'); } catch (err) { die(`回读失败：${file}（${err.message}）——写入结果不可验证，请人工核对`); }
+if (back !== out) problems.push('回读内容与拟写内容不一致（写入被截断或并发改动）');
+if (back.includes(find)) problems.push('旧锚串仍存在于回读内容中（替换不完整）');
+if (replace !== '' && !back.includes(replace)) problems.push('新锚串不在回读内容中');
+const backLines = back.split(/\r?\n/);
+const backBody = hadTrailingNewline ? backLines.slice(0, -1) : backLines;
+if (backBody.length !== bodyLines.length) problems.push(`行数变化：${bodyLines.length} → ${backBody.length}`);
+if (back.includes('\r\n') !== crlf) problems.push(`行尾形态变化：${crlf ? 'CRLF' : 'LF'} → ${back.includes('\r\n') ? 'CRLF' : 'LF'}`);
+if (problems.length) {
+  console.error(`❌ rewrite-file: 写后回读校验未过——${file}`);
+  problems.forEach((p) => console.error(`   - ${p}`));
+  console.error('   现场已保留（不要手改），请核对后用 git 恢复或重新替换');
+  process.exit(1);
+}
+
+console.log(`✅ rewrite-file: ${file} 替换 ${hits} 处（行 ${changedIdx.join(', ')}）｜行尾 ${crlf ? 'CRLF' : 'LF'} 保全｜行数 ${bodyLines.length} 不变｜回读校验通过`);