agentic-flow-kit 1.7.15 → 1.7.16

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);

package/templates/_agents/scripts/ledger-ts-monotonic.test.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// ledger-ts-monotonic.test.mjs — 台账行级校验 ts 口径修正 + 分片覆盖 fixture 套件（2026-10-12）
+// 命题：并集合并 / 分片归并会制造**跨 doc** 的物理序 ts 乱序，这是正常协作而非篡改；判据必须从
+//   「全表非降序」改为「同 doc 内非降序」，同时不能因此丢掉真问题的检出（同 doc 内倒挂照 hard 拦）。
+// 覆盖面：跨 doc 乱序放行 + 计数出账 / 同 doc 内倒挂仍拦 / 分片行纳入行级校验 / 豁免行号不漂移。
+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));
+// 夹具闭包（2026-10-12 fixture-closure-rootfix）：整闭包自动跟随，不再手写依赖枚举（漏拷 = 假绿）
+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 : ''}`); }
+};
+
+// 建真 git fixture（行级校验只在有提交历史时才会跑到；--staged 也需要 HEAD 基线）
+function mkRepo() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'tsmono-'));
+  const git = (...args) => spawnSync('git', args, { cwd: d, encoding: 'utf8' });
+  git('init', '-q', '.');
+  git('config', 'user.email', 't@t.io'); git('config', 'user.name', 't');
+  git('config', 'core.autocrlf', 'false');
+  fs.mkdirSync(path.join(d, '.agents', 'scripts'), { recursive: true });
+  copyScriptClosure(path.join(d, '.agents', 'scripts'), ['check-ledger-invariant.mjs']);
+  return { d, git };
+}
+const docFile = (d, rel) => {
+  const p = path.join(d, ...rel.split('/'));
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, '---\n状态: approved\n---\n# doc\n', 'utf8');
+};
+const row = (ts, doc, extra = {}) => JSON.stringify({
+  ts, doc, stage: 'approved', fingerprint: 'a'.repeat(64), source: 'tty', ...extra,
+});
+const writeLedger = (d, lines) => {
+  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.jsonl'), lines.filter(Boolean).join('\n') + '\n', 'utf8');
+};
+const runGate = (d) => spawnSync(process.execPath, ['.agents/scripts/check-ledger-invariant.mjs'], { cwd: d, encoding: 'utf8' });
+
+// ============ 场景 1：跨 doc 物理序 ts 乱序（并集合并形态）→ 放行 + 计数出账 ============
+// a 的末行 ts 晚于 b 的首行 ts——正是「A 分支先提交、B 分支的行被并集追加到尾部」产生的形态。
+{
+  const { d, git } = mkRepo();
+  docFile(d, 'workflow/intents/2026-10-01-a.md');
+  docFile(d, 'workflow/intents/2026-10-01-b.md');
+  writeLedger(d, [
+    row('2026-10-10T00:00:00Z', 'workflow/intents/2026-10-01-a.md'), // 较晚
+    row('2026-10-01T00:00:00Z', 'workflow/intents/2026-10-01-b.md'), // 较早，跨 doc 乱序
+  ]);
+  git('add', '-A'); git('commit', '-qm', 'x');
+  const r = runGate(d);
+  check('S1 跨 doc ts 乱序 → exit 0 放行（正常协作形态）', r.status === 0, `exit=${r.status} ${r.stderr}`);
+  check('S1 乱序计数出账且标明不阻断',
+    /跨 doc 物理序 ts 乱序 1 处/.test(r.stdout) && /不阻断/.test(r.stdout), r.stdout);
+}
+
+// ============ 场景 2：同 doc 内 ts 倒挂 → 仍 hard 拦（真问题未被放松）============
+{
+  const { d, git } = mkRepo();
+  docFile(d, 'workflow/intents/2026-10-01-a.md');
+  writeLedger(d, [
+    row('2026-10-10T00:00:00Z', 'workflow/intents/2026-10-01-a.md'),
+    row('2026-10-01T00:00:00Z', 'workflow/intents/2026-10-01-a.md'), // 同 doc 倒挂
+  ]);
+  git('add', '-A'); git('commit', '-qm', 'x');
+  const r = runGate(d);
+  check('S2 同 doc 内 ts 倒挂 → exit 1 hard 拦', r.status === 1, `exit=${r.status}`);
+  check('S2 报文点名「追加时序倒挂」并带 doc',
+    /追加时序倒挂/.test(r.stderr) && /2026-10-01-a/.test(r.stderr), r.stderr);
+}
+
+// ============ 场景 3：分片行纳入行级校验（分片里的坏行不能逃逸）============
+{
+  const { d, git } = mkRepo();
+  docFile(d, 'workflow/intents/2026-10-01-a.md');
+  writeLedger(d, [row('2026-10-01T00:00:00Z', 'workflow/intents/2026-10-01-a.md')]);
+  // 分片里放一行 fingerprint 非 64 位 hex 的坏行——只扫主台账会漏掉它
+  fs.mkdirSync(path.join(d, '.agents', 'confirmations.d'), { recursive: true });
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.d', 'x.jsonl'),
+    JSON.stringify({ ts: '2026-10-02T00:00:00Z', doc: 'workflow/intents/2026-10-01-a.md', stage: 'approved', fingerprint: 'bad', source: 'tty' }) + '\n', 'utf8');
+  git('add', '-A'); git('commit', '-qm', 'x');
+  const r = runGate(d);
+  check('S3 分片内坏行被行级校验抓到 → exit 1', r.status === 1, `exit=${r.status} ${r.stdout}`);
+  check('S3 报文指出 fingerprint 非 64 位 hex', /fingerprint 非 64 位 hex/.test(r.stderr), r.stderr);
+}
+
+// ============ 场景 4：分片内 doc 不存在 → 同样被抓 ============
+{
+  const { d, git } = mkRepo();
+  docFile(d, 'workflow/intents/2026-10-01-a.md');
+  writeLedger(d, [row('2026-10-01T00:00:00Z', 'workflow/intents/2026-10-01-a.md')]);
+  fs.mkdirSync(path.join(d, '.agents', 'confirmations.d'), { recursive: true });
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.d', 'y.jsonl'),
+    row('2026-10-02T00:00:00Z', 'workflow/intents/2026-10-01-ghost.md') + '\n', 'utf8');
+  git('add', '-A'); git('commit', '-qm', 'x');
+  const r = runGate(d);
+  check('S4 分片内 doc 在当前树不存在 → exit 1', r.status === 1, `exit=${r.status}`);
+  check('S4 报文点名 ghost.md', /ghost\.md/.test(r.stderr), r.stderr);
+}
+
+// ============ 场景 5：豁免行号不因引入分片而漂移 ============
+// 视图序 = 主台账在前、分片在后 → 主台账第 2 行的豁免登记在引入分片后仍指向同一行。
+{
+  const { d, git } = mkRepo();
+  docFile(d, 'workflow/intents/2026-10-01-a.md');
+  docFile(d, 'workflow/intents/2026-10-01-b.md');
+  // 第 2 行是「doc 不存在」的坏行（须靠豁免放行）
+  writeLedger(d, [
+    row('2026-10-01T00:00:00Z', 'workflow/intents/2026-10-01-a.md'),
+    row('2026-10-02T00:00:00Z', 'workflow/intents/2026-10-01-ghost.md'),
+  ]);
+  fs.writeFileSync(path.join(d, '.agents', 'ledger-line-exempt.json'),
+    JSON.stringify([{ line: 2, doc: 'workflow/intents/2026-10-01-ghost.md', reason: '文档已归档' }]), 'utf8');
+  git('add', '-A'); git('commit', '-qm', 'x');
+  const before = runGate(d);
+  check('S5 前：无分片时豁免生效 → exit 0', before.status === 0, `exit=${before.status} ${before.stderr}`);
+
+  // 追加一个分片（视图序追加在主台账之后），豁免行号应仍指向 ghost 那行
+  fs.mkdirSync(path.join(d, '.agents', 'confirmations.d'), { recursive: true });
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.d', 'z.jsonl'),
+    row('2026-10-03T00:00:00Z', 'workflow/intents/2026-10-01-b.md') + '\n', 'utf8');
+  git('add', '-A'); git('commit', '-qm', 'y');
+  const after = runGate(d);
+  check('S5 后：引入分片，豁免行号未漂移 → 仍 exit 0', after.status === 0, `exit=${after.status} ${after.stderr}`);
+}
+
+console.log(`\n[ledger-ts-monotonic.test] PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);