agentic-flow-kit 1.8.7 → 2.1.0

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

@@ -1,166 +0,0 @@
-#!/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

@@ -1,108 +0,0 @@
-#!/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

@@ -1,131 +0,0 @@
-#!/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

@@ -1,96 +0,0 @@
-#!/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

@@ -1,120 +0,0 @@
-#!/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);