agentic-flow-kit 1.7.0 → 1.7.16

package/templates/_agents/scripts/kb-search.mjs

@@ -10,6 +10,9 @@
 // 结构缓存（2026-09-23 intent kb-search-structure-cache）：可检索子集预提取进 .agents/cache/kb-index.json，
 //   按 [mtimeMs,size] 逐文件失效，口径指纹变化整份作废；匹配/排序/输出路径不变（三路输出与冷扫逐字节一致）；
 //   缓存任何读写异常静默回退全扫。`--include-generated` 走纯扫（bulk 文件不入缓存）。
+// 检索留痕（2026-10-11 P1-1）：每次实际检索后向 .agents/notes/kb-search-ledger.jsonl 追加一行 JSON
+//   （ts/query/scope/hits/top），KB 沉淀↔检索形成可审计闭环；--no-ledger 显式退出；
+//   写失败仅 console.error 一行 WARN，不改变检索输出与退出码。
 // 测试：node .agents/scripts/kb-search.test.mjs（fixture 回归，须全绿）
 // 模块词表：.agents/workflow-modules.txt（--module 取值校验，单源）
 import fs from 'node:fs';
@@ -33,6 +36,7 @@ const USAGE = `用法: node .agents/scripts/kb-search.mjs [选项] <词1> [词2
   --no-cache                     禁用结构缓存，全量扫（与缓存热路径输出逐字节一致）
   --cache <文件>                 结构缓存文件路径覆盖（默认 .agents/cache/kb-index.json；测试注入用）
   --rebuild                      忽略现有缓存重建后回写
+  --no-ledger                    退出检索留痕：不向 .agents/notes/kb-search-ledger.jsonl 追加本次检索记录
   --help                         打印本说明
 
 退出码：0 正常（含无命中）；1 参数错误（无词 / 未知选项 / 非法枚举值）`;
@@ -49,6 +53,7 @@ let includeGenerated = false;
 let noCache = false;
 let cacheFileOverride = ''; // --cache <文件>（board-kb-p1）：测试注入式缓存路径，不再直跑清真实开发缓存
 let rebuild = false;
+let noLedger = false; // --no-ledger（P1-1）：留痕默认开启（审计要完整），显式退出才跳过写 ledger
 const words = [];
 for (let i = 0; i < args.length; i++) {
   const a = args[i];
@@ -62,6 +67,7 @@ for (let i = 0; i < args.length; i++) {
   else if (a === '--no-cache') noCache = true;
   else if (a === '--cache') cacheFileOverride = args[++i] ?? '';
   else if (a === '--rebuild') rebuild = true;
+  else if (a === '--no-ledger') noLedger = true;
   else if (a === '--help' || a === '-h') { console.log(USAGE); process.exit(0); }
   else words.push(a);
 }
@@ -88,6 +94,9 @@ if (moduleFilter && !MODULES.includes(moduleFilter)) {
 // 活跃口径 = 单源 doc.status.active ∪ incident.status.active（与 workflow/INDEX.md 活跃层一致，fixed 归档案默认也可命中）
 const ACTIVE_STATUS = [...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']];
 const WF_SECTIONS = ['背景', '目标', '根因', '复盘三件套', '验收标准', '影响面'];
+// wiki 侧节提取白名单（2026-10-10 A1）：wiki 知识文档的骨架节——长文全文 includes 召回差，
+//   节级提取让命中带节名上下文。放此处（WF_SECTIONS 旁，CFG_FP 之前）供指纹派生。
+const WIKI_SECTIONS = ['标题', '摘要', '背景', '结论', '要点', '规范', '用法', '示例'];
 const WIKI_EXCLUDE = new Set(['INDEX.md', '知识沉淀总览.html']);
 const WIKI_MAX_KB = 180;
 
@@ -149,17 +158,20 @@ const ROOT_NS = `${path.resolve('.')}::`;
 const WIKI_EXTS = includeGenerated ? /\.(md|sql|html|csv|json|txt)$/i : /\.(md|sql|html|txt)$/i;
 
 // 行序列化/复活（缓存 schema 的定义者——board-kb-p1 起纳入 CFG_FP 指纹：schema 演进即整份缓存作废）
-const serializeLines = (lines, kind) => lines.map((x) => (kind === 'wf' ? [x.ln, x.section, x.line] : [x.ln, x.line]));
-const reviveLines = (lines, kind) => lines.map((a) => (kind === 'wf' ? { ln: a[0], section: a[1], line: a[2] } : { ln: a[0], line: a[1] }));
+//   2026-10-10 A1：wiki 行从二元组 [ln, line] 升三元组 [ln, section, line]（节级提取随动）——
+//   两 kind 同构后 serialize/revive 按 kind 取三元组即可，旧缓存由 CFG_FP 指纹整份作废。
+const serializeLines = (lines) => lines.map((x) => [x.ln, x.section, x.line]);
+const reviveLines = (lines) => lines.map((a) => ({ ln: a[0], section: a[1], line: a[2] }));
 
 // linesShapeOk：缓存条目 lines 形状校验（board-kb-p1）——JSON 合法但 schema 坏（lines 非数组 / 元素非数组）
 // 一律视同 miss 走 build 重建（头注释「任何读写异常静默回退」契约恢复；此前直接 .map 抛 TypeError exit 1）
 const linesShapeOk = (lines) => Array.isArray(lines) && (lines.length === 0 || lines.every(Array.isArray));
 
 const CFG_FP = createHash('sha256').update(JSON.stringify({
-  v: 1, WF_SECTIONS, ACTIVE_STATUS, WIKI_MAX_KB, excl: [...WIKI_EXCLUDE],
+  v: 3, // 2026-10-10 B3：wiki 条目也存 meta（来源 frontmatter 血缘显示），schema 演进作废旧缓存
+  WF_SECTIONS, WIKI_SECTIONS, ACTIVE_STATUS, WIKI_MAX_KB, excl: [...WIKI_EXCLUDE],
   exts: WIKI_EXTS.source, // schema 派生（board-kb-p1：手抄摘要曾致扩展面演进不触发指纹失效；RegExp.source 跨 includeGenerated 分支稳定）
-  fns: [parseDoc.toString(), workflowLines.toString(), matchWords.toString(), serializeLines.toString(), reviveLines.toString()],
+  fns: [parseDoc.toString(), workflowLines.toString(), wikiLines.toString(), matchWords.toString(), serializeLines.toString(), reviveLines.toString()],
 })).digest('hex').slice(0, 16);
 const cacheUsable = !noCache && !includeGenerated;
 let cache = null;
@@ -186,13 +198,13 @@ function cachedEntry(relPath, kind, build) {
   const e = cache[key];
   if (e && e.kind === kind && Array.isArray(e.st) && e.st[0] === sig[0] && e.st[1] === sig[1] && linesShapeOk(e.lines)) {
     touched.add(key);
-    return { st: e.st, meta: e.meta, title: e.title, lines: reviveLines(e.lines, kind) };
+    return { st: e.st, meta: e.meta, title: e.title, lines: reviveLines(e.lines) };
   }
   const built = build();
   cache[key] = {
     st: sig, kind,
-    ...(kind === 'wf' ? { meta: built.meta, title: built.title } : {}),
-    lines: serializeLines(built.lines, kind),
+    ...(built.meta ? { meta: built.meta, ...(built.title ? { title: built.title } : {}) } : {}),
+    lines: serializeLines(built.lines),
   };
   touched.add(key);
   return { st: sig, meta: built.meta, title: built.title, lines: built.lines };
@@ -249,7 +261,36 @@ function searchWorkflow(words) {
   return results.sort((a, b) => b.score - a.score);
 }
 
-// ---- wiki 检索（口径同 2026-09-21 降噪版 wiki-search）----
+// ---- wiki 检索（口径同 2026-09-21 降噪版 wiki-search；2026-10-10 A1：节级提取 + 主题路径加权）----
+// wiki 侧与 workflow 侧同款行结构（ln + section + line），节提取用 wiki 自己的标题滚动：
+//   wiki 知识文档多为长文，全文 includes 召回差、命中行缺乏上下文——节级提取让命中带节名
+//   （`[<节名>] L<行>: <摘录>`，与 workflow 侧输出对齐）。frontmatter（如有）单列 '(frontmatter)' 节。
+//   提取节白名单 WIKI_SECTIONS（常量定义在文件头部 WF_SECTIONS 旁），与 WF_SECTIONS 平行。
+function wikiLines(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let i = 0;
+  if (/^---\s*$/.test(lines[0] || '')) {
+    out.push({ ln: 1, section: '(frontmatter)', line: lines[0] });
+    for (i = 1; i < lines.length; i++) {
+      out.push({ ln: i + 1, section: '(frontmatter)', line: lines[i] });
+      if (/^---\s*$/.test(lines[i])) { i++; break; }
+    }
+  }
+  let section = '';
+  // wiki 短文常无小节标题（如「# 说明\n正文」）——节白名单只覆盖骨架节，纯标题文档会零命中。
+  //   兜底：全文无任何 `## ` 时正文全收（section 记 '(正文)'）；有 ## 后回到白名单口径。
+  const sawH2 = lines.slice(i).some((l) => /^## /.test(l));
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    const h1 = line.match(/^# (.+?)\s*$/);
+    if (h1 && !/^## /.test(line)) { out.push({ ln: i + 1, section: '(标题)', line }); section = ''; continue; }
+    const h2 = line.match(/^## (.+?)\s*$/);
+    if (h2) section = h2[1];
+    if (!sawH2 || WIKI_SECTIONS.some((s) => section.startsWith(s))) out.push({ ln: i + 1, section: section || '(正文)', line });
+  }
+  return out;
+}
 const walkWiki = (dir, rel) => {
   const out = [];
   for (const e of fs.readdirSync(dir)) {
@@ -275,13 +316,21 @@ function searchWiki(words) {
       const e = cachedEntry(p, 'wiki', () => {
         let text;
         try { text = fs.readFileSync(p, 'utf8'); } catch { return { lines: [] }; }
-        return { lines: text.split('\n').map((line, i) => ({ ln: i + 1, line })) };
+        const { meta } = parseDoc(text);
+        return { meta, lines: wikiLines(text) };
       });
       if (!e.lines.length) continue;
       const hits = matchWords(e.lines.filter((x) => words.some((w) => x.line.includes(w))), words);
       if (!hits) continue;
       const kb = size / 1024;
-      results.push({ file: key, total: hits.total, shown: hits.shown, kb, score: hits.total / Math.sqrt(Math.max(kb, 0.1)) });
+      // 主题路径加权（A1）：查询词出现在主题目录名（key 首段，如「项目规范」）时 ×1.2——
+      //   主题归属是 wiki 最有价值的结构特征，纯全文打分完全没用上；权重温和（不压倒命中数主序）
+      const topicHit = words.some((w) => key.includes(w));
+      const score = (hits.total / Math.sqrt(Math.max(kb, 0.1))) * (topicHit ? 1.2 : 1);
+      // 来源血缘（B3，2026-10-10）：wiki frontmatter「来源: workflow/<类型>/<文件>」指回 workflow 归档——
+      //   与 intent/incident 的正向「沉淀:」字段对称。有则结果行显示，无则空（老 wiki 文件零行为变化）
+      const source = (e.meta && e.meta['来源']) || '';
+      results.push({ file: key, total: hits.total, shown: hits.shown, kb, score, source });
     }
   }
   return { results: results.sort((a, b) => b.score - a.score), skipped };
@@ -290,11 +339,13 @@ function searchWiki(words) {
 // ---- 输出 ----
 const top = (arr) => (limit ? arr.slice(0, limit) : arr);
 let anyHits = 0;
+let topFile = null; // 首个展示文件（留痕用）：按展示顺序 workflow→wiki 取 shown[0]，无命中保持 null
 
 if (scope === 'workflow' || scope === 'all') {
   const res = searchWorkflow(words);
   anyHits += res.length;
   const shown = top(res);
+  if (shown.length && !topFile) topFile = `workflow/${shown[0].file}`;
   console.log(`── workflow（${res.length} 个文件命中${res.length > shown.length ? `，展示前 ${shown.length}` : ''}）──`);
   for (const r of shown) {
     console.log(`📄 workflow/${r.file} — ${r.status || '未填状态'} · ${r.level} · ${r.module} · ${r.total} 处命中 / ${r.kb < 10 ? r.kb.toFixed(1) : Math.round(r.kb)}KB`);
@@ -307,10 +358,11 @@ if (scope === 'wiki' || scope === 'all') {
   const { results: res, skipped } = searchWiki(words);
   anyHits += res.length;
   const shown = top(res);
+  if (shown.length && !topFile) topFile = `wiki/${shown[0].file}`;
   console.log(`── wiki（${res.length} 个文件命中${res.length > shown.length ? `，展示前 ${shown.length}` : ''}）──`);
   for (const r of shown) {
-    console.log(`📄 wiki/${r.file} — ${r.total} 处命中 / ${r.kb < 10 ? r.kb.toFixed(1) : Math.round(r.kb)}KB`);
-    for (const h of r.shown) console.log(`   L${h.ln}: ${h.line.trim().slice(0, 130)}`);
+    console.log(`📄 wiki/${r.file} — ${r.total} 处命中 / ${r.kb < 10 ? r.kb.toFixed(1) : Math.round(r.kb)}KB${r.source ? ` · 来源 ${r.source}` : ''}`);
+    for (const h of r.shown) console.log(`   [${h.section || '(无节)'}] L${h.ln}: ${h.line.trim().slice(0, 130)}`);
   }
   if (!res.length) console.log('（无命中）');
   if (skipped) console.log(`（wiki 跳过 ${skipped} 个产物/大文件——--include-generated 纳入）`);
@@ -321,3 +373,26 @@ console.log(`\n${anyHits ? `合计 ${anyHits} 个文件命中（${words.join(' A
   (scope === 'all' ? '；`--scope` 限定语料、`--status all` 显式全量' : ''));
 
 saveCache();
+
+// ---- 检索留痕（P1-1）：append-only 一行 JSON，KB 沉淀↔检索可审计闭环 ----
+// ROOT 与 workflow/、wiki/ 索引根一致（脚本按 cwd 相对路径读语料，ROOT_NS 同源）；
+// 写失败只 WARN 不阻断：留痕是旁路记录，异常必须可见，但绝不能改变检索结果与退出码。
+const LEDGER_FILE = path.join('.agents', 'notes', 'kb-search-ledger.jsonl');
+function appendLedger() {
+  if (noLedger) return;
+  const pad = (n) => String(n).padStart(2, '0');
+  const d = new Date();
+  try {
+    fs.mkdirSync(path.dirname(LEDGER_FILE), { recursive: true });
+    fs.appendFileSync(LEDGER_FILE, `${JSON.stringify({
+      ts: `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`, // ISO 8601 本地时间
+      query: words.join(' '),
+      scope,
+      hits: anyHits, // 切 top 之前的命中总量（workflow + wiki）
+      top: topFile,
+    })}\n`, 'utf8');
+  } catch (e) {
+    console.error(`WARN 检索留痕写入失败（不影响检索结果）：${e && e.message ? e.message : e}`);
+  }
+}
+appendLedger();

package/templates/_agents/scripts/kb-search.test.mjs

@@ -175,6 +175,89 @@ const files = (out) => (out.match(/^📄 (workflow\/\S+)/gm) || []).map((l) => l
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 10：A1 wiki 侧节级提取 + 主题路径加权（2026-10-10）----
+//    wiki 命中带节名（骨架节或无小节兜底）；主题目录命中查询词时排序提前；长文节外内容不参与检索
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-a1-'));
+  fs.mkdirSync(path.join(root, 'wiki', '项目规范'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'wiki', '杂项'), { recursive: true });
+  // 长文：命中在白名单节内（## 结论）+ 节外（## 历史流水，不应被索引）
+  fs.writeFileSync(path.join(root, 'wiki', '项目规范', '权限收敛.md'),
+    '# 权限收敛方案\n\n## 结论\n- 权限收敛后只读接口不再放行写操作。\n\n## 历史流水\n- 2026-09 某次发布也提到权限收敛但属节外内容\n', 'utf8');
+  // 短文：无任何 ## —— 正文兜底全收
+  fs.writeFileSync(path.join(root, 'wiki', '杂项', '说明.md'), '# 说明\n\n权限收敛的领域知识条目。\n', 'utf8');
+  const r = run(root, ['--scope', 'wiki', '--cache', rootCache(root), '权限收敛']);
+  check('场景 10a wiki 长文命中带节名（结论节）',
+    r.status === 0 && /wiki\/项目规范\/权限收敛.md/.test(r.stdout) && /\[结论\]/.test(r.stdout), `exit=${r.status}\n${r.stdout}`);
+  check('场景 10b wiki 长文节外内容不参与检索（历史流水行不进命中摘录）',
+    !/历史流水/.test(r.stdout), r.stdout);
+  check('场景 10c wiki 短文无小节兜底（正文命中，节名 (正文)）',
+    /wiki\/杂项\/说明.md/.test(r.stdout) && /\(正文\)/.test(r.stdout), `exit=${r.status}\n${r.stdout}`);
+  // 主题加权：两文件命中数同量级时，主题名含查询词的「项目规范」排前
+  const order = (r.stdout.match(/^📄 (wiki\/\S+)/gm) || []).map((l) => l.replace('📄 ', ''));
+  check('场景 10d 主题路径加权：主题名命中查询词的文件排前',
+    order.length === 2 && order[0].includes('项目规范'), `order=${JSON.stringify(order)}\n${r.stdout}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 11：B3 来源血缘显示（2026-10-10）----
+//    wiki frontmatter「来源: workflow/<类型>/<文件>」→ 结果行带「· 来源 …」；无来源老文件零变化
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-b3-'));
+  fs.mkdirSync(path.join(root, 'wiki', '项目规范'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'workflow', 'intents'), { recursive: true });
+  // 带来源的 wiki 文件（B2 生成的草稿/人工沉淀都是这个形态）
+  fs.writeFileSync(path.join(root, 'wiki', '项目规范', '权限收敛.md'),
+    '---\n来源: workflow/intents/2026-09-12-perm-shrink.md\n---\n# 权限收敛方案\n\n## 结论\n- 权限收敛后只读接口不再放行写操作。\n', 'utf8');
+  // 无 frontmatter 的老 wiki 文件（零行为变化对照）
+  fs.writeFileSync(path.join(root, 'wiki', '项目规范', '老规范.md'), '# 老规范\n\n权限收敛的旧条目。\n', 'utf8');
+  const r = run(root, ['--scope', 'wiki', '--cache', rootCache(root), '权限收敛']);
+  check('场景 11a 有来源的 wiki 结果行显示来源血缘',
+    r.status === 0 && /来源 workflow\/intents\/2026-09-12-perm-shrink\.md/.test(r.stdout), `exit=${r.status}\n${r.stdout}`);
+  check('场景 11b 无 frontmatter 老文件正常命中且无来源行干扰',
+    r.status === 0 && /wiki\/项目规范\/老规范\.md/.test(r.stdout), `exit=${r.status}\n${r.stdout}`);
+  // 来源字段本身可被检索（frontmatter 已进可检索面——双向找链：从 wiki 侧反查 workflow 来源）
+  const r2 = run(root, ['--scope', 'wiki', '--cache', rootCache(root), 'perm-shrink']);
+  check('场景 11c 来源路径本身参与检索（frontmatter 命中）',
+    r2.status === 0 && /wiki\/项目规范\/权限收敛\.md/.test(r2.stdout), `exit=${r2.status}\n${r2.stdout}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 12：检索留痕（P1-1）——每次检索后 ledger 追加一行 / --no-ledger 退出 / notes 目录自动创建 ----
+//    ledger 落在 <临时根>/.agents/notes/kb-search-ledger.jsonl（与 workflow/、wiki/ 索引根同 ROOT）
+{
+  const ledgerOf = (root) => path.join(root, '.agents', 'notes', 'kb-search-ledger.jsonl');
+  const ledgerLines = (root) => fs.readFileSync(ledgerOf(root), 'utf8').split('\n').filter(Boolean);
+  const root = mkfix();
+  check('场景 12 前置：.agents/notes 尚不存在', !fs.existsSync(path.join(root, '.agents')));
+  // a) 首次检索 → 恰 1 行、JSON 合法、字段齐全、hits 为数字
+  const r1 = run(root, ['--scope', 'workflow', '编码模板', '冲突']);
+  const lines1 = ledgerLines(root);
+  check('场景 12a 检索后 ledger 存在且恰 1 行', r1.status === 0 && lines1.length === 1, `exit=${r1.status}\n${r1.stderr}`);
+  const entry = JSON.parse(lines1[0]);
+  check('场景 12a ledger 行字段齐全（ts/query/scope/hits/top）',
+    typeof entry.ts === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/.test(entry.ts)
+    && entry.query === '编码模板 冲突' && entry.scope === 'workflow'
+    && entry.hits === 2 && entry.top === 'workflow/intents/2026-09-21-bbb.md', lines1[0]);
+  // b) 已有 ledger 再跑 → 追加成 2 行且旧行原样
+  const r2 = run(root, ['--scope', 'wiki', '编码模板']);
+  const lines2 = ledgerLines(root);
+  check('场景 12b 再次检索追加成 2 行且旧行原样',
+    r2.status === 0 && lines2.length === 2 && lines2[0] === lines1[0]
+    && JSON.parse(lines2[1]).scope === 'wiki' && JSON.parse(lines2[1]).top === 'wiki/测试主题/说明.md', lines2.join('\n'));
+  // c) --no-ledger → 不追加（仍 2 行）
+  const r3 = run(root, ['--no-ledger', '--scope', 'workflow', '编码模板']);
+  check('场景 12c --no-ledger 不追加不新建', r3.status === 0 && ledgerLines(root).length === 2, r3.stderr);
+  // d) 无命中检索也留痕（top=null、hits=0）
+  const r4 = run(root, ['--scope', 'workflow', 'zzz-绝不存在-zzz']);
+  const lines4 = ledgerLines(root);
+  const entry4 = JSON.parse(lines4[2]);
+  check('场景 12d 无命中留痕 top=null 且 hits=0',
+    r4.status === 0 && entry4.query === 'zzz-绝不存在-zzz' && entry4.hits === 0 && entry4.top === null, lines4.join('\n'));
+  check('场景 12e .agents/notes 目录由检索自动创建', fs.statSync(path.join(root, '.agents', 'notes')).isDirectory());
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log(`\n${USAGE}`);

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;
+}