agentic-flow-kit 1.7.15 → 1.7.16

package/templates/_agents/scripts/gen-workflow-metrics.mjs

@@ -13,6 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadEnums } from './workflow-enums.mjs';
+import { readLedgerRows as loadLedgerRows } from './ledger-loader.mjs';
 
 const USAGE = `用法：node .agents/scripts/gen-workflow-metrics.mjs [--month YYYY-MM] [--dry-run] [--help]
 
@@ -43,34 +44,10 @@ const WORKFLOW = 'workflow';
 const METRICS_P = path.join(WORKFLOW, 'metrics.md');
 const BUDGETS = path.join('.agents', 'rule-budgets.txt');
 const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
-// 活跃口径单源（board-kb-p1：枚举字面量硬编码退役——workflow-enums.txt 是唯一源）；
-// 枚举路径锚定脚本位置（fixture 测试 cwd 在临时目录，按 cwd 解析会 ENOENT）。
-// **不能用固定上溯级数**（2026-09-28 修正）：本脚本在两处运行、深度不同——
-//   包源 `templates/_agents/scripts/` → 上溯 3 级到仓库根
-//   装户 `.agents/scripts/`          → 上溯 2 级到安装根
-// 首版硬编码 3 级，故**在每个装户安装里都解析不到枚举文件**（报错路径 `<install>/../.agents/…`）。
-// 实测暴露路径：CI 新增「shipped 套件」步骤后，`.agents/scripts/gen-workflow-metrics.test.mjs`
-// 场景 1 即 exit 1（workflow-enums 单源文件不可读），而包源侧同字节跑出全绿。
-// 改为**逐级上溯探测**：找到含 `.agents/workflow-enums.txt` 的那一级即用，找不到则回退标准位置让
-// loadEnums fail-loud（保持「缺失即响亮」的既有纪律，不静默兜底）。
-// 包源仓布局补丁（装户端内容清理后）：纯包源仓无 `.agents/`，枚举单源在 `templates/_agents/` 下——
-// 上一级目录名是 `_agents` 而非 `.agents`。探测同步认这两种布局，回退仍走 fail-loud。
-const resolveEnumsPath = () => {
-  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-  let dir = scriptDir;
-  for (let i = 0; i < 6; i++) {
-    const cand = path.join(dir, '.agents', 'workflow-enums.txt');
-    if (fs.existsSync(cand)) return cand;
-    const parent = path.dirname(dir);
-    if (parent === dir) break; // 到根
-    dir = parent;
-  }
-  // 包源径：脚本在 templates/_agents/scripts/，枚举在 templates/_agents/workflow-enums.txt
-  const pkgSrc = path.join(scriptDir, '..', 'workflow-enums.txt');
-  if (fs.existsSync(pkgSrc)) return pkgSrc;
-  return path.join(scriptDir, '..', '..', '.agents', 'workflow-enums.txt');
-};
-const ENUMS = loadEnums(resolveEnumsPath());
+// 活跃口径单源（workflow-enums.txt）。与脚本同层的上一级：
+// 包源 templates/_agents/workflow-enums.txt，装户副本 .agents/workflow-enums.txt。
+// 拷贝后相对位置不变，不按仓库根猜测另一套目录。
+const ENUMS = loadEnums(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'workflow-enums.txt'));
 const ACTIVE_STATUS = [...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']];
 const BEGIN = '<!-- GENERATED:BEGIN — gen-workflow-metrics.mjs 整段重写，手工说明写在本行之前 -->';
 const END = '<!-- GENERATED:END -->';
@@ -176,12 +153,11 @@ const idxActive = Number((idxText.match(/^## 活跃（(\d+)）/m) || [])[1] ?? N
 
 // ---- 闭环漏斗（2026-10-02 ledger-funnel-metrics 立法）----
 // 只读台账一手字段（doc/stage/ts/source），坏行跳过（与检查 15/19 同容错）；观测面不挂门禁、不新增文档断言（检查 16 零接触）。
-const LEDGER_P = path.join('.agents', 'confirmations.jsonl');
+// 台账读取收敛 ledger-loader 单源（2026-10-12 ledger-loader-p1）——口径不变（只读一手字段 doc/stage/ts/source、
+// 坏行跳过，与检查 15/19 同容错）。**本步刻意保留「全量行不去重」**：去重会改漏斗 ledgerRows 计数口径，
+// 属口径变更，须随分片功能同批生效，不得混入单源化本步。
 function readLedgerRows() {
-  if (!fs.existsSync(LEDGER_P)) return [];
-  return fs.readFileSync(LEDGER_P, 'utf8').split(/\r?\n/)
-    .map((l) => { try { return JSON.parse(l); } catch { return null; } })
-    .filter((e) => e && typeof e === 'object');
+  return loadLedgerRows();
 }
 
 function funnelFromLedger(entries, month) {

package/templates/_agents/scripts/git-merge-jsonl.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// git-merge-jsonl.mjs — Git 自定义合并驱动：JSONL 追加式台账并集去重（2026-10-12 ledger-merge-driver）
+// 解决什么：确认台账 `.agents/confirmations.jsonl` 是「尾部追加 + 多人/多 worktree 并行」形态。
+//   两个分支各自追加行 → 同一文件末尾分叉 → git 默认三方合并把它当文本冲突，人工解且极易解错
+//   （常见错解：整取一侧，**静默丢掉另一侧的确认行**——门禁事后无从发现，人不可信面直接扩大）。
+//   本驱动把合并降级为确定性的**并集去重**：两侧行全保留，无冲突可解。
+//
+// 接线（两步，缺任一步则退化为文本冲突——不静默丢数据，但要人工解）：
+//   ① git config merge.jsonl-union.driver "node .agents/scripts/git-merge-jsonl.mjs %O %A %B"
+//   ② 目标仓 .gitattributes 含：.agents/*.jsonl merge=jsonl-union
+//   flow-kit init 会自动做 ①；②由 templates/.gitattributes 下发（**owned**——存量装户 sync 永不覆盖，
+//   需自行补一行，见 README 台账并发口径）。
+//
+// 调用协议（由 .gitattributes 关联 merge=jsonl-union 触发）：
+//   %O 祖先版本路径 ｜ %A 当前分支版本（合并结果必须覆写回此文件）｜ %B 对方分支版本
+//
+// **为什么 union 去重不会破坏台账哈希链**（ledgerChainHash 的前提，勿破坏）：
+//   去重按**整行文本**精确比对，不解析、不改写行内任何字段 → 合并后每行文本与合并前逐字相同
+//   → JSON.parse 保持键序 → ledgerChainHash(row) 重算结果不变。哈希链的**行内自洽**因此恒成立。
+//   （跨合并边界的**链首尾衔接**是另一回事，由链域改造承接，见 check-loop 检查 15。）
+import fs from 'node:fs';
+
+// mergeJsonlLines：并集去重。保持 current（%A）既有行的原始顺序，其余 other（%B）新行追加末尾。
+// 全部行按整行文本精确去重；CRLF 归一为 LF（台账判据与 check-ledger-invariant 的 blob 口径对齐）。
+export function mergeJsonlLines(currentContent, otherContent) {
+  const norm = (str) => (str || '').replace(/\r\n/g, '\n').split('\n').filter((l) => l.trim().length > 0);
+  const currentLines = norm(currentContent);
+  const otherLines = norm(otherContent);
+
+  const seen = new Set(currentLines);
+  const result = [...currentLines];
+  for (const line of otherLines) {
+    if (!seen.has(line)) { seen.add(line); result.push(line); }
+  }
+  return result.length > 0 ? result.join('\n') + '\n' : '';
+}
+
+// CLI 执行入口（isMain 守卫沿本仓惯例：被 import 时零副作用，供 compact-ledgers 复用本函数）
+const isMain = process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('git-merge-jsonl.mjs');
+if (isMain) {
+  // %O（祖先版本）本驱动用不到——并集去重只需 %A ∪ %B；保留位置占位以对齐 git 的 %O %A %B 调用协议
+  const [, , _ancestorPath, currentPath, otherPath] = process.argv;
+
+  if (!currentPath || !otherPath) {
+    console.error('用法：node git-merge-jsonl.mjs %O %A %B（由 .gitattributes 的 merge=jsonl-union 触发，不供手工调用）');
+    process.exit(1);
+  }
+
+  // 原子覆写：直接 writeFileSync 会先截断原文件，进程中途崩溃将留下半写文件——git 合并中途失败
+  // 正是最需要「要么旧要么新」的场合。改为同目录临时文件 + rename。
+  const tmpPath = `${currentPath}.tmp`;
+  try {
+    const currentContent = fs.existsSync(currentPath) ? fs.readFileSync(currentPath, 'utf8') : '';
+    const otherContent = fs.existsSync(otherPath) ? fs.readFileSync(otherPath, 'utf8') : '';
+    fs.writeFileSync(tmpPath, mergeJsonlLines(currentContent, otherContent), 'utf8');
+    fs.renameSync(tmpPath, currentPath);
+    process.exit(0);
+  } catch (err) {
+    try { fs.unlinkSync(tmpPath); } catch { /* tmp 可能尚未创建 */ }
+    console.error(`[git-merge-jsonl] 合并失败: ${err.message}——已保留原文件，git 将报为冲突（人工解，勿整取一侧丢行）`);
+    process.exit(1);
+  }
+}

package/templates/_agents/scripts/git-merge-jsonl.test.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// git-merge-jsonl.test.mjs — 台账并集合并驱动 fixture 套件（2026-10-12 ledger-merge-driver）
+// 覆盖：并集去重 / %A 行序保持 / %B 新行追加 / 空侧 / CRLF 归一 / 幂等 / CLI 原子覆写与失败码，
+//       以及**行内哈希重算不变**（union 不破坏台账哈希链的前提，见驱动头部注释）。
+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 SCRIPT = path.join(SCRIPT_DIR, 'git-merge-jsonl.mjs');
+const { mergeJsonlLines } = await import(pathToFileURL(SCRIPT).href);
+const { ledgerChainHash } = 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 L = (...xs) => xs.filter(Boolean).join('\n') + '\n';
+const r1 = L('{"ts":"1","doc":"a","stage":"approved"}', '{"ts":"2","doc":"a","stage":"done"}');
+const r2 = L('{"ts":"3","doc":"b","stage":"approved"}');
+const shared = L('{"ts":"9","doc":"c","stage":"approved"}');
+
+// ============ 场景 1：%A 独有 → 全保留，%A 顺序不变 ============
+{
+  const out = mergeJsonlLines(r1, '');
+  check('S1 %B 空时结果 == %A（字节级）', out === r1, JSON.stringify(out));
+}
+
+// ============ 场景 2：%B 有 %A 没有的新行 → 追加末尾 ============
+{
+  const out = mergeJsonlLines(r1, r2);
+  check('S2 %B 新行追加到末尾', out === r1 + r2, JSON.stringify(out));
+}
+
+// ============ 场景 3：共有行只留一份（去重） ============
+{
+  const out = mergeJsonlLines(r1 + shared, shared + r2);
+  const lines = out.trim().split('\n');
+  const cnt = lines.filter((l) => l === shared.trim()).length;
+  check('S3 共有行只保留一份', cnt === 1, `实得 ${cnt}`);
+  check('S3 %A 既有行顺序保持在前', lines[0].includes('"ts":"1"') && lines[1].includes('"ts":"2"'), JSON.stringify(lines));
+  check('S3 行数 = %A 行数 + %B 新增行数', lines.length === 4, `实得 ${lines.length}`);
+}
+
+// ============ 场景 4：双空 → 空串 ============
+{
+  check('S4 双空返回空串', mergeJsonlLines('', '') === '');
+  check('S4 null 视为空', mergeJsonlLines(null, null) === '');
+}
+
+// ============ 场景 5：CRLF 归一为 LF（与 check-ledger-invariant 的 blob 口径对齐） ============
+{
+  const out = mergeJsonlLines('{"ts":"1"}\r\n', '{"ts":"2"}\r\n');
+  check('S5 CRLF 归一为 LF', !out.includes('\r') && out === L('{"ts":"1"}', '{"ts":"2"}'), JSON.stringify(out));
+  check('S5 空行被剔除', mergeJsonlLines('{"ts":"1"}\n\n\n', '') === L('{"ts":"1"}'));
+}
+
+// ============ 场景 6：幂等——同输入重复合并结果不变（compact 重跑安全的前提） ============
+{
+  const once = mergeJsonlLines(r1, r2);
+  check('S6 重复合并幂等', mergeJsonlLines(once, r2) === once && mergeJsonlLines(r1, once) === once);
+}
+
+// ============ 场景 7【关键互证】：union 保留行文本 → 行内哈希重算不变 ============
+// 背景：台账哈希链 ledgerChainHash(row) = sha256(prevHash + JSON.stringify(row))，依赖 JSON.stringify
+//   的键序 = 写入序。union 按整行文本去重、不解析不改写 → 行文本逐字不变 → 键序不变 → 重算不变。
+//   这条一旦被破坏（例如将来有人改成「解析后重排键再序列化」），台账链会整片失效且极难排查。
+{
+  const mkRow = (prevHash, fields) => {
+    const row = { ...fields, prevHash };
+    return { ...row, hash: ledgerChainHash(fields, prevHash) };
+  };
+  const chained = [
+    JSON.stringify(mkRow('', { ts: '2026-10-01T00:00:00Z', doc: 'workflow/intents/a.md', stage: 'approved', fingerprint: 'a'.repeat(64), scope: { files: ['x.md'], sha256: 's' } })),
+    JSON.stringify(mkRow('PREVHASH', { ts: '2026-10-02T00:00:00Z', doc: 'workflow/intents/a.md', stage: 'done', fingerprint: 'a'.repeat(64) })),
+  ].join('\n') + '\n';
+  const mine = chained;
+  const theirs = L('{"ts":"2026-10-03T00:00:00Z","doc":"workflow/intents/b.md","stage":"approved","fingerprint":"b","extra":1}');
+  const merged = mergeJsonlLines(mine, theirs);
+  const rows = merged.trim().split('\n').map((l) => JSON.parse(l));
+  const selfOk = rows.every((r) => {
+    if (typeof r.hash !== 'string') return true; // 无链字段行（存量/注记）不参与
+    const { hash, prevHash, ...rest } = r;
+    return ledgerChainHash(rest, prevHash ?? '') === hash;
+  });
+  check('S7 合并后每行行内哈希仍可重算一致', selfOk, JSON.stringify(rows));
+  check('S7 合并后行文本与合并前逐字相同（去重不改写字段）',
+    merged.trim().split('\n')[0] === mine.trim().split('\n')[0]);
+}
+
+// ============ 场景 8：CLI 真跑 —— 覆写 %A、exit 0、无残留 .tmp ============
+{
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'jsonl-merge-'));
+  const A = path.join(d, 'A'), B = path.join(d, 'B'), O = path.join(d, 'O');
+  fs.writeFileSync(A, r1, 'utf8');
+  fs.writeFileSync(B, r1 + r2, 'utf8');
+  fs.writeFileSync(O, L(), 'utf8');
+  const r = spawnSync(process.execPath, [SCRIPT, O, A, B], { encoding: 'utf8' });
+  check('S8 CLI exit 0', r.status === 0, `exit=${r.status} ${r.stderr || ''}`);
+  check('S8 CLI 结果写入 %A', fs.readFileSync(A, 'utf8') === r1 + r2, JSON.stringify(fs.readFileSync(A, 'utf8')));
+  check('S8 无残留 .tmp', !fs.existsSync(`${A}.tmp`));
+  // 缺参数 → 用法提示 + exit 1（driver 由 git 触发，参数缺失属接线错误，应响亮）
+  const bad = spawnSync(process.execPath, [SCRIPT, O], { encoding: 'utf8' });
+  check('S8 缺参数 exit 1 且出用法', bad.status === 1 && bad.stderr.includes('用法'), `exit=${bad.status}`);
+  fs.rmSync(d, { recursive: true, force: true });
+}
+
+// ============ 场景 9：%A 不存在（对侧新增文件）→ 以 %B 内容落盘 ============
+{
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'jsonl-merge2-'));
+  const A = path.join(d, 'A'), B = path.join(d, 'B'), O = path.join(d, 'O');
+  fs.writeFileSync(B, r2, 'utf8');
+  fs.writeFileSync(O, L(), 'utf8');
+  const r = spawnSync(process.execPath, [SCRIPT, O, A, B], { encoding: 'utf8' });
+  check('S9 %A 缺失时以 %B 落盘且 exit 0', r.status === 0 && fs.readFileSync(A, 'utf8') === r2,
+    `exit=${r.status} ${r.stderr || ''}`);
+  fs.rmSync(d, { recursive: true, force: true });
+}
+
+console.log(`\n[git-merge-jsonl.test] PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 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;
+}