agentic-flow-kit 1.7.15 → 1.8.0

package/templates/_agents/scripts/ledger-doc-chain.test.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// ledger-doc-chain.test.mjs — 台账哈希链「链域改造」fixture 套件（2026-10-12 ledger-doc-chain）
+// 核心命题：把链域从「文件物理序」改成「按 doc 的逻辑序」，在**不削弱篡改检出**的前提下让三种
+// 正常协作（并发 append / git 并集合并 / 分片归并）不再撞 hard 门。
+// 覆盖面：锚缺键=旧行为 / 锚前行维持物理链 / 锚后行按 doc 链 / 跨域衔接 / 三类篡改仍被抓 /
+//         写入侧与校验侧口径一致（双方单源函数同源）。
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const { ledgerChainHash, ledgerDocChainActive, ledgerDocChainPrev } =
+  await import(pathToFileURL(path.join(SCRIPT_DIR, 'policy.mjs')).href);
+
+let pass = 0, fail = 0;
+const check = (name, ok, detail = '') => {
+  if (ok) { pass++; console.log(`  ok  ${name}`); }
+  else { fail++; console.error(`FAIL  ${name}${detail ? ' — ' + detail : ''}`); }
+};
+
+const ANCHOR = '2026-10-12T07:20:00Z';
+const OLD = '2026-10-01T00:00:00Z';   // 锚前（旧物理链口径）
+const NEW = '2026-10-13T00:00:00Z';   // 锚后（新 doc 链口径）
+
+// mkRow：造一条链行（prevHash 由调用方给）
+const mkRow = (ts, doc, stage, prevHash) => {
+  const fields = { ts, doc, stage, fingerprint: 'f'.repeat(64), source: 'tty' };
+  return { ...fields, prevHash, hash: ledgerChainHash(fields, prevHash) };
+};
+
+// ---- 校验侧判据的可执行镜像（必须与 check-loop.mjs 检查 15 同判据；此处用于单测，生产判据在 check-loop）----
+function verifyChain(rows, policy) {
+  const on = ledgerDocChainActive(policy);
+  const since = on ? policy.ledgerDocChainSince : '';
+  let prevHash = '', brokenAt = 0, brokenCount = 0;
+  const byDoc = new Map();
+  rows.forEach((row, idx) => {
+    if (!row || typeof row.hash !== 'string') { prevHash = ''; return; }
+    const { hash, prevHash: p, ...rest } = row;
+    const inDoc = on && typeof row.ts === 'string' && row.ts >= since;
+    const expected = inDoc ? (byDoc.get(row.doc) ?? '') : prevHash;
+    const ok = (p ?? '') === expected && ledgerChainHash(rest, p ?? '') === hash;
+    if (!ok) { if (!brokenAt) brokenAt = idx + 1; brokenCount++; }
+    prevHash = hash;
+    if (typeof row.doc === 'string') byDoc.set(row.doc, hash);
+  });
+  return { brokenAt, brokenCount };
+}
+
+// ================= 单元：锚开关 =================
+{
+  check('U1 缺键（v1-v7）→ 新口径不生效', ledgerDocChainActive({}) === false);
+  check('U2 非法锚值 → 不生效（fail-safe 回旧口径）', ledgerDocChainActive({ ledgerDocChainSince: '2026-10-12' }) === false);
+  check('U3 合法 ISO 时刻锚 → 生效', ledgerDocChainActive({ ledgerDocChainSince: ANCHOR }) === true);
+  check('U4 v8 锚值合法', ledgerDocChainActive({ ledgerDocChainSince: ANCHOR }) === true);
+}
+
+// ================= 单元：前驱取法 =================
+{
+  const rA1 = mkRow(OLD, 'a.md', 'approved', '');
+  const rA2 = mkRow(OLD, 'b.md', 'approved', rA1.hash);
+  const rA3 = mkRow(OLD, 'a.md', 'done', rA2.hash);
+  const rows = [rA1, rA2, rA3];
+  check('U5 doc 链前驱取同行末行（非物理末行）', ledgerDocChainPrev(rows, 'a.md') === rA3.hash);
+  check('U6 另一 doc 的前驱独立', ledgerDocChainPrev(rows, 'b.md') === rA2.hash);
+  check('U7 该 doc 无链行 → 链段重启返回空', ledgerDocChainPrev(rows, 'zz.md') === '');
+  check('U8 空表 → 返回空', ledgerDocChainPrev([], 'a.md') === '' && ledgerDocChainPrev(null, 'a.md') === '');
+}
+
+// ================= 关键：缺锚 = 旧行为（存量零变化）=====================
+{
+  const rA1 = mkRow(OLD, 'a.md', 'approved', '');
+  const rA2 = mkRow(OLD, 'b.md', 'approved', rA1.hash);
+  const rA3 = mkRow(OLD, 'a.md', 'done', rA2.hash);
+  // 物理链下这三行是自洽的（旧口径判定）
+  check('K1 缺锚：物理链自洽行不报断（= 存量零新增告警）',
+    verifyChain([rA1, rA2, rA3], {}).brokenCount === 0);
+}
+
+// ================= 关键：锚前行维持物理链 =================
+{
+  const pol = { ledgerDocChainSince: ANCHOR };
+  const rA1 = mkRow(OLD, 'a.md', 'approved', '');
+  const rA2 = mkRow(OLD, 'b.md', 'approved', rA1.hash); // 物理接续（doc 链口径下这行会断）
+  const rA3 = mkRow(OLD, 'a.md', 'done', rA2.hash);
+  check('K2 锚前：物理链接续的三行不误报（存量不受改造影响）',
+    verifyChain([rA1, rA2, rA3], pol).brokenCount === 0, JSON.stringify(verifyChain([rA1, rA2, rA3], pol)));
+}
+
+// ================= 关键：锚后 doc 链 + 跨域衔接 =================
+{
+  const pol = { ledgerDocChainSince: ANCHOR };
+  // 锚前：物理链两行（a 起点、b 接物理）
+  const rA1 = mkRow(OLD, 'a.md', 'approved', '');
+  const rB1 = mkRow(OLD, 'b.md', 'approved', rA1.hash);
+  // 锚后：doc 链接续（a 的新行接 rA1，b 的新行接 rB1——**不是**物理末行 rA1）
+  const rA2 = mkRow(NEW, 'a.md', 'done', rA1.hash);
+  const rB2 = mkRow(NEW, 'b.md', 'done', rB1.hash);
+  check('K3 锚后：doc 链接续自洽（跨域衔接成功）',
+    verifyChain([rA1, rB1, rA2, rB2], pol).brokenCount === 0, JSON.stringify(verifyChain([rA1, rB1, rA2, rB2], pol)));
+  check('K4 锚后 b 的前驱是 b 自己上一行（不是物理末行）',
+    rB2.prevHash === rB1.hash && rB2.prevHash !== rA2.hash);
+}
+
+// ================= 关键：三种正常协作不再误报 =================
+// 注意夹具语义：doc 链下某 doc 的**首个链行 prevHash 恒为 ''**（该 doc 链段重启），第二行才接前一行。
+// 用物理前驱填夹具会造出「本就不该自洽」的样本——那是夹具错，不是判据错（K5/K6/K7 首版即栽在这里）。
+{
+  const pol = { ledgerDocChainSince: ANCHOR };
+  const rA1 = mkRow(NEW, 'a.md', 'approved', '');
+  const rA2 = mkRow(NEW, 'a.md', 'done', rA1.hash);
+  const rB1 = mkRow(NEW, 'b.md', 'approved', '');
+  const rB2 = mkRow(NEW, 'b.md', 'done', rB1.hash);
+  // 协作①：两分支各自追加后并集合并 —— 行序可能被打乱（b 行被挪到 a 行之间）
+  check('K5 协作①并集合并（跨 doc 行序与物理链不同）→ doc 链仍自洽',
+    verifyChain([rA1, rB1, rA2, rB2], pol).brokenCount === 0, JSON.stringify(verifyChain([rA1, rB1, rA2, rB2], pol)));
+  // 协作②：分片归并把别的 doc 的行插进本 doc 链的中段
+  const rC1 = mkRow(NEW, 'c.md', 'approved', '');
+  check('K6 协作②分片归并插行 → doc 链仍自洽',
+    verifyChain([rA1, rC1, rA2, rB1, rB2], pol).brokenCount === 0, JSON.stringify(verifyChain([rA1, rC1, rA2, rB1, rB2], pol)));
+  // 基线：供下方篡改用例复用
+  const base = [rA1, rB1, rA2, rB2];
+  check('K7 基线：四行自洽', verifyChain(base, pol).brokenCount === 0, JSON.stringify(verifyChain(base, pol)));
+
+  // 篡改①：就地改中间行内容（不动其 hash）→ 重算必失配
+  const tampered1 = base.map((r) => (r === rB1 ? { ...r, stage: 'cancelled' } : r));
+  check('K8 篡改①就地改行 → 抓到', verifyChain(tampered1, pol).brokenCount > 0);
+
+  // 篡改②：删该 doc 的**中间行**（a 的首行）→ 其后继行 prevHash 失配。
+  //   诚实边界：**删某 doc 的末行在两种链域下都抓不到**（无后继可比），这是链式防伪的固有上限，
+  //   物理链同样如此；兜底仍是 check-ledger-invariant 的 append-only 历史全扫。
+  const deleted = base.filter((r) => r !== rA1);
+  check('K9 篡改②删中间行 → 抓到', verifyChain(deleted, pol).brokenCount > 0);
+
+  // 篡改③：插一行（自洽重算但前驱为空）→ 后继行前驱失配
+  const fFields = { ts: NEW, doc: 'a.md', stage: 'reverted', fingerprint: 'x'.repeat(64), source: 'tty' };
+  const forged = { ...fFields, prevHash: '', hash: ledgerChainHash(fFields, '') };
+  const inserted = [rA1, forged, rA2, rB1, rB2];
+  check('K10 篡改③插行（自洽重算但前驱为空）→ 抓到', verifyChain(inserted, pol).brokenCount > 0);
+}
+
+// ================= 关键：写入侧与校验侧口径一致 =================
+{
+  // 写入侧取前驱（ledgerDocChainPrev）与校验侧期望（byDoc 末值）必须是同一个值——否则新行一落账即断
+  const rA1 = mkRow(OLD, 'a.md', 'approved', '');
+  const rB1 = mkRow(OLD, 'b.md', 'approved', rA1.hash);
+  const rows = [rA1, rB1];
+  const writeSidePrev = ledgerDocChainPrev(rows, 'a.md');
+  // 校验侧：走一遍同样两行后，byDoc.get('a.md') 应等于写入侧取到的值
+  const byDoc = new Map();
+  for (const row of rows) byDoc.set(row.doc, row.hash);
+  check('K11 写入侧取前驱 == 校验侧期望（两侧单源一致）',
+    writeSidePrev === rA1.hash && byDoc.get('a.md') === writeSidePrev);
+}
+
+// ================= 边界：无 ts 的链行 fail-safe 回旧口径 =================
+{
+  const pol = { ledgerDocChainSince: ANCHOR };
+  const noTs = { doc: 'a.md', stage: 'approved', fingerprint: 'z'.repeat(64), prevHash: '', hash: '' };
+  const fields = { doc: 'a.md', stage: 'approved', fingerprint: 'z'.repeat(64) };
+  noTs.hash = ledgerChainHash(fields, '');
+  check('K12 无 ts 的链行按物理链判定（不因缺 ts 误入新域）',
+    verifyChain([noTs], pol).brokenCount === 0);
+}
+
+console.log(`\n[ledger-doc-chain.test] PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/ledger-loader.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// ledger-loader.mjs — 确认台账读取视图单源（2026-10-12 ledger-loader-p1）
+// 为什么有这个文件：确认台账 `.agents/confirmations.jsonl` 此前有 6 处生产代码各自
+// `readFileSync` + `JSON.parse` 复刻一遍（stage-gates / check-loop ×4 / check-metric-claims /
+// gen-workflow-dashboard / gen-workflow-metrics），口径与容错各写各的。后续引入分片台账
+// （多人 / 多 worktree 并发，见 README 台账并发口径）时，逐处加分支必然漏改——漏一处即
+// 「门禁看不见分片行」＝半盲，且不可见比全红更危险。本文件把**读**收成单源。
+//
+// 本步（Step 1）范围：纯重构，**行为逐字不变**——分片目录不存在时，视图与逐处直读等价。
+// 故意**不做去重**：去重会改 gen-workflow-metrics 的漏斗计数口径（当前计全部行），
+// 属口径变更，须随分片功能同批生效，不得混入本步。
+//
+// 两种视图（消费方需求不同，勿合并）：
+//   readLedgerLines —— 原始文本行，给「按行计数 / 文本特征匹配」用（检查 16 确认负担）。
+//   readLedgerRows  —— 解析后对象数组，坏行跳过，顺序 = 物理读序（主台账先、分片按文件名序）。
+//
+// **不归本文件管的两处（刻意保留直读，改动须先改这里）**：
+//   ① check-loop.mjs 检查 15 哈希链校验——需**物理行号对齐**与**物理顺序**，
+//      任何合并/去重视图都会毁掉它（物理行号 ↔ 数组下标换算依赖逐行原序）。
+//   ② check-ledger-invariant.mjs——校验的是**物理文件本身**的 append-only 前缀不变量，
+//      它审的是盘面字节，不是台账语义。
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const LEDGER_REL = '.agents/confirmations.jsonl';
+export const SHARD_DIR_REL = '.agents/confirmations.d';
+
+// ledgerSources：台账来源清单，顺序即读序——主台账（存量基线）先，分片按文件名序后。
+// 分片视为较新（后读覆盖），与「append-only 台账末次生效」同向。
+// 缺失即跳过（装户无台账 / 未启用分片 = 零影响，向上兼容）。
+export function ledgerSources(root = process.cwd()) {
+  const out = [];
+  const mainAbs = path.join(root, ...LEDGER_REL.split('/'));
+  if (fs.existsSync(mainAbs)) out.push({ rel: LEDGER_REL, abs: mainAbs });
+
+  const shardAbs = path.join(root, ...SHARD_DIR_REL.split('/'));
+  if (fs.existsSync(shardAbs) && fs.statSync(shardAbs).isDirectory()) {
+    let files = [];
+    try {
+      files = fs.readdirSync(shardAbs).filter((f) => f.endsWith('.jsonl')).sort();
+    } catch (err) {
+      // 目录读不出来仍要把已收集的来源交出去——本文件是 hard 门（检查 15）的数据源，
+      // IO 抖动不得伪装成「确认未对账」（fail-closed 会误伤真台账）
+      console.error(`[ledger-loader] 分片目录读取失败: ${SHARD_DIR_REL} (${err.message})——台账视图可能缺该来源`);
+      return out;
+    }
+    for (const f of files) {
+      out.push({ rel: `${SHARD_DIR_REL}/${f}`, abs: path.join(shardAbs, f) });
+    }
+  }
+  return out;
+}
+
+// readLedgerLines：全部来源的非空原始行（保留行内原文，顺序 = 物理读序）。
+export function readLedgerLines(root = process.cwd()) {
+  const lines = [];
+  for (const src of ledgerSources(root)) {
+    let text = '';
+    try {
+      text = fs.readFileSync(src.abs, 'utf8');
+    } catch (err) {
+      // 出账后继续：已读到的来源照常返回，缺的那个来源显式告警（不静默丢）
+      console.error(`[ledger-loader] 读取失败: ${src.rel} (${err.message})——台账视图可能缺该来源`);
+      continue;
+    }
+    for (const line of text.split(/\r?\n/)) {
+      if (line.trim()) lines.push(line);
+    }
+  }
+  return lines;
+}
+
+// readLedgerRows：全部来源解析后的行（坏行跳过，与检查 15 / 19 同容错口径）。
+export function readLedgerRows(root = process.cwd()) {
+  const out = [];
+  for (const line of readLedgerLines(root)) {
+    try {
+      const e = JSON.parse(line);
+      if (e && typeof e === 'object') out.push(e);
+    } catch { /* 坏行跳过 */ }
+  }
+  return out;
+}
+
+// readLedgerEntries：**带来源与行号**的视图，读序 = 主台账在前、分片按文件名序在后。
+//   返回 [{ rel, no, row }]，坏行 row=null（保留占位，否则物理行号会漂移）。
+//   消费方：check-loop 检查 15（链断裂要报「哪个文件的第几行」，跨来源后「物理行号」单一定位已不够，
+//   必须带 rel 才能定位）。此前检查 15 只读主台账故无需本视图——引入分片后改走这里。
+export function readLedgerEntries(root = process.cwd()) {
+  const out = [];
+  for (const src of ledgerSources(root)) {
+    let text = '';
+    try {
+      text = fs.readFileSync(src.abs, 'utf8');
+    } catch (err) {
+      console.error(`[ledger-loader] 读取失败: ${src.rel} (${err.message})——台账视图可能缺该来源`);
+      continue;
+    }
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      if (!lines[i].trim()) continue;
+      let row = null;
+      try { row = JSON.parse(lines[i]); } catch { /* 坏行占位 */ }
+      out.push({ rel: src.rel, no: i + 1, row: (row && typeof row === 'object') ? row : null });
+    }
+  }
+  return out;
+}

package/templates/_agents/scripts/ledger-loader.test.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// ledger-loader.test.mjs — 台账读取视图单源 fixture 套件（2026-10-12 ledger-loader-p1）
+// 覆盖：主台账单源 / 分片并入与读序 / 坏行跳过 / 缺失静默 / IO 失败 fail-soft 出账 /
+//       lines 视图保行内原文 / 两侧视图与旧逐处直读的等价性（Step 1 行为不变的回归护栏）。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+// 兄弟脚本动态载入必须走 file:// URL——win32 绝对路径（'E:\...'）直接 import 会被 ESM loader
+// 判 ERR_UNSUPPORTED_ESM_URL_SCHEME（protocol 'e:'），非 Windows 平台不受影响
+const { ledgerSources, readLedgerLines, readLedgerRows, LEDGER_REL, SHARD_DIR_REL } =
+  await import(pathToFileURL(path.join(SCRIPT_DIR, 'ledger-loader.mjs')).href);
+
+let pass = 0, fail = 0;
+const check = (name, ok, detail = '') => {
+  if (ok) { pass++; console.log(`  ok  ${name}`); }
+  else { fail++; console.error(`FAIL  ${name}${detail ? ' — ' + detail : ''}`); }
+};
+
+const mkRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'ledger-loader-'));
+const w = (root, rel, text) => {
+  const p = path.join(root, ...rel.split('/'));
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, text, 'utf8');
+};
+const row = (o) => JSON.stringify(o);
+
+// ============ 场景 1：无台账（装户/新仓）→ 空视图，不抛 ============
+{
+  const r = mkRoot();
+  check('S1 无台账时 sources 为空', ledgerSources(r).length === 0);
+  check('S1 无台账时 lines 为空', readLedgerLines(r).length === 0);
+  check('S1 无台账时 rows 为空', readLedgerRows(r).length === 0);
+}
+
+// ============ 场景 2：仅主台账 → 与旧逐处直读等价 ============
+{
+  const r = mkRoot();
+  const rows = [
+    row({ ts: '2026-10-01T00:00:00Z', doc: 'workflow/intents/a.md', stage: 'approved', fingerprint: 'a'.repeat(64) }),
+    row({ ts: '2026-10-02T00:00:00Z', doc: 'workflow/intents/a.md', stage: 'done', fingerprint: 'a'.repeat(64) }),
+    row({ ts: '2026-10-03T00:00:00Z', doc: 'workflow/specs/b.md', stage: 'approved', fingerprint: 'b'.repeat(64) }),
+  ];
+  w(r, LEDGER_REL, rows.join('\n') + '\n');
+  const got = readLedgerRows(r);
+  check('S2 rows 数与行数一致', got.length === 3, `实得 ${got.length}`);
+  check('S2 读序 = 物理序（末次 done 在后）',
+    got[1].stage === 'done' && got[2].doc === 'workflow/specs/b.md');
+  // 等价性护栏：旧口径（过滤空行 + JSON.parse + 跳过 null/非对象）
+  const legacy = rows.map((l) => JSON.parse(l));
+  check('S2 与旧逐处直读逐行等价', JSON.stringify(got) === JSON.stringify(legacy));
+  check('S2 lines 视图保留行内原文', readLedgerLines(r).length === 3 && /"stage":"approved"/.test(readLedgerLines(r)[0]));
+}
+
+// ============ 场景 3：坏行跳过（与检查 15/19 同容错口径） ============
+{
+  const r = mkRoot();
+  w(r, LEDGER_REL, [
+    row({ ts: '1', doc: 'workflow/intents/a.md', stage: 'approved' }),
+    '{不是 JSON',
+    '',
+    '   ',
+    row({ ts: '2', doc: 'workflow/intents/b.md', stage: 'approved' }),
+  ].join('\n') + '\n');
+  const got = readLedgerRows(r);
+  check('S3 坏行跳过、空行不计入', got.length === 2, `实得 ${got.length}`);
+  check('S3 坏行后仍继续读到后续行', got[1].doc === 'workflow/intents/b.md');
+  check('S3 lines 视图含坏行原文（计数口径要全量行）', readLedgerLines(r).length === 3, `实得 ${readLedgerLines(r).length}`);
+}
+
+// ============ 场景 4：分片并入——主台账先、分片按文件名序后（分片＝较新） ============
+{
+  const r = mkRoot();
+  w(r, LEDGER_REL, row({ ts: '2026-10-01T00:00:00Z', doc: 'workflow/intents/a.md', stage: 'approved' }) + '\n');
+  w(r, `${SHARD_DIR_REL}/b.jsonl`, row({ ts: '2026-10-05T00:00:00Z', doc: 'workflow/intents/b.md', stage: 'approved' }) + '\n');
+  w(r, `${SHARD_DIR_REL}/a.jsonl`, row({ ts: '2026-10-09T00:00:00Z', doc: 'workflow/intents/c.md', stage: 'approved' }) + '\n');
+  const srcs = ledgerSources(r).map((s) => s.rel);
+  check('S4 来源清单：主台账在最前', srcs[0] === LEDGER_REL, JSON.stringify(srcs));
+  check('S4 来源清单含分片（文件名序 a → b）', srcs.length === 3 && srcs[1] === `${SHARD_DIR_REL}/a.jsonl`, JSON.stringify(srcs));
+  const got = readLedgerRows(r);
+  // 读序 = 主台账 → 分片按**文件名**序：a.jsonl（内含 c.md）先于 b.jsonl
+  check('S4 读序：主台账行在前、分片行按文件名序在后',
+    got[0].doc === 'workflow/intents/a.md' && got[1].doc === 'workflow/intents/c.md' && got[2].doc === 'workflow/intents/b.md',
+    JSON.stringify(got.map((e) => e.doc)));
+  check('S4 分片行可见（末次取值口径：分片较新）',
+    [...got.reduce((m, e) => m.set(e.doc, e.ts), new Map()).values()].length === 3);
+}
+
+// ============ 场景 5：分片目录不存在 / 非目录 → 静默零影响 ============
+{
+  const r = mkRoot();
+  w(r, LEDGER_REL, row({ ts: '1', doc: 'workflow/intents/a.md', stage: 'approved' }) + '\n');
+  w(r, 'not-a-dir.txt', 'x');
+  check('S5 无分片目录时只返回主台账', ledgerSources(r).length === 1);
+  // 分片路径被同名普通文件占位 → 非目录，按不启用处理
+  w(r, SHARD_DIR_REL, '我是文件不是目录');
+  check('S5 分片路径非目录时静默跳过', ledgerSources(r).length === 1 && readLedgerRows(r).length === 1);
+}
+
+// ============ 场景 6：IO 失败 fail-soft —— 已读来源照常返回，缺的来源出账不抛 ============
+{
+  const r = mkRoot();
+  w(r, LEDGER_REL, row({ ts: '1', doc: 'workflow/intents/a.md', stage: 'approved' }) + '\n');
+  // 造一个 existsSync 为真但读取失败的来源：目录形态的 .jsonl（读目录抛 EISDIR）
+  const shardDir = path.join(r, ...SHARD_DIR_REL.split('/'));
+  fs.mkdirSync(shardDir, { recursive: true });
+  fs.mkdirSync(path.join(shardDir, 'boom.jsonl'), { recursive: true }); // 目录而非文件 → readFileSync 抛
+  const origErr = console.error;
+  const errs = [];
+  console.error = (...a) => { errs.push(a.join(' ')); };
+  let got = null;
+  try { got = readLedgerRows(r); } finally { console.error = origErr; }
+  check('S6 读取失败不抛异常', got !== null);
+  check('S6 主台账行仍正常返回', got.length === 1 && got[0].doc === 'workflow/intents/a.md');
+  check('S6 失败来源显式出账（不静默丢行）',
+    errs.some((e) => e.includes('boom.jsonl')), JSON.stringify(errs));
+}
+
+// ============ 场景 7：CRLF 台账 → 行视图不残留 \r（消费方免各自处理） ============
+{
+  const r = mkRoot();
+  w(r, LEDGER_REL, row({ ts: '1', doc: 'workflow/intents/a.md', stage: 'approved' }) + '\r\n');
+  const lines = readLedgerLines(r);
+  check('S7 CRLF 行尾不残留 \\r', lines.length === 1 && !lines[0].endsWith('\r'));
+  check('S7 CRLF 下 rows 仍可解析', readLedgerRows(r).length === 1);
+}
+
+console.log(`\n[ledger-loader.test] PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/ledger-prune.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// ledger-prune.mjs — 台账特许修剪的判据单源（2026-10-12 ledger-prune-manifest）
+// 为什么需要它：确认台账 append-only（README 硬规则 6），历史行禁删改。但现实中存在**合法**的删行场景——
+//   仓库所有者明令删除某批 workflow 文档（归档、误建单清理、GDPR/合规下架）。此时台账里对应的确认行
+//   也必须随之删除，否则行级校验④「doc 在当前树存在」会持续报红，退路只剩「手改台账」→ 直接踩
+//   `--no-verify` 的红线。
+//   在本模块之前，flow-kit 对此**无任何合法出口**——这不是一个「缺个功能」，而是一条会把人逼向绕过的死路。
+//
+// 本模块提供的唯一出口（**特许**，不是豁免）：逐行对账 + 凭据入库。
+//   manifest = .agents/ledger-prune-manifest.json，格式：
+//     { "ts": "<ISO>", "authority": "<授权来源：谁/哪次指令>", "reason": "<为什么删>",
+//       "removes": ["<被删行的 sha256>", ...], "docs": ["<家族名>", ...] }
+//   判据（matchPrune，四条缺一不可）：
+//     ① manifest 存在且 removes 非空；
+//     ② 每个哈希**恰命中一行**（哈希不存在或声明重复都判失败——防「一个哈希对多行」的糊弄）；
+//     ③ 新内容 == 旧内容 − manifest 所列各行（**保序**）——存在 manifest 之外的任何增删改即失败；
+//     ④ 每个被删行的 doc ∈ manifest.docs 清单（空清单 = 不约束）。
+//   凭据（被删行哈希）随 manifest 入 git，事后可对质；manifest 自身是 owned 面，人工审查面。
+//
+// **删行后该 doc 的哈希链会断**：被删行 R1（hash=H1）之后的后继行 R2 带 prevHash=H1，而 R1 已不在表内
+//   → 校验时 byDoc(doc) 为空、R2 的 H1 失配。本模块导出 prunedHashes() 供链校验识别这一**有凭据的链段重启**：
+//   「本行的 prevHash 出现在 manifest.prunedHashes 中」即视为合法重启点，而非篡改。
+//   诚实边界：manifest 是可写文件，**刻意伪造一份 manifest 即可让任意断链合法化**——这与「台账本地可写」
+//   的既有信任边界同级（见 README 确认门诚实边界 / policy.ledgerChainHash）。本模块不宣称通道关闭，
+//   它把「顺手手改台账」抬到「必须提交一份带授权与理由、可被 git 历史对质的凭据」——性质不同，可事后追责。
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+export const PRUNE_REL = '.agents/ledger-prune-manifest.json';
+
+export const sha256line = (l) => createHash('sha256').update(l, 'utf8').digest('hex');
+
+const linesOf = (text) => (text || '').replace(/\r\n/g, '\n').split('\n').filter((l) => l.trim().length > 0);
+
+// loadManifestFromRef：从某个 git 对象引用读 manifest（历史全扫用：该提交树上的 manifest）。
+// 用 spawnSync + status 判定而非 execFileSync：后者失败时 stderr 直通父进程，历史扫描探针在旧提交
+// 尚无 manifest 时会刷屏 fatal 噪声（实测教训）——探测失败必须静默归 null。
+export function loadManifestFromRef(ref, cwd) {
+  try {
+    const r = spawnSync('git', ['show', ref], { cwd, encoding: 'utf8' });
+    if (r.status !== 0) return null;
+    const m = JSON.parse(r.stdout);
+    return (m && typeof m === 'object') ? m : null;
+  } catch {
+    return null;
+  }
+}
+
+// loadManifestFromDisk：读工作树上的 manifest（链校验用；缺文件 = 无修剪凭据，返回 null）。
+export function loadManifestFromDisk(root) {
+  const p = path.join(root, ...PRUNE_REL.split('/'));
+  try {
+    if (!fs.existsSync(p)) return null;
+    const m = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return (m && typeof m === 'object') ? m : null;
+  } catch {
+    return null; // 损坏 = 视同无凭据 → 链断裂照报（fail-closed 于校验面）
+  }
+}
+
+// matchPrune：逐行对账。返回 {removed, docs, hashes} 或 {err}。
+export function matchPrune(headText, curText, manifest) {
+  if (!manifest || !Array.isArray(manifest.removes) || !manifest.removes.length) {
+    return { err: 'manifest 缺失或 removes 为空' };
+  }
+  const head = linesOf(headText);
+  const cur = linesOf(curText);
+  const want = new Set(manifest.removes);
+  const kept = head.filter((l) => !want.has(sha256line(l)));
+  const removedLines = head.filter((l) => want.has(sha256line(l)));
+
+  if (removedLines.length !== manifest.removes.length) {
+    return { err: `manifest 哈希命中 ${removedLines.length} 行 ≠ 声明 ${manifest.removes.length} 行（哈希不存在或声明重复）` };
+  }
+  if (kept.join('\n') !== cur.join('\n')) {
+    return { err: '新内容 ≠ 旧内容 − manifest 所列行（存在 manifest 之外的增删改）' };
+  }
+  const docs = new Set(manifest.docs || []);
+  for (const l of removedLines) {
+    let doc = '';
+    try { doc = JSON.parse(l).doc || ''; } catch { return { err: '被删行非 JSON' }; }
+    if (docs.size && !docs.has(path.basename(doc).replace(/\.md$/, ''))) {
+      return { err: `被删行 doc ${doc} 不在 manifest.docs 清单内` };
+    }
+  }
+  return { removed: removedLines.length, docs: [...docs], hashes: [...want] };
+}
+
+// prunedHashes：工作树 manifest 声明的被删行哈希集合（链校验的合法重启点判定用）。
+export function prunedHashes(root) {
+  const m = loadManifestFromDisk(root);
+  if (!m || !Array.isArray(m.removes)) return new Set();
+  return new Set(m.removes.filter((h) => typeof h === 'string'));
+}

package/templates/_agents/scripts/ledger-prune.test.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// ledger-prune.test.mjs — 台账特许修剪通道 fixture 套件（2026-10-12 ledger-prune-manifest）
+// 覆盖：四条判据逐条（哈希命中数 / 内容对账 / docs 清单 / manifest 缺失）+ 链段重启凭据 +
+//       --staged 真 git 端到端（放行与拦截）+ 无 manifest 时 append-only 红线不变。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const { matchPrune, sha256line, PRUNE_REL } = await import(pathToFileURL(path.join(SCRIPT_DIR, 'ledger-prune.mjs')).href);
+// 夹具闭包（2026-10-12 fixture-closure-rootfix）：check-ledger-invariant 及其传递依赖（ledger-loader /
+// policy 等）整闭包拷入。此前手写枚举漏拷 ledger-loader.mjs → 该脚本 import 失败 → 门禁静默不跑 →
+// 假绿；现在闭包自动跟随，且拷完 assertFixtureScripts 会在建夹具当场炸出全量缺失清单。
+const { copyScriptClosure } = await import(pathToFileURL(path.join(SCRIPT_DIR, 'fixture-scripts.mjs')).href);
+
+let pass = 0, fail = 0;
+const check = (name, ok, detail = '') => {
+  if (ok) { pass++; console.log(`  ok  ${name}`); }
+  else { fail++; console.error(`FAIL  ${name}${detail ? ' — ' + detail : ''}`); }
+};
+
+const L = (...xs) => xs.filter(Boolean).join('\n') + '\n';
+const rowA = L('{"ts":"2026-10-01T00:00:00Z","doc":"workflow/intents/2026-10-01-a.md","stage":"approved","fingerprint":"' + 'a'.repeat(64) + '"}');
+const rowB = L('{"ts":"2026-10-02T00:00:00Z","doc":"workflow/plans/2026-10-01-a.md","stage":"approved","fingerprint":"' + 'b'.repeat(64) + '"}');
+const rowC = L('{"ts":"2026-10-03T00:00:00Z","doc":"workflow/intents/2026-10-01-z.md","stage":"approved","fingerprint":"' + 'c'.repeat(64) + '"}');
+const HEAD = rowA + rowB + rowC;
+
+// ============ 场景 1：四条判据逐条 ============
+{
+  const mk = (over = {}) => ({
+    ts: '2026-10-12T00:00:00Z', authority: '仓库所有者', reason: '归档下架一批单',
+    removes: [sha256line(rowB.trim())], docs: ['2026-10-01-a'], ...over,
+  });
+  // ① manifest 缺失 / removes 空
+  check('S1① manifest 缺失 → err', !!(matchPrune(HEAD, rowA + rowC, null) || {}).err);
+  check('S1① removes 为空 → err', !!(matchPrune(HEAD, rowA + rowC, mk({ removes: [] })).err));
+  // ② 哈希不存在
+  check('S1② 哈希不存在 → err（命中数不符）',
+    !!(matchPrune(HEAD, rowA + rowC, mk({ removes: ['0'.repeat(64)] })).err));
+  // ② 哈希声明重复（两行内容相同 → 一个哈希命中 2 行）
+  const dup = L('{"ts":"1","doc":"workflow/intents/d.md","stage":"approved"}', '{"ts":"1","doc":"workflow/intents/d.md","stage":"approved"}');
+  check('S1② 重复行声明单哈希 → err（命中数 ≠ 声明数）',
+    !!(matchPrune(dup, '', mk({ removes: [sha256line(dup.split('\n')[0])] })).err));
+  // ③ 存在 manifest 之外的改动
+  check('S1③ 多删一行（manifest 外） → err',
+    !!(matchPrune(HEAD, rowA, mk()).err));
+  check('S1③ 改写保留行内容 → err',
+    !!(matchPrune(HEAD, rowA + rowC.replace('approved', 'done'), mk()).err));
+  check('S1③ 插入新行 → err',
+    !!(matchPrune(HEAD, rowA + rowC + rowB, mk()).err));
+  // ④ doc 不在清单
+  check('S1④ 被删行 doc 不在 manifest.docs → err',
+    !!(matchPrune(HEAD, rowA + rowC, mk({ docs: ['some-other'] })).err));
+  check('S1④ docs 为空数组 = 不约束 → 放行',
+    !(matchPrune(HEAD, rowA + rowC, mk({ docs: [] })).err));
+  // 全对
+  const ok = matchPrune(HEAD, rowA + rowC, mk());
+  check('S1 全部判据通过 → 放行且计数正确',
+    !ok.err && ok.removed === 1 && ok.docs[0] === '2026-10-01-a', JSON.stringify(ok));
+  check('S1 返回被删哈希供链校验复用', Array.isArray(ok.hashes) && ok.hashes[0] === sha256line(rowB.trim()));
+}
+
+// ============ 场景 2：--staged 真 git 端到端 ============
+{
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'prune-e2e-'));
+  const git = (args, cwd = d) => spawnSync('git', args, { cwd, encoding: 'utf8' });
+  git(['init', '-q', '.']);
+  git(['config', 'user.email', 't@t.io']); git(['config', 'user.name', 't']);
+  git(['config', 'core.autocrlf', 'false']);
+  const mkfix = () => {
+    fs.mkdirSync(path.join(d, '.agents', 'scripts'), { recursive: true });
+    copyScriptClosure(path.join(d, '.agents', 'scripts'), ['check-ledger-invariant.mjs']);
+    for (const p of ['workflow/intents/2026-10-01-a.md', 'workflow/plans/2026-10-01-a.md', 'workflow/intents/2026-10-01-z.md']) {
+      fs.mkdirSync(path.join(d, path.dirname(p)), { recursive: true });
+      fs.writeFileSync(path.join(d, p), '---\n状态: approved\n---\n# doc\n', 'utf8');
+    }
+    fs.writeFileSync(path.join(d, '.agents', 'confirmations.jsonl'), HEAD, 'utf8');
+    git(['add', '-A']); git(['commit', '-qm', 'base']);
+  };
+  const runGate = () => spawnSync(process.execPath, ['.agents/scripts/check-ledger-invariant.mjs', '--staged'],
+    { cwd: d, encoding: 'utf8' });
+
+  // ① 无 manifest 直接删行 → 仍 hard-block（append-only 红线不变）
+  mkfix();
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.jsonl'), rowA + rowC, 'utf8');
+  git(['add', '-A']);
+  let r = runGate();
+  check('S2① 无 manifest 删行 → exit 1（红线不变）', r.status === 1, `exit=${r.status} ${r.stderr}`);
+  check('S2① 报文含「特许修剪对账失败」', /台账重写/.test(r.stderr), r.stderr);
+
+  // ② 带 manifest 同笔暂存 → 放行
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.jsonl'), rowA + rowC, 'utf8');
+  fs.writeFileSync(path.join(d, PRUNE_REL), JSON.stringify({
+    ts: '2026-10-12T00:00:00Z', authority: '仓库所有者指令', reason: '下架 a 家族',
+    removes: [sha256line(rowB.trim())], docs: ['2026-10-01-a'],
+  }, null, 2), 'utf8');
+  git(['add', '-A']);
+  r = runGate();
+  check('S2② 带合法 manifest → exit 0 放行', r.status === 0, `exit=${r.status} ${r.stderr}`);
+  check('S2② 放行报文点名凭据与行数', /特许修剪通过/.test(r.stdout) && /移除 1 行/.test(r.stdout), r.stdout);
+
+  // ③ manifest 只写一半（另删一行未申报） → 仍拦
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.jsonl'), rowA, 'utf8');
+  git(['add', '-A']);
+  r = runGate();
+  check('S2③ manifest 外的额外删行 → exit 1', r.status === 1, `exit=${r.status}`);
+  check('S2③ 报文说明内容 ≠ 旧 − manifest', /旧内容 − manifest/.test(r.stderr), r.stderr);
+
+  // ④ 提交后跑历史全扫 → 认领修剪、不报前缀破坏
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.jsonl'), rowA + rowC, 'utf8');
+  git(['add', '-A']); git(['commit', '-qm', 'prune with manifest']);
+  r = spawnSync(process.execPath, ['.agents/scripts/check-ledger-invariant.mjs'], { cwd: d, encoding: 'utf8' });
+  check('S2④ 历史全扫认领修剪 → exit 0', r.status === 0, `exit=${r.status} ${r.stderr}`);
+  check('S2④ 全扫输出含修剪认领记录', /特许修剪 1 行/.test(r.stderr + r.stdout), (r.stderr + r.stdout).slice(0, 300));
+}
+
+console.log(`\n[ledger-prune.test] PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);