agentic-flow-kit 1.7.15 → 1.7.16

package/templates/_agents/scripts/check-loop.mjs

@@ -126,8 +126,10 @@ import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { loadEnums } from './workflow-enums.mjs';
 import { runCheck16 } from './check-metric-claims.mjs';
-import { auditEnabled, loadKitPolicy, hasFreshVerifyLine, ledgerChainHash, scopeMatches } from './policy.mjs';
+import { auditEnabled, loadKitPolicy, hasFreshVerifyLine, ledgerChainHash, ledgerDocChainActive, scopeMatches } from './policy.mjs';
 import { laneOfEntry } from './stage-gates.mjs';
+import { readLedgerRows, readLedgerEntries, LEDGER_REL } from './ledger-loader.mjs';
+import { prunedHashes as prunedHashesOf } from './ledger-prune.mjs';
 // MARK_RE：incident 留痕形态的单源（第七轮复核 N3——此前 check-loop 内联复制一份同口径字面量，
 // 两处靠注释与人工同步；改为复用 stage-gates.mjs 的导出，从结构上消除漂移可能）
 import { MARK_RE, approvedTraceHit } from './stage-gates.mjs';
@@ -805,16 +807,10 @@ export function runCheckLoop(opts = {}) {
     const doneTsOf = (() => {
       const map = new Map();
       try {
-        const lp = path.join(ROOT, '.agents', 'confirmations.jsonl');
-        if (fs.existsSync(lp)) {
-          for (const line of fs.readFileSync(lp, 'utf8').split(/\r?\n/)) {
-            if (!line.trim()) continue;
-            try {
-              const e = JSON.parse(line);
-              // append-only 取末次 done 跳转（同一 doc 多次 done 取最后一条 ts）
-              if (e && e.doc && ['done', 'closed'].includes(e.stage)) map.set(e.doc, e.ts || '');
-            } catch { /* 坏行跳过（同检查 15 口径） */ }
-          }
+        // 读法收敛 ledger-loader（2026-10-12 ledger-loader-p1）：末次 done 跳转取自物理读序，
+        // loader 保持读序返回故「取末次」语义与逐处直读一致（分片按文件名序排在主台账之后＝较新）
+        for (const e of readLedgerRows(ROOT)) {
+          if (e && e.doc && ['done', 'closed'].includes(e.stage)) map.set(e.doc, e.ts || '');
         }
       } catch { /* 台账不可读 → 无锚 → 全走全局布尔（fail-open，不误报 hard） */ }
       return map;
@@ -1024,15 +1020,8 @@ export function runCheckLoop(opts = {}) {
     // 台账 approved 文档集合：单次读取（坏行容忍跳过，与检查 15 同口径）；缺失视为空集（git 判据仍守门）
     const ledgerApproved = new Set();
     try {
-      const lp = path.join(ROOT, '.agents', 'confirmations.jsonl');
-      if (fs.existsSync(lp)) {
-        for (const line of fs.readFileSync(lp, 'utf8').split(/\r?\n/)) {
-          if (!line.trim()) continue;
-          try {
-            const e = JSON.parse(line);
-            if (e && typeof e.doc === 'string' && e.stage === 'approved') ledgerApproved.add(e.doc);
-          } catch { /* 坏行容忍跳过 */ }
-        }
+      for (const e of readLedgerRows(ROOT)) {
+        if (typeof e.doc === 'string' && e.stage === 'approved') ledgerApproved.add(e.doc);
       }
     } catch { /* 台账不可读视为无 approved 行 */ }
     for (const sub of ['specs', 'plans']) {
@@ -1071,18 +1060,26 @@ export function runCheckLoop(opts = {}) {
   // 台账坏行容忍跳过（审计件，jsonl 追加式）；frontmatter 存 16 位、台账存 64 位，按前 16 位配对。
   {
     const EFFECTIVE = kitPolicy.confirmDocsEffective;
-    const ledgerPath = path.join(ROOT, '.agents', 'confirmations.jsonl');
+    // 取数走 ledger-loader 的**带来源行号视图**（2026-10-12 ledger-shard-write）：主台账 + 分片
+    // `.agents/confirmations.d/*.jsonl`。分片里的行同样受链校验——否则 `--shard` 写入就等于给台账开了
+    // 一个防伪盲区（门禁看得见分片行、却不验它们的链）。
+    // **此处曾刻意不走 loader**（单源化时留的例外，因当时要物理行号对齐）；引入分片后该理由已不成立
+    // ——单一行号跨来源无法定位，故改用带 rel 的定位。第二处例外仍是 check-ledger-invariant.mjs
+    // （它审的是**盘面字节**的 append-only 前缀不变量，不是台账语义，见该文件头部）。
     const ledger = [];
-    const ledgerBadLines = []; // 坏行（JSON.parse 失败）的物理行号（复核 P2-1：报文行号须对齐物理行）
-    if (fs.existsSync(ledgerPath)) {
-      for (const [lineNo, line] of (linesOf(ledgerPath) || []).entries()) {
-        if (!line.trim()) continue;
-        try { ledger.push(JSON.parse(line)); } catch { ledgerBadLines.push(lineNo + 1); }
-      }
+    const ledgerRefs = [];   // 与 ledger 同下标：{rel, no}——断裂报文的定位来源
+    for (const e of readLedgerEntries(ROOT)) {
+      if (e.row === null) continue; // 坏行跳过（容错口径同前；它占物理行号但不入 ledger 下标）
+      ledger.push(e.row);
+      ledgerRefs.push({ rel: e.rel, no: e.no });
     }
-    // 台账哈希链校验（2026-10-09 engine-quality-round2 D；写入侧=confirm-doc appendLedger，哈希单源
-    // policy.ledgerChainHash——判定零复刻）。判据：连续带 hash 行段内，① prevHash 须等于前一带 hash
-    // 行的 hash（无 hash 行后链段重启 ''，与写入侧读末行口径一致）；② hash 须可重算一致。
+    // 台账哈希链校验（2026-10-09 engine-quality-round2 D；2026-10-12 ledger-doc-chain 改链域；
+    // 写入侧=confirm-doc appendLedger，哈希单源 policy.ledgerChainHash——判定零复刻）。
+    // **链域已从「文件物理序」改为「按 doc 的逻辑序」**（锚后生效，理由与不追溯口径见 POLICIES v8）：
+    //   原判据 ① prevHash = 前一带 hash 行（物理）的 hash；新判据 ① = **同行 doc** 最后一个带 hash 行的
+    //   hash。两者都要求 ② hash 可重算一致。无 hash 行仍按「链段重启」处理。
+    //   并发 append / git 并集合并 / 分片归并这三种**正常协作**都会打断物理链——门禁若继续据此 hard 拦，
+    //   必然被 --no-verify 绕过，治理失效；而 doc 链对就地改行 / 删行 / 插行三类篡改的检出能力不变。
     // **坏行口径（复核 P2-1 勘误，此前注释误称「与写入侧一致」）**：坏行被本解析整体剔除、不重置游标
     // ——坏行后写入的链行（写入侧读末行遇坏行 prevHash=''）验链必失配出账。这是**预期 fail-loud**
     // （坏行本身即台账完整性事故，应人工查验），非口径一致场景。
@@ -1093,19 +1090,36 @@ export function runCheckLoop(opts = {}) {
       let prevHash = '';
       let brokenAt = 0;
       let brokenCount = 0;
+      // 链域分界（2026-10-12 ledger-doc-chain）：doc 链锚存在且合法时，**按行分域**验链——
+      //   锚前行（ts < 锚）维持物理链口径（存量零变化）；锚后行（ts ≥ 锚）按「同行 doc 的最后一个
+      //   带 hash 行」接续，并同样要求 hash 可重算一致。锚缺键（v1-v7）→ 全表走物理链（= 旧行为）。
+      // byDoc 对**两种域的行都更新**：锚后行需要接到锚前该 doc 的最后一行，跨域才能连续。
+      const docChainOn = ledgerDocChainActive(kitPolicy);
+      const docChainSince = docChainOn ? kitPolicy.ledgerDocChainSince : '';
+      const byDoc = new Map();
+      const prunedHashSet = prunedHashesOf(ROOT); // 特许修剪凭据（无 manifest 时为空集，零 IO 成本）
       ledger.forEach((row, idx) => {
         if (!row || typeof row.hash !== 'string') { prevHash = ''; return; } // 存量行/无链字段 → 链段重启
         const { hash, prevHash: p, ...rest } = row;
-        const ok = (p ?? '') === prevHash && ledgerChainHash(rest, p ?? '') === hash;
+        const inDocChain = docChainOn && typeof row.ts === 'string' && row.ts >= docChainSince;
+        const expected = inDocChain ? (byDoc.get(row.doc) ?? '') : prevHash;
+        // 特许修剪链段重启（2026-10-12 ledger-prune-manifest）：删掉某 doc 的链行后，其后继行仍带被删行
+        //   的 prevHash，而该行已不在表内 → 必然失配。本行的 prevHash 若出现在 manifest 声明的被删哈希里，
+        //   即视为**有凭据的合法重启点**而非篡改（凭据 = .agents/ledger-prune-manifest.json，入库可对质）。
+        const prunedRestart = (p ?? '') !== expected && prunedHashSet.has(p ?? '');
+        const ok = ((p ?? '') === expected || prunedRestart) && ledgerChainHash(rest, p ?? '') === hash;
         if (!ok) {
-          if (!brokenAt) brokenAt = idx + 1;
+          if (!brokenAt) brokenAt = idx + 1; // 1-based 下标，供 ledgerRefs 定位
           brokenCount++;
         }
         prevHash = hash;
+        if (typeof row.doc === 'string') byDoc.set(row.doc, hash);
       });
       if (brokenAt) {
-        const physical = brokenAt + ledgerBadLines.filter((n) => n <= brokenAt).length; // 物理行号（复核 P2-1：剔除坏行会令数组下标漂移）
-        blockers.push(`- [台账链断裂] confirmations.jsonl 自第 ${physical} 行（物理）起哈希链校验失败（共 ${brokenCount} 行不一致——append-only 台账出现就地改/删痕迹；prevHash 接续或内容重算不符。整文件重写不可机器防，对质走台账自身 git 历史）`);
+        // 定位用 ledgerRefs（来源 + 行号）：跨来源后单一行号无法定位；坏行占位不计入 ledger 下标
+        const at = ledgerRefs[brokenAt - 1] || { rel: LEDGER_REL, no: brokenAt };
+        const domain = docChainOn ? '锚前物理链 / 锚后 doc 链' : '物理链';
+        blockers.push(`- [台账链断裂] 自 ${at.rel}:${at.no} 起哈希链校验失败（${domain}，共 ${brokenCount} 行不一致——append-only 台账出现就地改/删痕迹；prevHash 接续或内容重算不符。整文件重写不可机器防，对质走台账自身 git 历史）`);
       }
     }
     // scope 子项（2026-10-09 审查 A1 干净版）：受管台账行须带**机器派生**的改动面 scope{files,sha256}。
@@ -1335,13 +1349,7 @@ export function runCheckLoop(opts = {}) {
     if (typeof since === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(since)) {
       const ledgerRows = [];
       {
-        const lp = path.join(ROOT, '.agents', 'confirmations.jsonl');
-        if (fs.existsSync(lp)) {
-          for (const line of linesOf(lp) || []) {
-            if (!line.trim()) continue;
-            try { ledgerRows.push(JSON.parse(line)); } catch { /* 坏行跳过（同检查 15 口径） */ }
-          }
-        }
+        for (const e of readLedgerRows(ROOT)) ledgerRows.push(e);
       }
       const hasRow = (rel) => ledgerRows.some((e) => e && e.doc === rel && (e.stage === 'approved' || e.stage === 'done'));
       const docConfirmed = (rel, abs) => {

package/templates/_agents/scripts/check-loop.test.mjs

@@ -28,6 +28,10 @@ const check = (desc, cond, detail = '') => {
   else { fail++; console.log(`FAIL  ${desc}${detail ? '\n      ' + detail : ''}`); }
 };
 
+// 夹具闭包工具（2026-10-12 fixture-closure-rootfix）：本文件此前 5 处手写依赖枚举，2026-10-12 那批
+// 台账改动漏拷 ledger-loader.mjs 就假绿过（看板漂移门恒绿）。改为按入口自动求传递闭包——新增依赖自动跟随。
+const { copyScriptClosure, copyAgentsFiles } = await import('./fixture-scripts.mjs');
+
 // mkfix：空 fixture 根（四目录 + 枚举单源内联 8 键——fixture 自包含，测消费逻辑而非当前词表值）
 const ENUMS_FIXTURE = [
   'doc.status.all=draft approved done superseded cancelled',
@@ -383,9 +387,8 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
 {
   const T = mkfix();
   fs.mkdirSync(path.join(T, '.agents', 'scripts'), { recursive: true });
-  fs.copyFileSync(path.join(SCRIPT_DIR, 'gen-workflow-index.mjs'), path.join(T, '.agents', 'scripts', 'gen-workflow-index.mjs'));
-  fs.copyFileSync(path.join(SCRIPT_DIR, 'workflow-enums.mjs'), path.join(T, '.agents', 'scripts', 'workflow-enums.mjs'));
-  fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'workflow-modules.txt'), path.join(T, '.agents', 'workflow-modules.txt'));
+  copyScriptClosure(path.join(T, '.agents', 'scripts'), ['gen-workflow-index.mjs']);
+  copyAgentsFiles(path.join(T, '.agents'), ['workflow-modules.txt']);
   w(T, 'workflow/intents/2026-09-22-mod-ok.md', INTENT('mod ok', '状态: approved\n级别: L1\n日期: 2026-09-22\n模块: pipeline', '\n## 验收标准（可测试）\n- [ ] 用例通过\n'));
   w(T, 'workflow/plans/2026-09-22-mod-ok.md', PLAN('mod ok', '状态: approved\n级别: L1\n模块: pipeline'));
   spawnSync(process.execPath, ['.agents/scripts/gen-workflow-index.mjs'], { cwd: T });
@@ -412,9 +415,8 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
 {
   const T = mkfix();
   fs.mkdirSync(path.join(T, '.agents', 'scripts'), { recursive: true });
-  fs.copyFileSync(path.join(SCRIPT_DIR, 'gen-workflow-index.mjs'), path.join(T, '.agents', 'scripts', 'gen-workflow-index.mjs'));
-  fs.copyFileSync(path.join(SCRIPT_DIR, 'workflow-enums.mjs'), path.join(T, '.agents', 'scripts', 'workflow-enums.mjs'));
-  fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'workflow-modules.txt'), path.join(T, '.agents', 'workflow-modules.txt'));
+  copyScriptClosure(path.join(T, '.agents', 'scripts'), ['gen-workflow-index.mjs']);
+  copyAgentsFiles(path.join(T, '.agents'), ['workflow-modules.txt']);
   w(T, 'workflow/intents/2026-09-22-drift.md', INTENT('drift', '状态: approved\n级别: L1\n日期: 2026-09-22\n模块: pipeline'));
   w(T, 'workflow/plans/2026-09-22-drift.md', PLAN('drift', '状态: approved\n级别: L1\n模块: pipeline'));
   spawnSync(process.execPath, ['.agents/scripts/gen-workflow-index.mjs'], { cwd: T });
@@ -430,10 +432,10 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
   const mkDashFix = () => {
     const T = mkfix();
     fs.mkdirSync(path.join(T, '.agents', 'scripts'), { recursive: true });
-    for (const f of ['gen-workflow-index.mjs', 'gen-workflow-dashboard.mjs', 'agg-delegations.cjs', 'workflow-enums.mjs']) {
-      fs.copyFileSync(path.join(SCRIPT_DIR, f), path.join(T, '.agents', 'scripts', f));
-    }
-    fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'workflow-modules.txt'), path.join(T, '.agents', 'workflow-modules.txt'));
+    // 看板/索引生成器的台账读取依赖（ledger-loader 等）由闭包自动带入——此前手写枚举漏拷过，
+    // 表现是「import 失败 → 看板静默不生成 → 漂移门恒绿」，即假绿比红危险（2026-10-12 已修，见 fixture-scripts.mjs）
+    copyScriptClosure(path.join(T, '.agents', 'scripts'), ['gen-workflow-index.mjs', 'gen-workflow-dashboard.mjs']);
+    copyAgentsFiles(path.join(T, '.agents'), ['workflow-modules.txt']);
     w(T, 'workflow/intents/2026-09-22-dash.md', INTENT('dash', '状态: approved\n级别: L1\n日期: 2026-09-22\n模块: pipeline'));
     w(T, 'workflow/plans/2026-09-22-dash.md', PLAN('dash', '状态: approved\n级别: L1\n模块: pipeline'));
     spawnSync(process.execPath, ['.agents/scripts/gen-workflow-index.mjs'], { cwd: T });
@@ -460,7 +462,7 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
   const T = mkfix();
   fs.mkdirSync(path.join(T, '.agents', 'scripts'), { recursive: true });
   fs.copyFileSync(path.join(SCRIPT_DIR, 'rule-budget.sh'), path.join(T, '.agents', 'scripts', 'rule-budget.sh'));
-  fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'rule-budgets.txt'), path.join(T, '.agents', 'rule-budgets.txt'));
+  copyAgentsFiles(path.join(T, '.agents'), ['rule-budgets.txt']);
   // 超限样本自校准：从拷入的预算表读 AGENTS.md 上限（预算可上调，硬编码样本会随上调失效——2026-10-06-v114-backflow-batch）
   const agLimit = Number(fs.readFileSync(path.join(T, '.agents', 'rule-budgets.txt'), 'utf8').split(/\r?\n/).find((l) => l.startsWith('AGENTS.md ')).trim().split(' ').pop());
   w(T, 'AGENTS.md', '# AGENTS 小体积 fixture\n');
@@ -488,7 +490,7 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
     const T = mkfix();
     fs.mkdirSync(path.join(T, '.agents', 'scripts'), { recursive: true });
     fs.copyFileSync(path.join(SCRIPT_DIR, 'rule-budget.sh'), path.join(T, '.agents', 'scripts', 'rule-budget.sh'));
-    fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'rule-budgets.txt'), path.join(T, '.agents', 'rule-budgets.txt'));
+    copyAgentsFiles(path.join(T, '.agents'), ['rule-budgets.txt']);
     const agLimit = Number(fs.readFileSync(path.join(T, '.agents', 'rule-budgets.txt'), 'utf8').split(/\r?\n/).find((l) => l.startsWith('AGENTS.md ')).trim().split(' ').pop());
     gitInit(T);
     w(T, 'AGENTS.md', 'x'.repeat(agLimit + 512));
@@ -2919,8 +2921,11 @@ w(T, 'workflow/intents/2026-09-12-deep.md', INTENT('deep', '状态: draft\n级
   writeLedger(T, [tampered, row2]);
   let r = run(T);
   let out = outOf(r);
+  // 定位措辞随 2026-10-12 ledger-shard-write 由「第 N 行（物理）」改为 `rel:行号`——
+  // 台账视图含主台账 + 分片后，单一行号跨来源无法定位，必须带来源。首断行号仍须精确指向第 1 行。
   check('场景 21a 链断裂：中间行篡改 → hard 台账链断裂（指首断行号）',
-    r.status !== 0 && out.includes('台账链断裂') && /第 1 行/.test(out), `exit=${r.status}\n${out.slice(-400)}`);
+    r.status !== 0 && out.includes('台账链断裂') && /\.agents\/confirmations\.jsonl:1\b/.test(out),
+    `exit=${r.status}\n${out.slice(-400)}`);
   // 反证还原：篡改行恢复原 quote → 链复通（断言非恒绿）
   writeLedger(T, [row1, row2]);
   r = run(T);

package/templates/_agents/scripts/check-metric-claims.mjs

@@ -17,14 +17,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { readLedgerLines } from './ledger-loader.mjs';
 
 export function runCheck16(ctx) {
   const { ROOT, ENUMS, docFiles, fmGet, inSet, isTracked, linesOf, readdirOrNull, warnings } = ctx;
   const mcFile = path.join(ROOT, '.agents', 'metric-claims.txt');
   if (fs.existsSync(mcFile)) {
     const ledgerLines = () => {
-      const p = path.join(ROOT, '.agents', 'confirmations.jsonl');
-      const ls = (linesOf(p) || []).filter((l) => l.trim());
+      // 读法收敛 ledger-loader（2026-10-12 ledger-loader-p1）：本指标按**原始文本行**计数
+      // （total / 含 "batch" 字段的行数），故用 lines 视图而非 rows 视图。
+      const ls = readLedgerLines(ROOT);
       return { total: ls.length, withBatch: ls.filter((l) => /"batch"/.test(l)).length };
     };
     // 内置取数器：全部本地确定性、零网络。**装户零配置即用**（不依赖任何装户文件）。

package/templates/_agents/scripts/compact-ledgers.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// compact-ledgers.mjs — 台账分片归并器（2026-10-12 ledger-shard-write 配套）
+// 用途：里程碑节点或发布前，把 `.agents/confirmations.d/*.jsonl` 的分片确认行并回主台账
+//   `.agents/confirmations.jsonl` 并清理分片。`--shard` 写入的分片若长期不归并，会让台账面无限碎片化，
+//   且分片的历史不受主台账的前缀不变量约束（见 check-ledger-invariant 已知边界）——本脚本就是收敛动作。
+//
+// 保持 append-only 前缀不变量：主台账既有行**严格保序不动**，分片新行只追加到末尾——这正是
+//   check-ledger-invariant 的「旧 blob 是新 blob 的逐字节前缀」所要求的形态。绝不做重排/去重改写。
+//
+// 安全设计（三条，缺一条都可能损坏主台账）：
+//   ① 默认 dry-run：只报告「将并入 N 行」，不动盘。必须显式 execute 才写。
+//   ② 原子覆写：同目录临时文件 + rename。中途崩溃 = 主台账原样、分片未删，可安全重跑。
+//   ③ 幂等：并集按整行文本去重（复用 git-merge-jsonl 的同款判据），重复执行结果不变。
+//   任一分片读取失败 → 立即中止，主台账与全部分片保持原样。
+//
+// 用法：node .agents/scripts/compact-ledgers.mjs [--root <仓库根>] [--execute]
+import fs from 'node:fs';
+import path from 'node:path';
+import { mergeJsonlLines } from './git-merge-jsonl.mjs';
+import { LEDGER_REL, SHARD_DIR_REL } from './ledger-loader.mjs';
+
+const linesOf = (t) => (t || '').replace(/\r\n/g, '\n').split('\n').filter((l) => l.trim().length > 0);
+
+// compactLedgers(root, { execute })：纯函数形态，供测试直测。
+//   返回 { ok, skipped?, reason?, added, before, after, shards, shardLines, error? }
+export function compactLedgers(root = process.cwd(), { execute = false } = {}) {
+  const mainLedger = path.join(root, ...LEDGER_REL.split('/'));
+  const shardDir = path.join(root, ...SHARD_DIR_REL.split('/'));
+
+  if (!fs.existsSync(shardDir) || !fs.statSync(shardDir).isDirectory()) {
+    return { ok: true, skipped: true, reason: '无分片目录', added: 0, before: 0, after: 0, shards: 0, shardLines: 0 };
+  }
+  const shardFiles = fs.readdirSync(shardDir).filter((f) => f.endsWith('.jsonl')).sort();
+  if (shardFiles.length === 0) {
+    return { ok: true, skipped: true, reason: '分片目录无 .jsonl', added: 0, before: 0, after: 0, shards: 0, shardLines: 0 };
+  }
+
+  const mainBefore = fs.existsSync(mainLedger) ? fs.readFileSync(mainLedger, 'utf8') : '';
+  const mainBeforeLines = linesOf(mainBefore);
+
+  let shardCombined = '';
+  let shardLineCount = 0;
+  for (const f of shardFiles) {
+    try {
+      const t = fs.readFileSync(path.join(shardDir, f), 'utf8');
+      shardLineCount += linesOf(t).length;
+      shardCombined += '\n' + t;
+    } catch (err) {
+      // fail-soft 中止：主台账与全部分片保持原样（修好重跑即可——并集按行去重，重跑安全）
+      return { ok: false, error: `读取分片失败: ${f} (${err.message})`, added: 0, before: mainBeforeLines.length, after: mainBeforeLines.length, shards: shardFiles.length, shardLines: shardLineCount };
+    }
+  }
+
+  const merged = mergeJsonlLines(mainBefore, shardCombined);
+  const added = linesOf(merged).filter((l) => !mainBeforeLines.includes(l)).length;
+  const after = linesOf(merged).length;
+
+  if (!execute) {
+    return { ok: true, skipped: true, reason: 'dry-run', added, before: mainBeforeLines.length, after, shards: shardFiles.length, shardLines: shardLineCount };
+  }
+
+  const tmpMain = `${mainLedger}.tmp`;
+  try {
+    fs.writeFileSync(tmpMain, merged, 'utf8');
+    fs.renameSync(tmpMain, mainLedger);
+  } catch (err) {
+    try { fs.unlinkSync(tmpMain); } catch { /* tmp 可能未创建或删除失败 */ }
+    return { ok: false, error: `主台账写入失败: ${err.message}`, added: 0, before: mainBeforeLines.length, after: mainBeforeLines.length, shards: shardFiles.length, shardLines: shardLineCount };
+  }
+
+  for (const f of shardFiles) {
+    try { fs.unlinkSync(path.join(shardDir, f)); } catch { /* 残留分片不影响正确性，下轮再清 */ }
+  }
+  try { if (fs.readdirSync(shardDir).length === 0) fs.rmdirSync(shardDir); } catch { /* 忽略 */ }
+
+  return { ok: true, added, before: mainBeforeLines.length, after, shards: shardFiles.length, shardLines: shardLineCount };
+}
+
+const isMain = process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('compact-ledgers.mjs');
+if (isMain) {
+  const argv = process.argv.slice(2);
+  const i = argv.indexOf('--root');
+  const root = path.resolve(i >= 0 && argv[i + 1] ? argv[i + 1] : process.cwd());
+  const execute = argv.includes('--execute');
+  const r = compactLedgers(root, { execute });
+
+  if (!r.ok) { console.error(`[compact-ledgers] ${r.error}`); console.error('[compact-ledgers] 已中止：主台账与分片保持原样，修好重跑即可。'); process.exit(1); }
+  if (r.skipped) { console.log(`[compact-ledgers] ${r.reason}，无需归并。`); process.exit(0); }
+  if (!execute) {
+    console.log(`[compact-ledgers] dry-run：将并入 ${r.added} 行（分片共 ${r.shardLines} 行 / ${r.shards} 个文件，其中 ${r.shardLines - r.added} 行主台账已有），主台账 ${r.before} → ${r.after} 行`);
+    console.log('[compact-ledgers] 加 --execute 执行（未加则不动盘）。');
+    process.exit(0);
+  }
+  console.log(`[compact-ledgers] ✅ 归并完成：并入 ${r.added} 行，主台账 ${r.before} → ${r.after} 行；${r.shards} 个分片已清理。`);
+  console.log('[compact-ledgers] 提醒：归并产生的台账变更请随下一笔提交入库——历史前缀不变量按提交判，不入库等于没生效。');
+  process.exit(0);
+}

package/templates/_agents/scripts/compact-ledgers.test.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// compact-ledgers.test.mjs — 台账分片写入与 compact 归并 fixture 套件（2026-10-12 ledger-shard-write）
+// 覆盖：分片写入定位 + 跨来源链衔接 / compact 默认 dry-run 不动盘 / 幂等 / 前缀不变式（既有行保序）/
+//       读取失败中止 / 分片历史扫描与 compact 删除豁免 / 行未并入时仍拦丢行。
+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 { compactLedgers } = await import(pathToFileURL(path.join(SCRIPT_DIR, 'compact-ledgers.mjs')).href);
+const { appendLedger } = await import(pathToFileURL(path.join(SCRIPT_DIR, 'confirm-doc.mjs')).href);
+const { ledgerChainHash } = await import(pathToFileURL(path.join(SCRIPT_DIR, 'policy.mjs')).href);
+// 夹具闭包（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 : ''}`); }
+};
+
+const DOC_A = 'workflow/intents/2026-10-01-a.md';
+const DOC_B = 'workflow/intents/2026-10-01-b.md';
+const baseEntry = (doc, stage = 'approved') => ({
+  ts: new Date().toISOString(), doc, stage, fingerprint: 'a'.repeat(64), source: 'tty',
+});
+// --shard 依赖 doc 链口径（policyVersion ≥ 8）：分片与主台账是不同文件，只有 doc 链跨来源接续。
+// 装 kit.json 的 policyVersion=8 来启用，与真实装户升级后的形态一致。
+const enableDocChain = (root) => {
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'kit.json'), JSON.stringify({ policyVersion: 8 }), 'utf8');
+};
+
+// ============ 场景 1：--shard 写入定位到分片，且跨来源链接得上 ============
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-write-'));
+  enableDocChain(root);
+  // 先用主台账写一行（模拟该 doc 的历史行在主台账）
+  appendLedger(root, baseEntry(DOC_A));
+  const mainPath = path.join(root, '.agents', 'confirmations.jsonl');
+  check('S1 默认写主台账', fs.existsSync(mainPath));
+
+  // 再对同一 doc 用 --shard 写一行：前驱必须接主台账那行，而不是从 '' 重启
+  appendLedger(root, baseEntry(DOC_A, 'done'), { shard: true });
+  const shardPath = path.join(root, '.agents', 'confirmations.d', '2026-10-01-a.jsonl');
+  check('S1 --shard 写入分片文件（按 doc 基名命名）', fs.existsSync(shardPath));
+
+  const mainRows = fs.readFileSync(mainPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+  const shardRows = fs.readFileSync(shardPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+  check('S1 分片行的 prevHash 接主台账同 doc 行（跨来源衔接，链不断）',
+    shardRows[0].prevHash === mainRows[0].hash, `${shardRows[0].prevHash} vs ${mainRows[0].hash}`);
+  // 行内重算仍一致（doc 链前提）
+  const { hash, prevHash, ...rest } = shardRows[0];
+  check('S1 分片行行内哈希可重算', ledgerChainHash(rest, prevHash) === hash);
+}
+
+// ============ 场景 2：compact 默认 dry-run 不动盘 ============
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-dry-'));
+  appendLedger(root, baseEntry(DOC_A));
+  appendLedger(root, baseEntry(DOC_B), { shard: true });
+  const mainPath = path.join(root, '.agents', 'confirmations.jsonl');
+  const before = fs.readFileSync(mainPath, 'utf8');
+  const shardPath = path.join(root, '.agents', 'confirmations.d', '2026-10-01-b.jsonl');
+
+  const r = compactLedgers(root); // 默认 execute:false
+  check('S2 dry-run 标记 skipped 且给出并入行数', r.ok && r.skipped && r.reason === 'dry-run' && r.added === 1, JSON.stringify(r));
+  check('S2 dry-run 主台账字节不变', fs.readFileSync(mainPath, 'utf8') === before);
+  check('S2 dry-run 分片仍在', fs.existsSync(shardPath));
+}
+
+// ============ 场景 3：--execute 归并 + 前缀不变式 ============
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-exec-'));
+  appendLedger(root, baseEntry(DOC_A));
+  const mainPath = path.join(root, '.agents', 'confirmations.jsonl');
+  const before = fs.readFileSync(mainPath, 'utf8');
+  appendLedger(root, baseEntry(DOC_B), { shard: true });
+
+  const r = compactLedgers(root, { execute: true });
+  const after = fs.readFileSync(mainPath, 'utf8');
+  check('S3 execute 归并成功并计入 1 行', r.ok && !r.skipped && r.added === 1, JSON.stringify(r));
+  check('S3 既有行严格保序在前（append-only 前缀不变式）', after.startsWith(before), JSON.stringify(after.slice(0, 40)));
+  check('S3 分片已清理', !fs.existsSync(path.join(root, '.agents', 'confirmations.d', '2026-10-01-b.jsonl')));
+}
+
+// ============ 场景 4：幂等（重跑不重复追加）============
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-idem-'));
+  enableDocChain(root);
+  appendLedger(root, baseEntry(DOC_A));
+  appendLedger(root, baseEntry(DOC_B), { shard: true });
+  compactLedgers(root, { execute: true });
+  const mainPath = path.join(root, '.agents', 'confirmations.jsonl');
+  const after1 = fs.readFileSync(mainPath, 'utf8');
+  const mergedLine = after1.trim().split('\n').pop(); // 归并时实际追加的那一行（含 prevHash/hash）
+
+  // 把**同一行原文**再放进分片重跑（模拟重复归并同批内容）——行文本逐字相同才会被去重
+  fs.mkdirSync(path.join(root, '.agents', 'confirmations.d'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'confirmations.d', '2026-10-01-b.jsonl'), mergedLine + '\n', 'utf8');
+  const r = compactLedgers(root, { execute: true });
+  const after2 = fs.readFileSync(mainPath, 'utf8');
+  check('S4 重复归并不重复追加（并集按整行去重）', r.ok && r.added === 0 && after1 === after2, `added=${r.added}`);
+}
+
+// ============ 场景 5：无分片 / 空分片 → 跳过且不报错 ============
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-none-'));
+  const r = compactLedgers(root);
+  check('S5 无分片目录 → 跳过且 ok', r.ok && r.skipped);
+}
+
+// ============ 场景 6：分片历史扫描 + compact 删除豁免（真 git）============
+{
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-hist-'));
+  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']);
+  const mkDoc = (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 rowObj = (doc) => JSON.stringify({ ts: '2026-10-01T00:00:00Z', doc, stage: 'approved', fingerprint: 'a'.repeat(64), source: 'tty' });
+  const runGate = () => spawnSync(process.execPath, ['.agents/scripts/check-ledger-invariant.mjs'], { cwd: d, encoding: 'utf8' });
+
+  mkDoc(DOC_A); mkDoc(DOC_B);
+  // 基线：主台账一行 + 分片一行（分片持有 B 的行）
+  fs.mkdirSync(path.join(d, '.agents', 'confirmations.d'), { recursive: true });
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.jsonl'), rowObj(DOC_A) + '\n', 'utf8');
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.d', '2026-10-01-b.jsonl'), rowObj(DOC_B) + '\n', 'utf8');
+  git('add', '-A'); git('commit', '-qm', 'base with shard');
+  let r = runGate();
+  check('S6 分片入库且未删 → 历史扫描放行', r.status === 0, `exit=${r.status} ${r.stderr}`);
+
+  // compact 归并后删分片：删除豁免应认领
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.jsonl'), rowObj(DOC_A) + '\n' + rowObj(DOC_B) + '\n', 'utf8');
+  fs.rmSync(path.join(d, '.agents', 'confirmations.d', '2026-10-01-b.jsonl'));
+  git('add', '-A'); git('commit', '-qm', 'compact merged');
+  r = runGate();
+  check('S6 compact 归并删分片 → 删除豁免认领，exit 0', r.status === 0, `exit=${r.status} ${r.stderr}`);
+  check('S6 豁免记录点名 compact 归并形态', /compact 归并形态/.test(r.stderr), r.stderr.slice(0, 200));
+
+  // 未归并就删分片（丢行）→ 仍 hard 拦。用**从未进过主台账**的独立 doc C，
+  // 否则它的行已在主台账里（早先 compact 并过），删除豁免会正确地放行——那正是豁免该有的行为。
+  const DOC_C = 'workflow/intents/2026-10-01-c.md';
+  mkDoc(DOC_C);
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.d', '2026-10-01-c.jsonl'), rowObj(DOC_C) + '\n', 'utf8');
+  git('add', '-A'); git('commit', '-qm', 'add shard c');
+  fs.rmSync(path.join(d, '.agents', 'confirmations.d', '2026-10-01-c.jsonl'));
+  git('add', '-A'); git('commit', '-qm', 'drop shard c without merge');
+  r = runGate();
+  check('S6 未归并即删分片（丢行）→ exit 1 hard 拦', r.status === 1, `exit=${r.status}`);
+  check('S6 报文点名「分片删除丢行」', /分片删除丢行/.test(r.stderr), r.stderr.slice(0, 300));
+}
+
+console.log(`\n[compact-ledgers.test] PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);