agentic-flow-kit 1.7.0 → 1.7.16

package/templates/_agents/scripts/gen-wiki-board.mjs

@@ -1,7 +1,8 @@
 // wiki 索引生成器：磁盘 + INDEX 速览表「用途」列 → 自动重生成 INDEX 速览计数/映射表 + 看板 DATA
 // 2026-09-13 引入：消除三层手工双写（短板①）。人工只维护两样：磁盘文件本身 + 速览表用途列。
-// 用法：node .agents/scripts/gen-wiki-board.mjs [--dry-run] [--help]
+// 用法：node .agents/scripts/gen-wiki-board.mjs [--dry-run] [--check] [--help]
 //   （收录/删除/移动 wiki 文件后必跑，随后跑 verify-wiki-consistency.mjs）
+//   --check 不写盘；INDEX/看板与磁盘不一致时 exit 1 并打印差异（供 doctor 漂移告警）
 // 测试：node .agents/scripts/gen-wiki-board.test.mjs（fixture 回归，须全绿）
 // 生成范围（锚点内整段重写，锚点外字节原样保留）：
 //   INDEX.md 速览表数据行 / 「合计」行数字 / 「## 文件 → 主题 → 归属目录 映射表」到「## 命名规则」之间
@@ -11,7 +12,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 
-const USAGE = `用法：node .agents/scripts/gen-wiki-board.mjs [--dry-run] [--help]
+const USAGE = `用法：node .agents/scripts/gen-wiki-board.mjs [--dry-run] [--check] [--help]
 
 事实源：磁盘 wiki/<主题>/ 一层文件 + INDEX.md 速览表「用途」列（人工列）。重生成：
   - wiki/INDEX.md：速览表数据行与文件计数、「合计」行数字、映射表节
@@ -21,6 +22,7 @@ const USAGE = `用法：node .agents/scripts/gen-wiki-board.mjs [--dry-run] [--h
 
 选项：
   --dry-run   只打印将生成内容的摘要与逐行差异，不写盘
+  --check     不写盘；INDEX/看板与磁盘不一致时 exit 1 并打印差异（供 doctor 漂移告警）
   --help      打印本说明`;
 
 const args = process.argv.slice(2);
@@ -28,12 +30,13 @@ if (args.includes('--help') || args.includes('-h')) {
   console.log(USAGE);
   process.exit(0);
 }
-const unknown = args.filter((a) => a !== '--dry-run');
+const unknown = args.filter((a) => a !== '--dry-run' && a !== '--check');
 if (unknown.length) {
   console.error(`❌ 未知参数：${unknown.join(' ')}\n\n${USAGE}`);
   process.exit(1);
 }
 const DRY = args.includes('--dry-run');
+const CHECK = args.includes('--check');
 
 const WIKI = 'wiki';
 const INDEX_P = path.join(WIKI, 'INDEX.md');
@@ -87,6 +90,34 @@ for (const d of fs.readdirSync(WIKI)) {
   diskTopics.set(d, entries);
 }
 
+// ---- 草稿超龄提醒（P1-2）：drafts-archive/<YYYY-MM-DD-主题>/ 落盘超龄未归类 → stdout WARN ----
+// advisory 档：只提醒不阻断（与 B1 沉淀追踪同档），不改归档统计口径与任何生成物，exit code 不受影响。
+// 目录名不带日期前缀（人工建的目录）→ 静默跳过，不 WARN 也不报错。
+const DRAFT_AGE_DAYS = 14; // 超龄档位（天）：与 B1 沉淀追踪同档 advisory，只提醒不阻断
+const TODAY = (() => {
+  // FLOW_KIT_TODAY=YYYY-MM-DD 仅测试/演练用：覆盖「今天」便于构造超龄/未超龄用例；未设置或格式不合法时用系统当前日期
+  const env = process.env.FLOW_KIT_TODAY;
+  if (env && /^\d{4}-\d{2}-\d{2}$/.test(env)) return env;
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+})();
+const utcMs = (s) => { // 'YYYY-MM-DD' → 当日 UTC 零点毫秒（与 TODAY 同构换算，天数差恒为精确整数）
+  const [y, m, d] = s.split('-').map(Number);
+  return Date.UTC(y, m - 1, d);
+};
+// rel：相对 drafts-archive 的 '/' 分隔路径（如 '2026-09-01-主题/主题.md'，与上方 walk 的 rel 拼法一致）
+const warnIfDraftAged = (rel) => {
+  if (!rel.includes('/')) return; // 直接躺在 drafts-archive 根（无日期目录包裹）→ 静默跳过
+  const dirName = rel.split('/')[0];
+  const m = dirName.match(/^(\d{4}-\d{2}-\d{2})/);
+  if (!m) return; // 目录名不带日期前缀（人工建的目录）→ 静默跳过
+  const days = (utcMs(TODAY) - utcMs(m[1])) / 86400000;
+  if (!(days > DRAFT_AGE_DAYS)) return; // 未超龄（恰 14 天不提醒，超过才提醒）；NaN 同样落此静默跳过
+  const topic = dirName.slice('YYYY-MM-DD-'.length) || dirName; // 目录名 = 日期-主题；无主题段则退回目录名
+  console.log(`[WARN 草稿超龄] drafts-archive/${rel} 落于 ${m[1]} 未归类——草稿是中间态，归类到 wiki/${topic}/ 后跑 gen-wiki-board + verify-wiki-consistency`);
+};
+
 const archiveCount = (() => {
   let n = 0;
   const walk = (dir, rel = '') => {
@@ -95,7 +126,10 @@ const archiveCount = (() => {
       // 集合键带 drafts-archive/ 前缀（扫描面扩全 wiki/ 后），walk rel 须拼前缀比对（复核 P2-b）
       const r = rel ? `drafts-archive/${rel}/${e}` : `drafts-archive/${e}`;
       if (fs.statSync(p).isDirectory()) walk(p, rel ? `${rel}/${e}` : e);
-      else if (!gitIgnoredArchive.has(r)) n++;
+      else if (!gitIgnoredArchive.has(r)) {
+        n++;
+        warnIfDraftAged(rel ? `${rel}/${e}` : e); // 超龄提醒挂在计数控分支：口径一致（ignored 件不提醒），不影响计数
+      }
     }
   };
   if (fs.existsSync(path.join(WIKI, 'drafts-archive'))) walk(path.join(WIKI, 'drafts-archive'));
@@ -185,7 +219,28 @@ if (boardOut === boardText && !/const DATA = \{[\s\S]*?\n\};/.test(boardText)) {
   process.exit(1);
 }
 
-// ---- 写盘（dry-run 只预览差异）----
+// ---- 写盘（dry-run 只预览差异；--check 只比对不写盘）----
+// 行尾归一比较（与 gen-workflow-index.mjs 同款：fresh clone 检出 CRLF、生成段恒 LF——
+// 直接字符串相等会在克隆环境假阳性「漂移」；仅内容差异才算漂移）
+const normEol = (s) => String(s).replace(/\r\n/g, '\n');
+const indexOk = normEol(out) === normEol(indexText);
+const boardOk = normEol(boardOut) === normEol(boardText);
+const summary = `文件 ${totalFiles} 份 / 主题 ${diskTopics.size} 个 / 归档 ${archiveCount} 份`;
+if (CHECK) {
+  if (indexOk && boardOk) {
+    console.log(`✅ wiki/INDEX.md 与看板均与磁盘一致（${summary}）`);
+    process.exit(0);
+  }
+  if (!indexOk) {
+    console.error(`❌ wiki/INDEX.md 与磁盘不一致（${summary}）——跑 node .agents/scripts/gen-wiki-board.mjs 重新生成`);
+    previewDiff('wiki/INDEX.md', indexText, out);
+  }
+  if (!boardOk) {
+    console.error(`❌ wiki/知识沉淀总览.html 与磁盘不一致（${summary}）——跑 node .agents/scripts/gen-wiki-board.mjs 重新生成`);
+    previewDiff('wiki/知识沉淀总览.html', boardText, boardOut);
+  }
+  process.exit(1);
+}
 if (DRY) {
   console.log('🔎 --dry-run：未写盘，差异预览如下');
   previewDiff('wiki/INDEX.md', indexText, out);
@@ -196,7 +251,7 @@ if (DRY) {
 }
 
 const tail = DRY ? '将重写' : '已重写';
-console.log(`${DRY ? '🔎 [dry-run] 将生成' : '✅ 已生成'}：文件 ${totalFiles} 份 / 主题 ${diskTopics.size} 个 / 归档 ${archiveCount} 份；速览表 ${overviewRows.length} 行、映射表 ${ordered.length} 节、看板 DATA ${tail}`);
+console.log(`${DRY ? '🔎 [dry-run] 将生成' : '✅ 已生成'}：${summary}；速览表 ${overviewRows.length} 行、映射表 ${ordered.length} 节、看板 DATA ${tail}`);
 console.log('   人工仅维护：磁盘文件 + 速览表「用途」列（新主题为 <待补> 的请补描述后重跑本脚本）');
 
 // dry-run 差异预览：首尾对齐后取中段变更块（逐行），各方向最多显示 10 行

package/templates/_agents/scripts/gen-wiki-board.test.mjs

@@ -85,7 +85,8 @@ const mkfix = (eol) => {
   return root;
 };
 
-const runGen = (root) => spawnSync(process.execPath, [GEN], { cwd: root, encoding: 'utf8' });
+// extraEnv：注入被测脚本环境变量（场景 8/9 用 FLOW_KIT_TODAY 固定「今天」，默认继承父进程环境不变）
+const runGen = (root, extraArgs = [], extraEnv = {}) => spawnSync(process.execPath, [GEN, ...extraArgs], { cwd: root, encoding: 'utf8', env: { ...process.env, ...extraEnv } });
 
 // ---- 场景 1：CRLF INDEX ——「用途」列重生成后保持 + 行尾保持（缺陷回归）----
 {
@@ -168,6 +169,78 @@ const runGen = (root) => spawnSync(process.execPath, [GEN], { cwd: root, encodin
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 7：--check 漂移判定（2026-10-10 wiki-index-drift：供 doctor §6 镜像 workflow INDEX 检查）----
+//      不写盘；一致 exit 0，任一生成区漂移 exit 1 + 差异预览。行尾归一（CRLF clone 不假阳性）
+{
+  const root = mkfix('\r\n');
+  // 先跑一次正规生成，把 INDEX/看板对齐到磁盘事实
+  const r0 = runGen(root);
+  check('场景 7：前置生成 exit 0', r0.status === 0, `exit=${r0.status}\n${r0.stdout}${r0.stderr}`);
+  // 对齐后 --check 须一致（CRLF INDEX 尤其不能因行尾假阳性）
+  const r1 = runGen(root, ['--check']);
+  check('场景 7a --check 对齐态 → exit 0 且提示一致',
+    r1.status === 0 && (r1.stdout || '').includes('一致'), `exit=${r1.status}\n${r1.stdout}${r1.stderr}`);
+  check('场景 7a --check 不写盘（INDEX 内容字节不变）',
+    fs.readFileSync(path.join(root, 'wiki', 'INDEX.md'), 'utf8').includes(USAGE_COL), '');
+  // 磁盘新增文件 → 生成区与磁盘不一致 → exit 1
+  fs.writeFileSync(path.join(root, 'wiki', '主题A', 'b.md'), '# b\n', 'utf8');
+  const r2 = runGen(root, ['--check']);
+  check('场景 7b --check 漂移（磁盘新增文件未重生成）→ exit 1',
+    r2.status === 1 && (r2.stderr || '').includes('不一致'), `exit=${r2.status}\n${r2.stdout}${r2.stderr}`);
+  check('场景 7b --check 不写盘（漂移时仍不覆盖磁盘文件）',
+    !fs.readFileSync(path.join(root, 'wiki', 'INDEX.md'), 'utf8').includes('| b.md | 主题A |'), '');
+  // 修复后 --check 恢复 exit 0
+  const r3 = runGen(root);
+  const r4 = runGen(root, ['--check']);
+  check('场景 7c 重生成后 --check 恢复 exit 0', r3.status === 0 && r4.status === 0, `exit3=${r3.status} exit4=${r4.status}\n${r4.stdout}${r4.stderr}`);
+  // 看板 DATA 被手改 → exit 1（与 INDEX 漂移同档）
+  const board = path.join(root, 'wiki', '知识沉淀总览.html');
+  fs.writeFileSync(board, fs.readFileSync(board, 'utf8').replace('"total": 2', '"total": 99'), 'utf8');
+  const r5 = runGen(root, ['--check']);
+  check('场景 7d --check 看板 DATA 漂移 → exit 1',
+    r5.status === 1 && (r5.stderr || '').includes('知识沉淀总览.html'), `exit=${r5.status}\n${r5.stdout}${r5.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 8：草稿超龄 WARN（P1-2：drafts-archive/<YYYY-MM-DD-主题>/ 落盘超 14 天未归类 → stdout 提醒）----
+//      advisory 档只提醒不阻断：exit 0、INDEX/看板 DATA 不因 WARN 有任何变化；FLOW_KIT_TODAY 固定「今天」保证时间可控
+{
+  const root = mkfix('\n');
+  const DRAFT_DIR = '2026-09-01-登录优化';
+  const DRAFT_DATE = '2026-09-01';
+  fs.mkdirSync(path.join(root, 'wiki', 'drafts-archive', DRAFT_DIR));
+  fs.writeFileSync(path.join(root, 'wiki', 'drafts-archive', DRAFT_DIR, '登录优化.md'), '# 登录优化草稿\n', 'utf8');
+  const board = path.join(root, 'wiki', '知识沉淀总览.html');
+  const warnLine = `[WARN 草稿超龄] drafts-archive/${DRAFT_DIR}/登录优化.md 落于 ${DRAFT_DATE} 未归类——草稿是中间态，归类到 wiki/登录优化/ 后跑 gen-wiki-board + verify-wiki-consistency`;
+
+  // a) 「今天」= 草稿日期 + 15 天（> 14 天档）→ WARN 整行点名该草稿
+  const ra = runGen(root, [], { FLOW_KIT_TODAY: '2026-09-16' });
+  check('场景 8a：超龄 15 天 → exit 0（advisory 不阻断）', ra.status === 0, `exit=${ra.status}\n${ra.stdout}${ra.stderr}`);
+  check('场景 8a：stdout 含超龄 WARN 且整行点名草稿', (ra.stdout || '').includes(warnLine), ra.stdout);
+  check('场景 8a：生成物不受影响（看板归档计数仍为文件数 1）', /"archive": 1/.test(fs.readFileSync(board, 'utf8')), '');
+
+  // b) 「今天」= 同日 / 恰 14 天 → 未超龄，无 WARN（超过才提醒）
+  const rb = runGen(root, [], { FLOW_KIT_TODAY: DRAFT_DATE });
+  check('场景 8b：同日 → 无超龄 WARN', rb.status === 0 && !(rb.stdout || '').includes('[WARN 草稿超龄]'), rb.stdout);
+  const rb14 = runGen(root, [], { FLOW_KIT_TODAY: '2026-09-15' });
+  check('场景 8b：恰 14 天 → 无超龄 WARN（边界）', rb14.status === 0 && !(rb14.stdout || '').includes('[WARN 草稿超龄]'), rb14.stdout);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 9：目录名无日期前缀（人工建的目录）→ 静默跳过：不 WARN、不报错、生成物不受影响（P1-2）----
+{
+  const root = mkfix('\n');
+  fs.mkdirSync(path.join(root, 'wiki', 'drafts-archive', '临时素材'));
+  fs.writeFileSync(path.join(root, 'wiki', 'drafts-archive', '临时素材', 'x.md'), '# x\n', 'utf8');
+  // 「今天」取远期（2027-01-01）：若误把无日期目录判成超龄必触发 WARN，可当场暴露缺陷
+  const r = runGen(root, [], { FLOW_KIT_TODAY: '2027-01-01' });
+  const board = fs.readFileSync(path.join(root, 'wiki', '知识沉淀总览.html'), 'utf8');
+  check('场景 9：无日期前缀目录 → exit 0（不报错）', r.status === 0, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 9：无超龄 WARN（静默跳过）', !(r.stdout || '').includes('[WARN 草稿超龄]'), r.stdout);
+  check('场景 9：看板输出不受影响（归档计数仍为文件数 1）', /"archive": 1/.test(board), '');
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log(`\n${USAGE}`);

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

@@ -19,6 +19,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
+import { readLedgerRows } from './ledger-loader.mjs';
 
 const require = createRequire(import.meta.url);
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -82,17 +83,13 @@ function collectDoneIntents(root) {
 // collectDoneMap：台账 earliest done 行（坏行容忍，doc 正斜杠根相对——沿检查 14/15 口径）
 function collectDoneMap(root) {
   const doneMap = new Map();
-  const ledgerPath = path.join(root, '.agents', 'confirmations.jsonl');
-  if (!fs.existsSync(ledgerPath)) return doneMap;
-  for (const line of fs.readFileSync(ledgerPath, 'utf8').split(/\r?\n/)) {
-    if (!line.trim()) continue;
-    try {
-      const e = JSON.parse(line);
-      if (e && e.stage === 'done' && typeof e.doc === 'string' && e.doc.startsWith('workflow/intents/')) {
-        const prev = doneMap.get(e.doc);
-        if (prev === undefined || e.ts < prev) doneMap.set(e.doc, e.ts);
-      }
-    } catch { /* 坏行容忍跳过 */ }
+  // 读法收敛 ledger-loader（2026-10-12 ledger-loader-p1）：earliest done 行取自时间戳比较，
+  // 与行序无关，故并入台账视图不改变本函数语义（分片行同样参与「最早」判定）
+  for (const e of readLedgerRows(root)) {
+    if (e && e.stage === 'done' && typeof e.doc === 'string' && e.doc.startsWith('workflow/intents/')) {
+      const prev = doneMap.get(e.doc);
+      if (prev === undefined || e.ts < prev) doneMap.set(e.doc, e.ts);
+    }
   }
   return doneMap;
 }
@@ -119,7 +116,7 @@ export function qualityRows(root) {
     const avg = Number.isFinite(m.avgRework) ? m.avgRework.toFixed(2) : '—';
     // 门禁噪声返工单列（2026-10-08 selfmeasure-and-modularize）：设计返工与噪声返工分列可诊断——
     // 「平均返工」把两者平均在一起时看不出该改门禁还是改设计。
-    out.push(`| ${ym} | ${m.total} | ${pct(m.passRate)} | ${m.reworkSum} | ${m.reworkNoiseSum} | ${avg} | ${pct(m.fallbackRate)} | ${verdict} |`);
+    out.push(`| ${ym} | ${m.total} | ${pct(m.passRate)} | ${m.reworkSum} | ${m.reworkNoiseSum} | ${avg} | ${pct(m.fallbackRate)} | ${agg.fmtAccept(m)} | ${verdict} |`);
   }
   return { rows: out, verdictMap, months };
 }
@@ -202,7 +199,7 @@ function main() {
     '',
     '## 质量 / 返工（月度，判据复用 agg-delegations）',
     '',
-    '| 月份 | 有效任务 | 一次通过率 | 设计返工 | 门禁噪声返工 | 平均返工 | 主兜底占比 | 扩容门判定 |',
+    '| 月份 | 有效任务 | 一次通过率 | 设计返工 | 门禁噪声返工 | 平均返工 | 主兜底占比 | 产出接受率 | 扩容门判定 |',
     '|------|----------|------------|---------|-------------|--------|------------|------------|',
     ...(q.rows.length ? q.rows : ['| — | — | — | — | — | — | — | 台账暂无数据 |']),
     '',

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,28 +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（保持「缺失即响亮」的既有纪律，不静默兜底）。
-const resolveEnumsPath = () => {
-  let dir = path.dirname(fileURLToPath(import.meta.url));
-  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;
-  }
-  return path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '.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 -->';
@@ -168,14 +151,13 @@ const idxText = fs.existsSync(path.join(WORKFLOW, 'INDEX.md')) ? fs.readFileSync
 const idxBytes = Buffer.byteLength(idxText, 'utf8');
 const idxActive = Number((idxText.match(/^## 活跃（(\d+)）/m) || [])[1] ?? NaN);
 
-// ---- 闭环漏斗（2026-10-02 ledger-funnel-metrics；口径定义式单源 = workflow/specs/2026-10-02-ledger-funnel-metrics.md）----
+// ---- 闭环漏斗（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) {
@@ -249,9 +231,9 @@ const TABLE_HEAD = [
   '| 月份 | 文档（活跃/终态） | 文档字节 | 模块已填/总 | 常驻面字节（预算峰值） | INDEX（活跃行） |',
   '|---|---|---|---|---|---|',
 ];
-// 漏斗表头（第二表；口径定义式单源 = workflow/specs/2026-10-02-ledger-funnel-metrics.md）
+// 漏斗表头（第二表）
 const FUNNEL_HEAD = [
-  '## 闭环漏斗（机器口径，源：.agents/confirmations.jsonl——定义式见 specs/2026-10-02-ledger-funnel-metrics.md）',
+  '## 闭环漏斗（机器口径，源：.agents/confirmations.jsonl）',
   '',
   '| 月份 | 收口 | 完整链 | 协议前 | 一次通过 | 返工件 | 中位周期(天) | 台账行数 |',
   '|---|---|---|---|---|---|---|---|',

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