agentic-flow-kit 1.7.15 → 1.8.0

package/templates/_agents/scripts/gen-verify-evidence.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// gen-verify-evidence.mjs — 验证绿凭证摘要入库生成器（2026-10-13 自 Shipyard.Material 参考实现回灌，
+//   源仓沿革留痕在包源仓 git 历史与 CHANGELOG——装户径不引实例路径）
+// 背景：verifications.jsonl 是 gitignore 的本地台账（24h 窗口、跨机不可见）——历史提交「当时验证过什么」
+//   的机器事实只活在本地。本脚本把全绿行按 headShort 去重（同 SHA 取最新 ts）渲染进仓内
+//   workflow/verify-evidence.md，使绿凭证成为随库持久、跨机可对质的生成物（全量台账仍留本地）。
+// 语义：一行 = 「**验证时刻的工作树**（其基线提交 = 短 SHA，工作树可含未提交改动）过 verify 全量门禁
+//   全绿（门数 / 套件计数）」；非证据链签名——本地台账可伪造的诚实边界不变（check-loop 检查 15 头注释
+//   口径），入库摘要只是把「曾有凭证」从易失升级为难失。
+// 归因提醒：短 SHA 只是**基线提交**，不等于被测内容。关单应「先提交、后跑门」，否则绿行 SHA 指向
+//   未含本次改动的上一提交——同一 SHA 可能既有绿行（脏工作区跑）又有红记录。
+// 追加保全：已入仓的行不因本地台账缺失而被抹掉——台账 per-worktree 且 gitignore，整段重写会让
+//   跨机/换 worktree 的历史凭证消失。合并口径 = 仓内既有行 ∪ 本地台账绿行，同 headShort 取更新 ts
+//   （平局取本地台账，保持「重跑刷新凭证」语义）。代价（已接受）：仓内错行不会被重生成自动纠正——
+//   须人工改正；若本地台账仍持同一 SHA，重生成会按台账重写该行（须连同台账处理）。
+// 时机：verify.mjs 全绿尾部自动重生成（事件原子化——绿事实与仓内摘要同刻生成，消除双真相分叉）
+//   + 关单时随三件套同笔提交；CI 侧重生成于 CI 工作区、不回流本仓，无副作用；--check 只供本地自检。
+// 台账口径：kit 绿行形状 = {ts, exitCode:0, suite:'npm test', gates?, headShort?, passed?, failed?,
+//   doc?, runId?}（verify.mjs 落账单源）——本脚本只认 exitCode===0 且 suite==='npm test' 且带 headShort
+//   的行（无 SHA 的旧 schema 行不渲染）；passed/failed 语义 = 套件计数（非断言），doc = --doc 绑定单。
+// 用法：node .agents/scripts/gen-verify-evidence.mjs [--root <dir>] [--check]
+// 测试：node .agents/scripts/gen-verify-evidence.test.mjs（fixture 注入 --root）
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const argv = process.argv.slice(2);
+const argOf = (k) => {
+  const i = argv.indexOf(k);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : '';
+};
+const ROOT = argOf('--root') || path.resolve(SCRIPT_DIR, '..', '..');
+const LEDGER = path.join(ROOT, '.agents', 'verifications.jsonl');
+const OUT = path.join(ROOT, 'workflow', 'verify-evidence.md');
+
+// 六列数据行：短SHA / 时间 / 门数 / 套件计数 / 绑定单 / runId
+const ROW_RE = /^\|\s*`([0-9a-f]{7,40})`\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|\s*$/;
+
+/** 按本地台账条目渲染数据行 */
+function renderRow(e) {
+  const cnt = Number.isFinite(e.passed) ? `PASS ${e.passed} / FAIL ${e.failed ?? 0}` : '—';
+  return `| \`${e.headShort}\` | ${e.ts} | ${e.gates ?? '—'} | ${cnt} | ${e.doc || '—'} | ${e.runId || '—'} |`;
+}
+
+/**
+ * 解析本文件既有数据行（追加保全用）。
+ * 只认形态完整的数据行；说明行 / 表头 / 注释一律忽略。读不到文件 = 无既有行。
+ */
+function parseCommittedRows() {
+  const out = [];
+  let disk = '';
+  try { disk = fs.readFileSync(OUT, 'utf8'); } catch { return out; }
+  for (const raw of disk.split(/\r?\n/)) {
+    const m = raw.trim().match(ROW_RE);
+    if (m) out.push({ headShort: m[1], ts: m[2].trim(), line: raw.trim() });
+  }
+  return out;
+}
+
+function render() {
+  const rows = [];
+  try {
+    for (const line of fs.readFileSync(LEDGER, 'utf8').split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        const e = JSON.parse(line);
+        if (e.exitCode === 0 && e.suite === 'npm test' && e.headShort) rows.push(e);
+      } catch { /* 坏行跳过——台账是 append-only 事实流，不因单行格式失败中断 */ }
+    }
+  } catch { /* 无台账 = 空表（新装户/新 clone 首跑前） */ }
+  // 行统一形态 { headShort, ts, line }。先放**仓内既有行**（追加保全），再叠加本地台账绿行。
+  const bySha = new Map();
+  for (const r of parseCommittedRows()) bySha.set(r.headShort, r);
+  // 同 headShort 取更新 ts（重跑刷新凭证，不堆行）；平局取本地台账
+  for (const e of rows) {
+    const prev = bySha.get(e.headShort);
+    if (!prev || String(e.ts) >= String(prev.ts)) bySha.set(e.headShort, { headShort: e.headShort, ts: String(e.ts), line: renderRow(e) });
+  }
+  const ordered = [...bySha.values()].sort((a, b) => String(a.ts).localeCompare(String(b.ts)));
+  const lines = [];
+  lines.push('# 验证绿凭证摘要（生成物，勿手改）');
+  lines.push('');
+  lines.push('> 生成器 `node .agents/scripts/gen-verify-evidence.mjs`（verify.mjs 全绿尾部自动重生成；源 .agents/verifications.jsonl 为本地台账）。');
+  lines.push('> 一行 = 验证时刻**工作树**过 verify 全量门禁全绿（短 SHA 为该时刻的**基线提交**，工作树可能含未提交改动——关单宜「先提交、后跑门」）；`套件计数` 为测试门编排器的套件 PASS/FAIL（无汇总行时缺省）；`绑定单` 为 --doc 绑定的工作流文档（不带的行不给任何单背书）。非签名链——诚实边界同 check-loop 检查 15。');
+  lines.push('> 行来源 = 本地台账绿行 ∪ 本文件既有行（**追加保全**：跨机 / 换 worktree 不失历史；代价：错行不会被重生成自动纠正，须人工改正后重跑）。');
+  lines.push('');
+  lines.push('| 提交(短SHA) | 时间(UTC) | 门数 | 套件计数 | 绑定单 | runId |');
+  lines.push('|---|---|---|---|---|---|');
+  for (const e of ordered) lines.push(e.line);
+  lines.push('');
+  lines.push(`<!-- GENERATED:END — 共 ${ordered.length} 行；gen-verify-evidence.mjs 生成（既有行追加保全，勿手改） -->`);
+  return lines.join('\n') + '\n';
+}
+
+const text = render();
+if (argv.includes('--check')) {
+  let disk = '';
+  try { disk = fs.readFileSync(OUT, 'utf8'); } catch { /* 缺文件走漂移分支 */ }
+  if (disk === text) { console.log('[verify-evidence] ✅ 与磁盘一致'); process.exit(0); }
+  console.error('[verify-evidence] 漂移：本地台账有新绿行未入摘要——关单时跑 node .agents/scripts/gen-verify-evidence.mjs 并随同提交');
+  process.exit(1);
+}
+fs.mkdirSync(path.dirname(OUT), { recursive: true });
+fs.writeFileSync(OUT, text);
+// 数据行计数：直接数六列数据行，不做总行数算术（生成物自描述）
+console.log(`✅ 已生成 ${path.relative(process.cwd(), OUT)}（绿凭证 ${text.split(/\r?\n/).filter((l) => ROW_RE.test(l.trim())).length} 行）`);

package/templates/_agents/scripts/gen-verify-evidence.test.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// gen-verify-evidence.test.mjs — 验证凭证摘要生成器 fixture 套件（2026-10-13 自 Shipyard.Material
+//   参考实现回灌时随件移植；台账口径改 kit 绿行形状 suite:'npm test' + 绑定单 doc 列）
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SCRIPT = path.join(SCRIPT_DIR, 'gen-verify-evidence.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 mkfix = (rows) => {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-evidence-test-'));
+  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
+  if (rows) fs.writeFileSync(path.join(d, '.agents', 'verifications.jsonl'), rows.map((r) => JSON.stringify(r)).join('\n') + '\n');
+  return d;
+};
+const run = (root, ...args) => {
+  const r = spawnSync(process.execPath, [SCRIPT, '--root', root, ...args], { encoding: 'utf8' });
+  return { code: r.status, out: `${r.stdout || ''}${r.stderr || ''}` };
+};
+// kit 绿行形状（verify.mjs 落账单源）：suite 'npm test'、passed/failed = 套件计数、doc = --doc 绑定单
+const GREEN = (headShort, ts, extra = {}) => ({ ts, exitCode: 0, suite: 'npm test', gates: 7, passed: 45, failed: 0, headShort, ...extra });
+
+// 场景 1：绿行渲染 + 同 SHA 去重取最新 + 失败行/无 SHA 行/坏行排除
+{
+  const d = mkfix([
+    GREEN('abc1234', '2026-10-09T08:34:08Z'),
+    GREEN('abc1234', '2026-10-09T09:14:44Z'), // 同 SHA 更新 ts → 只留此行
+    GREEN('def5678', '2026-10-09T10:00:00Z', { runId: 'PIPE-1', doc: 'workflow/intents/<日期>-<主题>.md' }),
+    { ts: '2026-10-09T11:00:00Z', exitCode: 1, suite: 'check-loop', note: 'exit 1' }, // 失败行
+    { ts: '2026-10-09T12:00:00Z', exitCode: 0, suite: 'npm test', gates: 7 }, // 无 headShort（非 git 环境/旧 schema）
+    '{broken json', // 坏行
+  ]);
+  const r = run(d);
+  const doc = fs.readFileSync(path.join(d, 'workflow', 'verify-evidence.md'), 'utf8');
+  check('场景 1：只渲染绿行且同 SHA 取最新（abc1234 只出现一次且为 09:14）',
+    r.code === 0 && (doc.match(/\| `abc1234`/g) || []).length === 1 && doc.includes('2026-10-09T09:14:44Z') && doc.includes('`def5678`') && doc.includes('PIPE-1') && !doc.includes('2026-10-09T11:00:00Z') && !doc.includes('broken'),
+    doc);
+  check('场景 1b：门数、套件计数与绑定单列渲染', doc.includes('| 7 | PASS 45 / FAIL 0 |') && doc.includes('workflow/intents/<日期>-<主题>.md'), doc);
+}
+// 场景 2：无台账 → 空表骨架（新 clone 首跑）
+{
+  const d = mkfix(null);
+  const r = run(d);
+  const doc = fs.readFileSync(path.join(d, 'workflow', 'verify-evidence.md'), 'utf8');
+  check('场景 2：无台账生成空表骨架', r.code === 0 && doc.includes('# 验证绿凭证摘要') && !doc.includes('`abc'), doc);
+}
+// 场景 3：--check 一致/漂移/再生成恢复
+{
+  const d = mkfix([GREEN('aaa1111', '2026-10-09T08:00:00Z')]);
+  run(d);
+  check('场景 3a：生成后 --check 一致', run(d, '--check').code === 0);
+  fs.writeFileSync(path.join(d, '.agents', 'verifications.jsonl'), JSON.stringify(GREEN('bbb2222', '2026-10-09T09:00:00Z')) + '\n');
+  const r2 = run(d, '--check');
+  check('场景 3b：台账新增绿行 → --check 漂移 exit 1', r2.code === 1 && r2.out.includes('关单时跑'), r2.out);
+  run(d);
+  check('场景 3c：再生成后恢复一致', run(d, '--check').code === 0);
+}
+
+// 场景 4：追加保全——本地台账缺某 SHA 时，仓内既有行不被抹掉（跨机/换 worktree 不失历史）
+{
+  const d = mkfix([GREEN('aaa1111', '2026-10-09T08:00:00Z'), GREEN('ccc3333', '2026-10-09T09:00:00Z')]);
+  run(d);
+  const before = fs.readFileSync(path.join(d, 'workflow', 'verify-evidence.md'), 'utf8');
+  // 换 worktree / 换机：本地台账被覆盖为只含 ddd4444
+  fs.writeFileSync(path.join(d, '.agents', 'verifications.jsonl'), JSON.stringify(GREEN('ddd4444', '2026-10-09T10:00:00Z')) + '\n');
+  const r = run(d);
+  const doc = fs.readFileSync(path.join(d, 'workflow', 'verify-evidence.md'), 'utf8');
+  check('场景 4：台账换机后仓内既有行保全（aaa1111/ccc3333 仍在，ddd4444 补入）',
+    r.code === 0 && doc.includes('`aaa1111`') && doc.includes('`ccc3333`') && doc.includes('`ddd4444`') && before.includes('`aaa1111`'),
+    doc);
+  check('场景 4b：保全后 --check 一致（幂等）', run(d, '--check').code === 0);
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

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

@@ -19,6 +19,10 @@ 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';
+// 委派台账分片感知读（2026-10-13 ledger-shard-ledgers 回灌）：合并文本（主台账 ∪ delegations.d/*.md）
+// 由本件经 readLedgerText 取（读侧单源），经 opts.text 注入 agg.readLedger——.cjs 库模式无法自装载 .mjs。
+import { readLedgerText } from './ledger-shards.mjs';
 
 const require = createRequire(import.meta.url);
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -82,24 +86,22 @@ 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;
 }
 
 // qualityRows：月度质量行（判据全部复用 agg——本函数只做分组与格式化）
 export function qualityRows(root) {
-  const rows = agg.readLedger(root, { soft: true });
+  // 分片感知（2026-10-13 ledger-shard-ledgers）：text = 主台账 ∪ delegations.d/*.md；空文本（无台账
+  // 装户）→ rows []，soft 优雅降级语义不变。
+  const rows = agg.readLedger(root, { soft: true, text: readLedgerText(root, 'delegations') });
   const byMonth = {};
   for (const r of rows) (byMonth[r.date.slice(0, 7)] ||= []).push(r);
   const months = Object.keys(byMonth).sort();
@@ -133,9 +135,9 @@ export function qualityRows(root) {
 //   故本节恒为静态文案：**任何时候生成本文件，字节恒等**（测试 ⑤ 的两条 --check exit 0 钉的就是这条）。
 export function gateRoiLines() {
   return [
-    '- 采集：`node .agents/scripts/check-loop.mjs --gate-stats`（数据落 `.agents/cache/gate-stats.jsonl`，该目录已 gitignore；不带 flag 时零写入、输出逐字节不变）',
+    '- 采集：`node .agents/scripts/check-loop.mjs --all --gate-stats`（--all 全段成本面——2026-10-13 分道后裸跑只记硬门段；数据落 `.agents/cache/gate-stats.jsonl`，该目录已 gitignore；不带 flag 时零写入、输出逐字节不变）',
     '- 看数值：`node .agents/scripts/agg-gate-stats.mjs [--days 30]`——输出成本排序 + 两类决策依据：噪声率 top（该收窄或该修）、死检查（该拆或该降级）；无采集数据时该命令自己提示「未采集」并给出采集命令',
-    '- 口径：耗时**含子进程时间**（检查 11 调两个生成器 `--check`、检查 13 调 `sh rule-budget.sh`）——门禁真实成本，不做剔除；样本 <5 次时只作线索，不作决策依据',
+    '- 口径：耗时**含子进程时间**（检查 11 调两个生成器 `--check`、检查 13 调 `rule-budget.mjs`）——门禁真实成本，不做剔除；样本 <5 次时只作线索，不作决策依据',
     '- 本节为何不铺数值：本文件被检查 11 漂移门覆盖，运行数据每跑一次门禁即变一次，铺进来会让每次采集都产一条漂移 WARN（不可消除噪声）',
   ];
 }

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

@@ -163,8 +163,9 @@ const INTENT = (fm) => `---\n${fm}\n---\n# INTENT — x\n`;
 
   // 无采集态（先于造 cache 生成）：节恒为静态文案，故与有无数据无关
   const rl = gateRoiLines();
+  // 采集命令随 2026-10-13 分道带 --all（全段成本面；裸 --gate-stats 只记硬门段）
   check('门禁ROI：节内容给出采集命令 + 看数值命令 + 无数据时 CLI 自带「未采集」提示（优雅降级不落空节）',
-    rl.join('\n').includes('check-loop.mjs --gate-stats') && rl.join('\n').includes('agg-gate-stats.mjs') && rl.join('\n').includes('未采集'), rl.join('\n'));
+    rl.join('\n').includes('check-loop.mjs --all --gate-stats') && rl.join('\n').includes('agg-gate-stats.mjs') && rl.join('\n').includes('未采集'), rl.join('\n'));
   check('门禁ROI：节内容不含任何耗时/次数运行数值（防检查 11 每次采集报漂移的设计核心）',
     !/\d+\s*(ms|s)\b/.test(rl.join('\n')) && !/运行\s*\d/.test(rl.join('\n')), rl.join('\n'));
   run();

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

@@ -4,15 +4,16 @@
 // 目的：把「语料膨胀 + 常驻面体积」变成可观测趋势——每月（或按需）跑一次，往 workflow/metrics.md 追加/更新一行。
 // 口径：文档 = 磁盘（对照 gen-workflow-index / 看板，排除 _TEMPLATE.md）；常驻面 = `.agents/rule-budgets.txt`
 //   各条实测（单源，含预算上限），括号内给「预算占用峰值项」。
-//   字节口径声明（p2-batch2）：本脚本用工作区 statSync 字节（CRLF 检出态会偏高），rule-budget.sh 用
+//   字节口径声明（p2-batch2）：本脚本用工作区 statSync 字节（CRLF 检出态会偏高），rule-budget.mjs 用
 //   索引 LF 归一字节——趋势观测可对比，但与门禁判定数值存在系统性差异，勿互相替用。
 // 不做 --check / 不挂门禁：快照是历史记录——任何文档改动都会让「当前值」漂移，拿它做漂移校验只会常红；
-//   规则面的机器约束由 pre-commit 的 rule-budget.sh 负责，本脚本只负责「看见趋势」。
+//   规则面的机器约束由 pre-commit 的 rule-budget.mjs 负责，本脚本只负责「看见趋势」。
 // 测试：node .agents/scripts/gen-workflow-metrics.test.mjs（fixture 回归，须全绿）
 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 -->';
@@ -138,7 +115,7 @@ function scanSurface() {
       max = sum;
       label = `${pat}（合计）`;
     } else if (pat.includes('*')) {
-      // 词表约定 glob = 基名内单个 `*`（<前缀>*<后缀>），目录段不支持通配——与 rule-budget.sh 的 shell glob 同口径。
+      // 词表约定 glob = 基名内单个 `*`（<前缀>*<后缀>），目录段不支持通配——与 rule-budget.mjs 的 glob 展开同口径。
       // 多 `*` / 目录段含 `*` 出词表：警告跳过，不做「只按后缀 endsWith」的放宽式匹配（2026-09-24 收口：
       // 曾按首个 * 取后缀，`pl*.md` 会误吃目录内全部 .md、`a*b` 会误吃一切 b 结尾文件）
       const stars = pat.split('*').length - 1;
@@ -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-core.mjs

@@ -0,0 +1,45 @@
+// git-core.mjs — 引擎 git 调用单源（2026-10-10 收敛系列 5：合并 check-loop-kit spawnGit/gitOut 与
+// stage-gates gitRun 的「同口径两份实现」（该债由 stage-gates 头注登记、本单偿清））。
+// 语义（取两侧并集，全部调用方共享）：
+//   - 参数数组直 spawn（不走 shell——Windows cmd 不认单引号）；git.exe 显式解析（Windows spawn 不补扩展名）
+//   - CHECK_LOOP_GIT 环境变量注入钩子（测试替身：指向不存在路径可稳定触发 spawn 异常）
+//   - 瞬时类错误（EAGAIN/EPERM/EMFILE/EINTR）单次重试；重试终败响亮出账（进程级去重恰一条）——
+//     「非 git 仓」（status≠0、无 error）仍是合法装户语义、静默降级
+//   - 只读查询记忆化：同参（含 cwd）复用结果；带 error 的基础设施失败不缓存（保留重试语义）
+//   - maxBuffer 32MB（pickaxe/name-only 大输出）
+import { spawnSync } from 'node:child_process';
+
+export const GIT = process.env.CHECK_LOOP_GIT || (process.platform === 'win32' ? 'git.exe' : 'git');
+
+const GIT_TRANSIENT = new Set(['EAGAIN', 'EPERM', 'EMFILE', 'EINTR']);
+const GIT_RESULT_CACHE = new Map(); // 键 = cwd + NUL + args.join(NUL)（多仓安全：confirm-doc 等 root 参数调用方）
+let infraWarned = false;
+function warnInfra(args, code) {
+  if (infraWarned) return;
+  infraWarned = true;
+  console.error(`git-core: git 探测异常 ${args[0]}（${code}）——按非 git 仓降级，检查面可能收窄`);
+}
+
+export function spawnGit(args, cwd) {
+  const cacheKey = cwd + '\u0000' + args.join('\u0000');
+  if (GIT_RESULT_CACHE.has(cacheKey)) return GIT_RESULT_CACHE.get(cacheKey);
+  const opts = { cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 };
+  let r = spawnSync(GIT, args, opts);
+  if (r.error) {
+    if (GIT_TRANSIENT.has(r.error.code)) r = spawnSync(GIT, args, opts);
+    if (r.error) warnInfra(args, r.error.code || r.error.message);
+  }
+  if (!r.error) GIT_RESULT_CACHE.set(cacheKey, r);
+  return r;
+}
+
+export function gitOut(args, cwd, { ok = () => true } = {}) {
+  const r = spawnGit(args, cwd);
+  if (r.error || r.status !== 0 || !ok(r)) return null;
+  return r.stdout || '';
+}
+
+// --rev 模式 ROOT 切到临时 worktree 后调：缓存键含 cwd，本不必整体作废；保留接口防御未来键形变化
+export function clearGitCache() {
+  GIT_RESULT_CACHE.clear();
+}

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