agentic-flow-kit 1.7.15 → 1.8.0

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

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+// ledger-shards.mjs — 三个 append-only 台账的分片读写单源（2026-10-13 ledger-shard-ledgers，自源仓回灌）
+//
+// 背景：workflow/{regression-checklist,delegations,papercuts}.md 是 append-only 活文档，每次追加
+// 全量重写整文件——源仓实测 blob 膨胀（regression-checklist 单文件 14.0 MiB、delegations 11.5 MiB，
+// 膨胀/冲突实测数据出处留痕在包源仓 git 历史与 CHANGELOG），且多 worktree 并行时每次合并都可能冲突。
+//
+// 分片形态（沿 confirmations.d 先例，2026-10-12 ledger-shard-default）：
+//   workflow/<ledger>.d/<YYYY-MM>.md —— 按月切分，每月一个文件
+// 读侧 = 主台账 ∪ 全部分片（按文件名排序，月序即时间序）；写侧 = 追加进当月分片。
+// 主台账保留「头部说明 + 维护规则 + 表头」等人类阅读面，数据行迁入分片。
+//
+// 为什么按月而非按条目：三个台账的数据行天然带日期列（首列 YYYY-MM-DD），月边界即天然分片键；
+// 同月并发追加落同一文件（冲突面从「全历史」缩到「当月」），跨月并发零冲突。
+//
+// 合并驱动：.gitattributes 的 merge=jsonl-union 只覆盖 .agents/*.jsonl；本模块的 .md 分片走
+// 追加式表格行，冲突面已由月切分压到最小，不另配驱动（如需可后续加 merge=union）。
+//
+// kit 适配（源仓→kit，2026-10-13 B8 批）：表头签名对齐 kit 模板形态——delegations 两表末列为
+// 「合入结论」（源仓为「返工原因」）、regression-checklist 表头为「incident | 条目 | 落点」
+// （源仓为「来源 incident | 回归条目 | 落点」）。数据行判据不变（首列日期即数据行），表头签名
+// 只进分片渲染。分片仍带节标题：kit 侧 wf-journal.delegationSectionRows 按 `## 委派结果` 节门
+// 读行（kit check-loop 检查 18 走表头签名、不依赖节标题——与源仓相反；节标题 + 表头都带则两边读侧全兼容）。
+//
+// 用法（库）：
+//   import { readLedger, shardPathFor, appendRows } from './ledger-shards.mjs';
+//   const { main, shards, all } = readLedger(root, 'delegations');
+// 用法（CLI，迁移/巡检/追加）：
+//   node .agents/scripts/ledger-shards.mjs --check          # 巡检：主台账残留数据行 / 分片可读性
+//   node .agents/scripts/ledger-shards.mjs --split <ledger> # 把主台账数据行按月迁入分片（幂等）
+//   node .agents/scripts/ledger-shards.mjs --append <ledger> --row "<行>" [--month YYYY-MM]
+// 测试：node .agents/scripts/ledger-shards.test.mjs
+import fs from 'node:fs';
+import path from 'node:path';
+
+// 受管台账清单（单源）：键 = 台账基名，值 = 数据行判定
+// - 表格式台账（delegations/papercuts）：整文件数据行按月迁出
+// - 分节台账（regression-checklist）：只有「防复发验证」节是 append-only 追加区（incident 追加区），
+//   其余模块节是稳定参考内容——故用 section 限定，只迁该节的数据行
+export const LEDGERS = {
+  'regression-checklist': {
+    section: '防复发验证', // 只迁此节内的数据行（节标题前缀匹配）
+    row: /^\s*\|\s*\d{4}-\d{2}-\d{2}/, // 表格式：首列日期
+  },
+  delegations: {
+    row: /^\s*\|\s*\d{4}-\d{2}-\d{2}/,
+  },
+  papercuts: {
+    row: /^\s*\|\s*\d{4}-\d{2}-\d{2}/,
+  },
+};
+
+// 表格式台账的表头签名（分片须自带表头——读侧按表头识别数据边界，见 agg-delegations.splitTables）。
+// delegations 有两张表（委派表 / 自做表），分片须两张都带且行归入正确表下。
+// **归属判据 = 原节标题**（`## 委派结果` / `## 自做任务结果`），不用列数——末列「合入结论」可缺省、
+// 存量行不回填，两表都可能出现 5 列行，列数无法区分两表。
+// **分片须同时带节标题**：kit 读侧 wf-journal.delegationSectionRows 要求行落在 `## 委派结果`
+// 节内（节门）；只带表头会让 wf-journal 读到 0 行。kit check-loop 检查 18 与
+// agg-delegations.splitTables 走表头签名（节标题只服务人类阅读）——节标题 + 表头都带则两边读侧全兼容。
+const TABLE_HEADERS = {
+  delegations: [
+    { section: '委派结果', header: ['## 委派结果', '', '| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 | 合入结论 |', '|------|----------------|------------|------|------|----------|'] },
+    { section: '自做任务结果', header: ['## 自做任务结果', '', '| 日期 | 任务一句话 | 结果 | 备注 | 合入结论 |', '|------|------------|------|------|----------|'] },
+  ],
+  papercuts: [
+    { section: null, header: ['| 日期 | 位置 | 症状 | 拟修 |', '|------|------|------|------|'] },
+  ],
+  'regression-checklist': [
+    { section: null, header: ['| incident | 条目 | 落点 |', '|----------|------|------|'] },
+  ],
+};
+
+// tableIndexOf(name, line, section)：该行属于哪张表。
+// 多表台账（delegations）按**原节标题**归属（列数不可靠，见 TABLE_HEADERS 注释）；
+// 单表台账恒 0。section 为行所在节的标题（调用方按 `## ` 滚动维护）。
+function tableIndexOf(name, line, section = '') {
+  const specs = TABLE_HEADERS[name];
+  if (!specs || specs.length === 1) return 0;
+  for (let i = 0; i < specs.length; i++) {
+    if (specs[i].section && String(section).startsWith(specs[i].section)) return i;
+  }
+  return 0; // 无节信息（旧分片/裸行）→ 归首表（委派表），沿原主台账行序语义
+}
+
+export function ledgerPath(root, name) {
+  return path.join(root, 'workflow', `${name}.md`);
+}
+
+export function shardDir(root, name) {
+  return path.join(root, 'workflow', `${name}.d`);
+}
+
+export function shardPathFor(root, name, month) {
+  return path.join(shardDir(root, name), `${month}.md`);
+}
+
+// monthOf(line)：从数据行提取分片月（YYYY-MM）。表格式取首列日期；清单式无日期 → 返回 ''（调用方兜底）。
+export function monthOf(name, line) {
+  const m = /(\d{4})-(\d{2})-\d{2}/.exec(line);
+  return m ? `${m[1]}-${m[2]}` : '';
+}
+
+// isDataRow(name, line)：该行是否属于「应迁入分片」的数据行（不含节上下文）。
+export function isDataRow(name, line) {
+  const spec = LEDGERS[name];
+  if (!spec) return false;
+  if (!spec.row.test(line)) return false;
+  // 表头/分隔行排除
+  if (/^\s*\|/.test(line)) {
+    const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+    if (!cells.length || cells.every((c) => /^[-: ]*$/.test(c))) return false;
+    if (cells[0] === '日期' || cells[0] === '来源 incident' || cells[0] === 'incident') return false;
+  }
+  return true;
+}
+
+// inScope(name, section)：当前节是否属于该台账的迁移范围（无 section 限定 → 恒 true）。
+export function inScope(name, section) {
+  const spec = LEDGERS[name];
+  if (!spec || !spec.section) return true;
+  return String(section).startsWith(spec.section);
+}
+
+// readLedger(root, name)：主台账 ∪ 全部分片。返回 { main, shards: [{file, text}], all }。
+// 分片按文件名排序（月序 = 时间序）；读失败 fail-loud（指标缺数会喂错门禁，沿 agg-delegations 口径）。
+export function readLedger(root, name) {
+  const mainP = ledgerPath(root, name);
+  let main = '';
+  if (fs.existsSync(mainP)) {
+    try { main = fs.readFileSync(mainP, 'utf8'); }
+    catch (err) { throw new Error(`台账读取失败: ${mainP} (${err.message})`); }
+  }
+  const dir = shardDir(root, name);
+  const shards = [];
+  if (fs.existsSync(dir) && fs.statSync(dir).isDirectory()) {
+    let files;
+    try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort(); }
+    catch (err) { throw new Error(`分片目录遍历失败: ${dir} (${err.message})`); }
+    for (const f of files) {
+      const p = path.join(dir, f);
+      try { shards.push({ file: f, text: fs.readFileSync(p, 'utf8') }); }
+      catch (err) { throw new Error(`分片读取失败: ${f} (${err.message})`); }
+    }
+  }
+  const all = [main, ...shards.map((s) => s.text)].join('\n');
+  return { main, shards, all };
+}
+
+// readLedgerText(root, name)：便捷形态——只要合并文本（读侧最小改动接入点）。
+export function readLedgerText(root, name) {
+  return readLedger(root, name).all;
+}
+
+// readDelegationsText(root, file)：delegations 合并文本（主台账 ∪ delegations.d/*.md）。
+// 供读侧消费者共用（单源，禁各自拼路径）：
+//   - agg-delegations.splitTables（表头签名识别）
+//   - check-loop.delegationResultRows（表头签名识别，检查 18）
+//   - wf-journal.delegationSectionRows（`## 委派结果` 节门）
+// file 语义：**仅当它不是本仓默认主台账路径时**才作显式覆盖（测试注入临时文件用）；
+// 传默认路径（消费者按 `path.join(ROOT,'workflow','delegations.md')` 拼出来的）→ 走分片合并，
+// 否则分片被静默跳过（2026-10-13 源仓实测踩中：检查 18 读到 0 行）。
+export function readDelegationsText(root, file = null) {
+  const def = ledgerPath(root, 'delegations');
+  if (file && path.resolve(file) !== path.resolve(def)) {
+    try { return fs.readFileSync(file, 'utf8'); } catch { return ''; }
+  }
+  try { return readLedgerText(root, 'delegations'); } catch { return ''; }
+}
+
+// splitMain(root, name, { dryRun })：把主台账里的数据行按月迁入分片（幂等：已迁走的行不再出现）。
+// 返回 { moved: {month: count}, kept: 主台账保留行数 }。主台账保留非数据行（说明/规则/表头/生成区）。
+export function splitMain(root, name, { dryRun = false } = {}) {
+  const mainP = ledgerPath(root, name);
+  if (!fs.existsSync(mainP)) throw new Error(`台账不存在: ${mainP}`);
+  const raw = fs.readFileSync(mainP, 'utf8');
+  const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+  const lines = raw.split(/\r?\n/);
+  const kept = [];
+  const byMonth = new Map();
+  let section = '';
+  for (const line of lines) {
+    const h = /^##\s+(.+?)\s*$/.exec(line);
+    if (h) section = h[1];
+    if (!inScope(name, section) || !isDataRow(name, line)) { kept.push(line); continue; }
+    const month = monthOf(name, line);
+    if (!month) { kept.push(line); continue; } // 无日期行不迁
+    if (!byMonth.has(month)) byMonth.set(month, []);
+    byMonth.get(month).push({ line, section }); // 带节信息（多表台账按节归属表）
+  }
+  const moved = {};
+  for (const [month, rows] of byMonth) moved[month] = rows.length;
+  if (dryRun) return { moved, kept: kept.length, byMonth };
+  // 写分片：已存在的分片保留原内容，新行追加——**按行去重**（幂等：重跑不重复追加）。
+  // 2026-10-13 源仓实测踩中：无去重时二次 split 把 58 行重复写入（120 行 vs 62 行）。
+  for (const [month, rows] of byMonth) {
+    const p = shardPathFor(root, name, month);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
+    const existingRows = new Set(existing.split(/\r?\n/).filter((l) => l.trim()));
+    const fresh = rows.filter((r) => !existingRows.has(r.line));
+    if (!fresh.length) continue; // 全部已在分片 → 不写（幂等）
+    const next = existing
+      ? `${existing.replace(/\s*$/, '')}${eol}${fresh.map((r) => r.line).join(eol)}${eol}`
+      : renderShard(name, fresh, eol);
+    fs.writeFileSync(p, next, 'utf8');
+  }
+  // 主台账：保留行 + 尾部空行规整
+  const out = kept.join(eol).replace(/(\r?\n)+$/, '') + eol;
+  fs.writeFileSync(mainP, out, 'utf8');
+  return { moved, kept: kept.length };
+}
+
+// renderShard(name, rows, eol)：完整分片内容 = 表头 + 行（行归入各自表头之下）。
+// 多表台账（delegations）必须逐表「表头 + 该表行」交错输出——否则读侧 splitTables 会把
+// 后一张表的行按前一张表解析（2026-10-13 源仓实测：240 任务塌成 100）。
+// rows 项 = { line, section }（section 为原节标题，用于表归属）；rows 为空 → 出全部表头（空分片骨架）。
+export function renderShard(name, rows, eol = '\n') {
+  const specs = TABLE_HEADERS[name];
+  if (!specs) return rows.length ? `${rows.map((r) => r.line ?? r).join(eol)}${eol}` : '';
+  const out = [];
+  for (let i = 0; i < specs.length; i++) {
+    const mine = rows.filter((r) => tableIndexOf(name, r.line ?? r, r.section) === i);
+    if (rows.length && !mine.length) continue; // 有行但本表无行 → 不出空表头
+    out.push(...specs[i].header, ...mine.map((r) => r.line ?? r));
+  }
+  return out.length ? `${out.join(eol)}${eol}` : '';
+}
+
+// appendRows(root, name, rows, { month, section })：把数据行追加进指定月分片（缺省取行内日期月）。
+// rows 可为字符串数组或 { line, section } 数组（多表台账须带 section 才能归对表）。
+// 返回实际写入的分片路径列表。写失败 fail-loud（不静默吞）。
+export function appendRows(root, name, rows, { month, section = '' } = {}) {
+  const written = [];
+  const byMonth = new Map();
+  for (const row of rows) {
+    const line = typeof row === 'string' ? row : row.line;
+    const sec = typeof row === 'string' ? section : (row.section ?? section);
+    const m = month || monthOf(name, line);
+    if (!m) throw new Error(`appendRows: 无法确定分片月（行无日期且未传 month）: ${String(line).slice(0, 80)}`);
+    if (!byMonth.has(m)) byMonth.set(m, []);
+    byMonth.get(m).push({ line, section: sec });
+  }
+  for (const [m, rs] of byMonth) {
+    const p = shardPathFor(root, name, m);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
+    const existingRows = new Set(existing.split(/\r?\n/).filter((l) => l.trim()));
+    const fresh = rs.filter((r) => !existingRows.has(r.line));
+    if (!fresh.length) { written.push(p); continue; } // 已在分片 → 幂等跳过
+    const next = existing
+      ? `${existing.replace(/\s*$/, '')}\n${fresh.map((r) => r.line).join('\n')}\n`
+      : renderShard(name, fresh, '\n');
+    fs.writeFileSync(p, next, 'utf8');
+    written.push(p);
+  }
+  return written;
+}
+
+// ---- CLI：巡检 / 迁移 / 追加 ----
+function main() {
+  const argv = process.argv.slice(2);
+  const root = process.cwd();
+  if (argv.includes('--check')) {
+    let bad = 0;
+    for (const name of Object.keys(LEDGERS)) {
+      const mainP = ledgerPath(root, name);
+      if (!fs.existsSync(mainP)) { console.log(`[skip] ${name}: 主台账不存在`); continue; }
+      const lines = fs.readFileSync(mainP, 'utf8').split(/\r?\n/);
+      const residual = lines.filter((l) => isDataRow(name, l)).length;
+      let shardRows = 0;
+      try {
+        const { shards } = readLedger(root, name);
+        for (const s of shards) shardRows += s.text.split(/\r?\n/).filter((l) => isDataRow(name, l)).length;
+      } catch (err) { console.error(`[FAIL] ${name}: ${err.message}`); bad++; continue; }
+      console.log(`[${residual ? 'WARN' : 'OK'}] ${name}: 主台账残留数据行 ${residual}｜分片数据行 ${shardRows}`);
+      if (residual) bad++;
+    }
+    process.exit(bad ? 1 : 0);
+  }
+  const splitIdx = argv.indexOf('--split');
+  if (splitIdx >= 0) {
+    const name = argv[splitIdx + 1];
+    if (!LEDGERS[name]) { console.error(`--split 须指定台账名（${Object.keys(LEDGERS).join('|')}）`); process.exit(2); }
+    const dry = argv.includes('--dry-run');
+    const r = splitMain(root, name, { dryRun: dry });
+    console.log(`${dry ? '[dry] ' : ''}${name}: 迁出 ${Object.values(r.moved).reduce((a, b) => a + b, 0)} 行 → ${JSON.stringify(r.moved)}｜主台账保留 ${r.kept} 行`);
+    return;
+  }
+  // --append <ledger> --row "<行>" [--month YYYY-MM]：追加一行进当月分片（写侧唯一入口）
+  const appIdx = argv.indexOf('--append');
+  if (appIdx >= 0) {
+    const name = argv[appIdx + 1];
+    if (!LEDGERS[name]) { console.error(`--append 须指定台账名（${Object.keys(LEDGERS).join('|')}）`); process.exit(2); }
+    const rowIdx = argv.indexOf('--row');
+    const row = rowIdx >= 0 ? argv[rowIdx + 1] : '';
+    if (!row) { console.error('--append 须带 --row "<数据行>"'); process.exit(2); }
+    const mIdx = argv.indexOf('--month');
+    const month = mIdx >= 0 ? argv[mIdx + 1] : undefined;
+    const written = appendRows(root, name, [row], { month });
+    console.log(`✓ 追加 1 行 → ${written.map((p) => path.relative(root, p).split(path.sep).join('/')).join(', ')}`);
+    return;
+  }
+  console.error('用法：node .agents/scripts/ledger-shards.mjs --check | --split <ledger> [--dry-run] | --append <ledger> --row "<行>" [--month YYYY-MM]');
+  process.exit(2);
+}
+
+if (process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('ledger-shards.mjs')) main();

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

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+// ledger-shards.test.mjs — 分片读写单源 fixture（2026-10-13 ledger-shard-ledgers，自源仓回灌）
+// 覆盖：数据行判定（含节限定）/ 月提取 / 主台账∪分片读 / 迁移幂等 / 追加 / 表头自带 / fail-loud
+// kit 适配：表头签名用 kit 模板形态（delegations 末列「合入结论」、regression-checklist「incident | 条目 | 落点」）；
+//   S22 钉住 kit 适配（分片渲染须出 kit 表头、不出源仓表头——防再同步漂移）。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  LEDGERS, isDataRow, inScope, monthOf, readLedger, readLedgerText,
+  splitMain, appendRows, shardPathFor, renderShard,
+} from './ledger-shards.mjs';
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS ${desc}`); }
+  else { fail++; console.log(`FAIL ${desc}${detail ? '\n  ' + detail : ''}`); }
+};
+const mkroot = () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ledger-shards-'));
+  fs.mkdirSync(path.join(root, 'workflow'), { recursive: true });
+  return root;
+};
+const wf = (root, ...p) => path.join(root, 'workflow', ...p);
+
+// ---- S1 数据行判定：表格式（delegations/papercuts）----
+{
+  check('S1a delegations 数据行命中', isDataRow('delegations', '| 2026-10-01 | ui-verifier | 任务 | 一次通过 | 备注 |'));
+  check('S1b delegations 表头排除', !isDataRow('delegations', '| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 | 合入结论 |'));
+  check('S1c delegations 分隔行排除', !isDataRow('delegations', '|------|----------------|------------|------|------|----------|'));
+  check('S1d papercuts 数据行命中', isDataRow('papercuts', '| 2026-10-11 | `.agents/x.mjs` | 症状 | 拟修 |'));
+  check('S1e papercuts 表头排除', !isDataRow('papercuts', '| 日期 | 位置 | 症状 | 拟修 |'));
+  check('S1f 说明行不命中', !isDataRow('papercuts', '> 说明文字，非数据行'));
+}
+
+// ---- S2 节限定：regression-checklist 只迁「防复发验证」节 ----
+{
+  check('S2a 防复发验证节在范围内', inScope('regression-checklist', '防复发验证'));
+  check('S2b 模块节不在范围内', !inScope('regression-checklist', '回归必过'));
+  check('S2c 无 section 限定的台账恒在范围', inScope('delegations', '任意节') && inScope('papercuts', ''));
+  check('S2d 防复发数据行命中', isDataRow('regression-checklist', '| 2026-09-11 某事故 | 条目 | 落点 |'));
+  check('S2e 防复发表头排除', !isDataRow('regression-checklist', '| incident | 条目 | 落点 |'));
+}
+
+// ---- S3 月提取 ----
+{
+  check('S3a 表格式取首列日期月', monthOf('delegations', '| 2026-10-01 | x |') === '2026-10');
+  check('S3b 无日期返回空', monthOf('delegations', '| 无日期 | x |') === '');
+}
+
+// ---- S4 读：主台账 ∪ 分片 ----
+{
+  const root = mkroot();
+  fs.mkdirSync(wf(root, 'papercuts.d'), { recursive: true });
+  fs.writeFileSync(wf(root, 'papercuts.md'), '# 台账\n\n| 日期 | 位置 | 症状 | 拟修 |\n|------|------|------|------|\n| 2026-10-01 | 主表行 | s | f |\n', 'utf8');
+  fs.writeFileSync(wf(root, 'papercuts.d', '2026-09.md'), renderShard('papercuts', []) + '| 2026-09-01 | 分片行 | s | f |\n', 'utf8');
+  const r = readLedger(root, 'papercuts');
+  check('S4a 主台账 + 分片都读到', r.main.includes('主表行') && r.shards.length === 1 && r.all.includes('分片行'));
+  check('S4b all 含两侧', r.all.includes('主表行') && r.all.includes('分片行'));
+  check('S4c readLedgerText 等价 all', readLedgerText(root, 'papercuts') === r.all);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S5 读：分片按文件名排序（月序 = 时间序）----
+{
+  const root = mkroot();
+  fs.mkdirSync(wf(root, 'papercuts.d'), { recursive: true });
+  fs.writeFileSync(wf(root, 'papercuts.md'), '# 台账\n', 'utf8');
+  fs.writeFileSync(wf(root, 'papercuts.d', '2026-10.md'), '| 2026-10-01 | 十月 | s | f |\n', 'utf8');
+  fs.writeFileSync(wf(root, 'papercuts.d', '2026-09.md'), '| 2026-09-01 | 九月 | s | f |\n', 'utf8');
+  const r = readLedger(root, 'papercuts');
+  check('S5 分片按文件名排序（09 在 10 前）', r.shards[0].file === '2026-09.md' && r.shards[1].file === '2026-10.md');
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S6 读：无分片目录 → 等价原读法（向后兼容）----
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'papercuts.md'), '# 台账\n| 2026-10-01 | 行 | s | f |\n', 'utf8');
+  const r = readLedger(root, 'papercuts');
+  check('S6 无分片目录 → shards 空、all = main', r.shards.length === 0 && r.all === r.main);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S7 迁移：主台账数据行按月迁出，非数据行保留 ----
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'papercuts.md'), [
+    '# 台账', '', '> 说明', '',
+    '| 日期 | 位置 | 症状 | 拟修 |', '|------|------|------|------|',
+    '| 2026-09-01 | 九月行 | s | f |',
+    '| 2026-10-01 | 十月行 | s | f |',
+    '| 2026-10-02 | 十月行2 | s | f |', '',
+  ].join('\n'), 'utf8');
+  const r = splitMain(root, 'papercuts');
+  check('S7a 迁移计数正确', r.moved['2026-09'] === 1 && r.moved['2026-10'] === 2, JSON.stringify(r.moved));
+  const main = fs.readFileSync(wf(root, 'papercuts.md'), 'utf8');
+  check('S7b 主台账保留说明与表头、无数据行', main.includes('# 台账') && main.includes('| 日期 |') && !main.includes('九月行') && !main.includes('十月行'));
+  check('S7c 分片自带表头', fs.readFileSync(wf(root, 'papercuts.d', '2026-09.md'), 'utf8').includes('| 日期 | 位置 | 症状 | 拟修 |'));
+  check('S7d 分片含数据行', fs.readFileSync(wf(root, 'papercuts.d', '2026-10.md'), 'utf8').includes('十月行2'));
+  // 迁移后读回：数据不丢
+  const back = readLedgerText(root, 'papercuts');
+  check('S7e 迁移后读回数据完整', back.includes('九月行') && back.includes('十月行') && back.includes('十月行2'));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S8 迁移幂等：二次 split 无数据行可迁 ----
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'papercuts.md'), '| 日期 | 位置 | 症状 | 拟修 |\n|------|------|------|------|\n| 2026-10-01 | 行 | s | f |\n', 'utf8');
+  splitMain(root, 'papercuts');
+  const r2 = splitMain(root, 'papercuts');
+  check('S8 二次迁移 0 行（幂等）', Object.keys(r2.moved).length === 0, JSON.stringify(r2.moved));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S9 节限定迁移：regression-checklist 只迁防复发节 ----
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'regression-checklist.md'), [
+    '# 回归清单', '',
+    '## 回归必过', '',
+    '| 模块 | 条目 | 依据 |', '|------|------|------|',
+    '| 模块条目（不迁） | x | y |', '',
+    '## 防复发验证', '',
+    '| incident | 条目 | 落点 |', '|----------|------|------|',
+    '| 2026-09-11 某事故 | 条目 | 落点 |', '',
+  ].join('\n'), 'utf8');
+  const r = splitMain(root, 'regression-checklist');
+  check('S9a 只迁防复发节 1 行', r.moved['2026-09'] === 1, JSON.stringify(r.moved));
+  const main = fs.readFileSync(wf(root, 'regression-checklist.md'), 'utf8');
+  check('S9b 模块节条目留守', main.includes('| 模块条目（不迁） | x | y |'));
+  check('S9c 防复发数据行已迁出', !main.includes('2026-09-11 某事故'));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S10 appendRows：追加进指定月分片，缺表头则补 ----
+{
+  const root = mkroot();
+  appendRows(root, 'papercuts', ['| 2026-10-13 | 新行 | s | f |']);
+  const p = shardPathFor(root, 'papercuts', '2026-10');
+  check('S10a 分片文件已建', fs.existsSync(p));
+  const txt = fs.readFileSync(p, 'utf8');
+  check('S10b 自带表头 + 数据行', txt.includes('| 日期 | 位置 | 症状 | 拟修 |') && txt.includes('新行'));
+  appendRows(root, 'papercuts', ['| 2026-10-14 | 第二行 | s | f |']);
+  const txt2 = fs.readFileSync(p, 'utf8');
+  check('S10c 二次追加不重复表头', (txt2.match(/\| 日期 \| 位置/g) || []).length === 1 && txt2.includes('第二行'));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S11 appendRows：显式 month 覆盖（无日期行）----
+{
+  const root = mkroot();
+  appendRows(root, 'papercuts', ['| 无日期行 | s | f |'], { month: '2026-10' });
+  check('S11 显式 month 生效', fs.existsSync(shardPathFor(root, 'papercuts', '2026-10')));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S12 fail-loud：无法确定月 → 抛（不静默吞）----
+{
+  const root = mkroot();
+  let thrown = null;
+  try { appendRows(root, 'papercuts', ['| 无日期行 | s | f |']); } catch (e) { thrown = e; }
+  check('S12 无日期且未传 month → 抛错', thrown !== null && /无法确定分片月/.test(thrown.message));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S13 fail-loud：分片目录读取异常 → 抛 ----
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'papercuts.md'), '# 台账\n', 'utf8');
+  fs.mkdirSync(wf(root, 'papercuts.d'), { recursive: true });
+  fs.mkdirSync(wf(root, 'papercuts.d', 'bad.md')); // 目录冒充分片 → readFileSync EISDIR
+  let thrown = null;
+  try { readLedger(root, 'papercuts'); } catch (e) { thrown = e; }
+  check('S13 分片读失败 → 抛（不静默吞）', thrown !== null && /分片读取失败/.test(thrown.message));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S14 台账清单单源：三个台账都在册 ----
+{
+  check('S14 三台账在册', Object.keys(LEDGERS).sort().join(',') === 'delegations,papercuts,regression-checklist');
+}
+
+// ---- S15 delegations 双表分组：分片须两张表头都带且行归入正确表 ----
+// （2026-10-13 源仓迁移实测踩中：只带一张表头 → splitTables 把另一张的行按错表解析，240 任务塌成 100）
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'delegations.md'), [
+    '# 台账', '',
+    '## 委派结果', '',
+    '| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 | 合入结论 |',
+    '|------|----------------|------------|------|------|----------|',
+    '| 2026-09-01 | ui-verifier | 委派任务 | 一次通过 | 备注 | |',
+    '',
+    '## 自做任务结果', '',
+    '| 日期 | 任务一句话 | 结果 | 备注 | 合入结论 |',
+    '|------|------------|------|------|----------|',
+    '| 2026-09-02 | 自做任务 | 一次通过 | 备注 | |',
+    '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'delegations');
+  const shard = fs.readFileSync(wf(root, 'delegations.d', '2026-09.md'), 'utf8');
+  check('S15a 分片含委派表头（kit 形态）', shard.includes('| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 | 合入结论 |'));
+  check('S15b 分片含自做表头（kit 形态）', shard.includes('| 日期 | 任务一句话 | 结果 | 备注 | 合入结论 |'));
+  // 委派行须在委派表头之后、自做表头之前
+  const iDeleg = shard.indexOf('被委派方(模型)');
+  const iSelf = shard.indexOf('| 日期 | 任务一句话');
+  const iRow = shard.indexOf('委派任务');
+  check('S15c 委派行归入委派表（表头之后、自做表头之前）', iDeleg < iRow && iRow < iSelf, `deleg=${iDeleg} row=${iRow} self=${iSelf}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S16 renderShard 分组：有行时不出空表头 ----
+{
+  const onlyDeleg = renderShard('delegations', [{ line: '| 2026-09-01 | a | b | c | d | e |', section: '委派结果' }]);
+  check('S16a 只有委派行 → 不出自做表头', onlyDeleg.includes('被委派方(模型)') && !onlyDeleg.includes('| 日期 | 任务一句话'));
+  const onlySelf = renderShard('delegations', [{ line: '| 2026-09-01 | b | c | d | e |', section: '自做任务结果' }]);
+  check('S16b 只有自做行 → 不出委派表头', !onlySelf.includes('被委派方(模型)') && onlySelf.includes('| 日期 | 任务一句话'));
+  const empty = renderShard('delegations', []);
+  check('S16c 无行 → 出全部表头（空分片骨架）', empty.includes('被委派方(模型)') && empty.includes('| 日期 | 任务一句话'));
+}
+
+// ---- S17 幂等：分片已存在时重跑 split 不重复追加 ----
+// （2026-10-13 源仓实测踩中：无去重时二次 split 把 58 行重复写入，120 行 vs 62 行）
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'papercuts.md'), [
+    '| 日期 | 位置 | 症状 | 拟修 |', '|------|------|------|------|',
+    '| 2026-09-01 | 行A | s | f |',
+    '| 2026-09-02 | 行B | s | f |', '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'papercuts');
+  const after1 = fs.readFileSync(wf(root, 'papercuts.d', '2026-09.md'), 'utf8');
+  // 模拟「主台账被还原后重跑」（分片仍在）
+  fs.writeFileSync(wf(root, 'papercuts.md'), [
+    '| 日期 | 位置 | 症状 | 拟修 |', '|------|------|------|------|',
+    '| 2026-09-01 | 行A | s | f |',
+    '| 2026-09-02 | 行B | s | f |', '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'papercuts');
+  const after2 = fs.readFileSync(wf(root, 'papercuts.d', '2026-09.md'), 'utf8');
+  check('S17 重跑 split 不重复追加（幂等）', after1 === after2, `len1=${after1.length} len2=${after2.length}`);
+  const rows = after2.split(/\r?\n/).filter((l) => /^\| 20/.test(l));
+  check('S17b 行数仍为 2', rows.length === 2, `rows=${rows.length}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S18 appendRows 幂等：同行走两次只落一次 ----
+{
+  const root = mkroot();
+  appendRows(root, 'papercuts', ['| 2026-10-13 | 同行 | s | f |']);
+  appendRows(root, 'papercuts', ['| 2026-10-13 | 同行 | s | f |']);
+  const txt = fs.readFileSync(shardPathFor(root, 'papercuts', '2026-10'), 'utf8');
+  const rows = txt.split(/\r?\n/).filter((l) => /^\| 20/.test(l));
+  check('S18 同行走两次只落一次', rows.length === 1, `rows=${rows.length}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S19 嵌入 `|` 的行不丢（2026-10-13 源仓实测踩中：4 行因列数虚高被 renderShard 丢弃）----
+{
+  const root = mkroot();
+  const weird = '| 2026-09-17 | `.agents/x.mjs` | 正则 `[:=]\\s*["\']?` 含字面竖线 | 拟修 |';
+  fs.writeFileSync(wf(root, 'papercuts.md'), [
+    '| 日期 | 位置 | 症状 | 拟修 |', '|------|------|------|------|',
+    '| 2026-09-01 | 正常行 | s | f |',
+    weird, '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'papercuts');
+  const shard = fs.readFileSync(wf(root, 'papercuts.d', '2026-09.md'), 'utf8');
+  check('S19a 嵌入竖线的行不丢', shard.includes('含字面竖线'), shard.slice(0, 200));
+  check('S19b 正常行也在', shard.includes('正常行'));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S20 多表按节归属：委派行（含嵌入竖线）仍归委派表 ----
+{
+  const root = mkroot();
+  const weirdDeleg = '| 2026-09-01 | ui-verifier | 任务含 `a|b` 竖线 | 一次通过 | 备注 | |';
+  fs.writeFileSync(wf(root, 'delegations.md'), [
+    '## 委派结果', '',
+    '| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 | 合入结论 |',
+    '|------|----------------|------------|------|------|----------|',
+    weirdDeleg, '',
+    '## 自做任务结果', '',
+    '| 日期 | 任务一句话 | 结果 | 备注 | 合入结论 |',
+    '|------|------------|------|------|----------|',
+    '| 2026-09-02 | 自做任务 | 一次通过 | 备注 | |', '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'delegations');
+  const shard = fs.readFileSync(wf(root, 'delegations.d', '2026-09.md'), 'utf8');
+  const iDeleg = shard.indexOf('被委派方(模型)');
+  const iSelf = shard.indexOf('| 日期 | 任务一句话');
+  const iWeird = shard.indexOf('任务含');
+  check('S20 嵌入竖线的委派行仍归委派表', iDeleg < iWeird && iWeird < iSelf, `deleg=${iDeleg} weird=${iWeird} self=${iSelf}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S21 分片须带节标题（wf-journal.delegationSectionRows 的节门）----
+// （2026-10-13 源仓实测踩中：只带表头 → 节门读侧读到 0 行 → 静默漏报）
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'delegations.md'), [
+    '## 委派结果', '',
+    '| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 | 合入结论 |',
+    '|------|----------------|------------|------|------|----------|',
+    '| 2026-09-01 | ui-verifier | 委派任务 | 一次通过 | 备注 | |', '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'delegations');
+  const shard = fs.readFileSync(wf(root, 'delegations.d', '2026-09.md'), 'utf8');
+  check('S21a 分片带 `## 委派结果` 节标题', /^##\s+委派结果\s*$/m.test(shard), shard.slice(0, 120));
+  // 复刻 wf-journal.delegationSectionRows 的节门判据（不 break 形态）
+  let inSec = false;
+  let rows = 0;
+  for (const line of shard.split(/\r?\n/)) {
+    if (/^##\s+/.test(line)) { inSec = /^##\s+委派结果\s*$/.test(line); continue; }
+    if (!inSec || !/^\s*\|/.test(line)) continue;
+    const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+    if (!cells.length || cells.every((c) => /^[-: ]*$/.test(c))) continue;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(cells[0])) continue;
+    rows++;
+  }
+  check('S21b 节门口径能读到分片行', rows === 1, `rows=${rows}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S22 kit 适配钉子：分片渲染出 kit 表头、不出源仓表头 ----
+// （kit delegations 两表末列 =「合入结论」、regression-checklist 表头 =「incident | 条目 | 落点」；
+//   再自源仓同步本模块时若把源仓表头带回来，此组先红）
+{
+  const deleg = renderShard('delegations', []);
+  check('S22a delegations 分片骨架出「合入结论」表头', deleg.includes('合入结论') && !deleg.includes('返工原因'));
+  const regr = renderShard('regression-checklist', []);
+  check('S22b regression-checklist 分片骨架出 kit 表头', regr.includes('| incident | 条目 | 落点 |') && !regr.includes('来源 incident'));
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);