agentic-flow-kit 1.8.7 → 2.1.0

package/templates/engine/.agents/scripts/memory-tier.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// memory-tier.mjs — 注入层预算 + 记忆升降候选
+//
+// 背景（Anthropic《The components of agent memory》）：
+//   - 顶层记忆会被注入每个会话，必须小；Claude Code 只加载 MEMORY.md 前 200 行 / 25KB。
+//   - dreaming 的职责之一是“把细节下沉、把该上浮的规则上浮”，而不是持续变大。
+//
+// 本脚本：
+//   audit   检查注入层是否超行/字节预算（超限非零）
+//   suggest 从错题/会话经验/主张里找重复模式，输出“可考虑上浮”的候选（只读）
+//   budget  打印当前用量
+//
+// 用法：
+//   node .agents/scripts/memory-tier.mjs audit
+//   node .agents/scripts/memory-tier.mjs suggest [--days 90] [--min 3]
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_CONFIG = {
+  version: 1,
+  injected: { file: '.agents/notes/injected-memory.md', maxLines: 200, maxBytes: 25600 },
+  promotion: { candidates: '.agents/cache/memory-promotions.jsonl', minOccurrences: 3, outputDir: 'tmp' },
+};
+
+export function loadConfig(root) {
+  const file = path.join(root, '.agents', 'config', 'memory-tiers.json');
+  try {
+    return { ...DEFAULT_CONFIG, ...JSON.parse(fs.readFileSync(file, 'utf8')) };
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+
+export function auditBudget(root, cfg = loadConfig(root)) {
+  const rel = cfg.injected.file;
+  const abs = path.join(root, rel);
+  if (!fs.existsSync(abs)) return { ok: false, reason: 'missing', rel, lines: 0, bytes: 0, cfg };
+  const text = fs.readFileSync(abs, 'utf8');
+  const lines = text.split(/\r?\n/).length;
+  // 字节口径与 rule-budget 一致：LF 归一，避免 CRLF 虚高。
+  const bytes = Buffer.byteLength(text.replace(/\r\n/g, '\n'), 'utf8');
+  const overLines = lines > cfg.injected.maxLines;
+  const overBytes = bytes > cfg.injected.maxBytes;
+  return {
+    ok: !overLines && !overBytes,
+    reason: overLines ? 'over-lines' : overBytes ? 'over-bytes' : 'ok',
+    rel,
+    lines,
+    bytes,
+    maxLines: cfg.injected.maxLines,
+    maxBytes: cfg.injected.maxBytes,
+    cfg,
+  };
+}
+
+function readJsonl(dir, re) {
+  const rows = [];
+  let names = [];
+  try {
+    names = fs.readdirSync(dir).filter((n) => re.test(n)).sort();
+  } catch {
+    return rows;
+  }
+  for (const name of names) {
+    let raw = '';
+    try {
+      raw = fs.readFileSync(path.join(dir, name), 'utf8');
+    } catch {
+      continue;
+    }
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        rows.push(JSON.parse(line));
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return rows;
+}
+
+function norm(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/[`"'“”‘’]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// 候选来源：会话失败/纠正、错题 tag、主张中的重复主题。
+export function suggestPromotions(root, { days = 90, min = null, now = new Date() } = {}) {
+  const cfg = loadConfig(root);
+  const floor = Number(min) || cfg.promotion.minOccurrences;
+  const cutoff = now.getTime() - days * 86400000;
+  const buckets = new Map();
+  const add = (key, source, sample) => {
+    const k = norm(key);
+    if (!k || k.length < 4) return;
+    if (!buckets.has(k)) buckets.set(k, { key: k, count: 0, sources: new Set(), samples: [] });
+    const b = buckets.get(k);
+    b.count += 1;
+    b.sources.add(source);
+    if (sample && b.samples.length < 3) b.samples.push(sample);
+  };
+
+  const sessions = readJsonl(path.join(root, '.agents', 'cache', 'session-logs'), /^\d{4}-\d{2}-\d{2}\.jsonl$/)
+    .filter((e) => ['failure', 'correction', 'refusal'].includes(e.type))
+    .filter((e) => !e.ts || Date.parse(e.ts) >= cutoff);
+  for (const e of sessions) add(e.tag || e.text, 'session-log', e.text);
+
+  const papercuts = readJsonl(path.join(root, 'workflow', 'papercuts.d'), /\.(jsonl|json)$/)
+    .filter((e) => !e.ts || Date.parse(e.ts) >= cutoff);
+  for (const e of papercuts) add(e.tag || e.kind || e.text, 'papercut', e.text);
+
+  const claims = readJsonl(path.join(root, 'workflow', 'claims.d'), /^\d{4}-\d{2}\.jsonl$/)
+    .filter((e) => !e.ts || Date.parse(e.ts) >= cutoff);
+  for (const e of claims) {
+    const topic = String(e.path || '').split(/[\\/]/)[0];
+    add(topic || e.claim, 'claim', e.claim);
+  }
+
+  return [...buckets.values()]
+    .filter((b) => b.count >= floor)
+    .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key))
+    .map((b) => ({ key: b.key, count: b.count, sources: [...b.sources].sort(), samples: b.samples }));
+}
+
+export function writeSuggestion(root, candidates, { days = 90, cfg = loadConfig(root), now = new Date() } = {}) {
+  const dir = path.join(root, cfg.promotion.outputDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `memory-tier-suggest-${now.toISOString().slice(0, 10)}.md`);
+  const lines = [
+    `# 记忆上浮候选（近 ${days} 天）`,
+    '',
+    '> 只出候选，不自动改写注入层。裁决后手工改 `.agents/notes/injected-memory.md`，',
+    '> 并保持 200 行 / 25KB 预算；下沉详情用链接。',
+    '',
+  ];
+  if (!candidates.length) lines.push('_无达到阈值的重复模式。_');
+  else {
+    lines.push('| 候选 | 次数 | 来源 | 样本 |');
+    lines.push('|---|---|---|---|');
+    for (const c of candidates) {
+      lines.push(`| ${c.key.replace(/\|/g, '\\|')} | ${c.count} | ${c.sources.join(', ')} | ${c.samples[0]?.replace(/\|/g, '\\|') || ''} |`);
+    }
+  }
+  lines.push('');
+  fs.writeFileSync(file, `${lines.join('\n')}\n`, 'utf8');
+  return file;
+}
+
+function argOf(argv, name, fallback = null) {
+  const i = argv.indexOf(`--${name}`);
+  if (i < 0) return fallback;
+  const v = argv[i + 1];
+  return v == null || v.startsWith('--') ? true : v;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0] || 'audit';
+  const root = path.resolve(argOf(argv, 'root', process.cwd()));
+  const cfg = loadConfig(root);
+
+  if (cmd === 'audit') {
+    const res = auditBudget(root, cfg);
+    if (!res.ok) {
+      console.error(`✗ 注入层 ${res.reason}: ${res.rel} (${res.lines}/${cfg.injected.maxLines} 行, ${res.bytes}/${cfg.injected.maxBytes} 字节)`);
+      return 1;
+    }
+    console.log(`✅ 注入层预算: ${res.lines}/${cfg.injected.maxLines} 行, ${res.bytes}/${cfg.injected.maxBytes} 字节`);
+    return 0;
+  }
+
+  if (cmd === 'suggest') {
+    const days = Number(argOf(argv, 'days', 90)) || 90;
+    const min = Number(argOf(argv, 'min', 0)) || null;
+    const candidates = suggestPromotions(root, { days, min });
+    const file = writeSuggestion(root, candidates, { days, cfg });
+    console.log(`${file}（${candidates.length} 个候选）`);
+    return 0;
+  }
+
+  if (cmd === 'budget') {
+    const res = auditBudget(root, cfg);
+    console.log(`lines=${res.lines} bytes=${res.bytes} maxLines=${cfg.injected.maxLines} maxBytes=${cfg.injected.maxBytes} ok=${res.ok}`);
+    return res.ok ? 0 : 1;
+  }
+
+  console.error('用法: memory-tier.mjs audit | suggest [--days N] [--min N] | budget');
+  return 2;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('memory-tier.mjs');
+if (isMain) process.exit(main());

package/templates/engine/.agents/scripts/memory-wiki.mjs

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// memory-wiki.mjs — 把“记忆”编译成可导航的表示（wiki）
+//
+// 背景（Anthropic《The components of agent memory》）：wiki 不是文档归档，
+// 而是 dreaming 增量构建的“记忆地图”——页面 + 链接，让智能体能遍历自己知道什么；
+// 检索与 wiki 组合通常优于单独检索。
+//
+// 输入（存在即用）：
+//   workflow/claims.d/*.jsonl          主张账（未来会话可能当真的话 + 原文出处）
+//   workflow/incidents/*.md            事故复盘
+//   workflow/papercuts.d/*.md          错题/纸割登记
+//   .agents/cache/session-logs/*.jsonl 会话经验（failure/correction/refusal）
+//
+// 输出：wiki/_memory/INDEX.md + 每个主题一页（主张/事故/经验），带来源链接。
+// 语义：
+//   - 只写 wiki/_memory/**，不碰人工 wiki；
+//   - 幂等：内容未变不写；--check 发现漂移即非零；
+//   - 不自动 commit；不把 claims 的“原文还在”当成“主张为真”。
+//
+// 用法：
+//   node .agents/scripts/memory-wiki.mjs            # 生成/更新
+//   node .agents/scripts/memory-wiki.mjs --check    # 只检查是否最新
+//   node .agents/scripts/memory-wiki.mjs --dry-run  # 只打印将写文件
+import fs from 'node:fs';
+import path from 'node:path';
+import { recheckClaims } from './claims.mjs';
+
+const OUT_DIR = path.join('wiki', '_memory');
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function listFiles(dir, re) {
+  try {
+    return fs.readdirSync(dir).filter((n) => re.test(n)).sort();
+  } catch {
+    return [];
+  }
+}
+
+function slugify(s) {
+  return String(s || 'general')
+    .trim()
+    .toLowerCase()
+    .replace(/[^\w一-龥-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'general';
+}
+
+function firstHeading(text) {
+  const m = String(text).match(/^#\s+(.+)$/m);
+  return m ? m[1].trim() : '';
+}
+
+function relLink(fromRel, toRel) {
+  const rel = path.relative(path.dirname(fromRel), toRel).replace(/\\/g, '/');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+function readClaims(root) {
+  const dir = path.join(root, 'workflow', 'claims.d');
+  const rows = [];
+  for (const name of listFiles(dir, /^\d{4}-\d{2}\.jsonl$/)) {
+    const raw = readText(path.join(dir, name));
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        rows.push(JSON.parse(line));
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return rows;
+}
+
+function readSessionLessons(root) {
+  const dir = path.join(root, '.agents', 'cache', 'session-logs');
+  const rows = [];
+  for (const name of listFiles(dir, /^\d{4}-\d{2}-\d{2}\.jsonl$/)) {
+    const raw = readText(path.join(dir, name));
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        const row = JSON.parse(line);
+        if (['failure', 'correction', 'refusal'].includes(row.type)) rows.push(row);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return rows.sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts));
+}
+
+function readIncidents(root) {
+  const dir = path.join(root, 'workflow', 'incidents');
+  return listFiles(dir, /\.md$/).map((name) => {
+    const rel = `workflow/incidents/${name}`;
+    const text = readText(path.join(root, rel));
+    return { name, rel, title: firstHeading(text) || name.replace(/\.md$/, ''), text };
+  });
+}
+
+function readPapercuts(root) {
+  const dir = path.join(root, 'workflow', 'papercuts.d');
+  const out = [];
+  for (const name of listFiles(dir, /\.md$/)) {
+    const rel = `workflow/papercuts.d/${name}`;
+    const text = readText(path.join(root, rel));
+    out.push({ name, rel, title: firstHeading(text) || name, text });
+  }
+  const legacy = path.join(root, 'workflow', 'papercuts.md');
+  if (fs.existsSync(legacy)) out.push({ name: 'papercuts.md', rel: 'workflow/papercuts.md', title: 'papercuts', text: readText(legacy) });
+  return out;
+}
+
+export function buildMemoryWiki(root) {
+  const files = new Map();
+  const claims = readClaims(root);
+  const lessons = readSessionLessons(root);
+  const incidents = readIncidents(root);
+  const papercuts = readPapercuts(root);
+
+  // 主张按“出处路径的首段”聚主题；这比按时间堆叠更接近可遍历的记忆。
+  const claimTopics = new Map();
+  for (const c of claims) {
+    const topic = slugify(String(c.path || 'general').split(/[\\/]/)[0] || 'general');
+    if (!claimTopics.has(topic)) claimTopics.set(topic, []);
+    claimTopics.get(topic).push(c);
+  }
+
+  const indexRel = `${OUT_DIR.replace(/\\/g, '/')}/INDEX.md`;
+  const pages = [];
+
+  if (claimTopics.size) {
+    let recheck = { results: [] };
+    try {
+      recheck = recheckClaims(root);
+    } catch {
+      /* claims 账损坏时仍生成页面，只标 unknown */
+    }
+    const statusById = new Map((recheck.results || []).map((r) => [r.id, r.status]));
+    for (const topic of [...claimTopics.keys()].sort()) {
+      const rel = `${OUT_DIR.replace(/\\/g, '/')}/claims-${topic}.md`;
+      const rows = claimTopics.get(topic).slice().sort((a, b) => String(a.ts).localeCompare(String(b.ts)));
+      const body = [
+        '---',
+        `title: 主张 · ${topic}`,
+        'generated: true',
+        'source: workflow/claims.d',
+        '---',
+        '',
+        `# 主张 · ${topic}`,
+        '',
+        '> 主张是“未来会话可能当真的一句话”。`held` 只表示原文仍在，不表示主张为真。',
+        '',
+        ...rows.map((r) => {
+          const status = statusById.get(r.id) || 'unknown';
+          const mark = status === 'broken' ? '⚠ broken' : status;
+          return `- [${mark}] ${r.claim}\n  - 出处：\`${r.path}\` · \`${r.quote}\``;
+        }),
+        '',
+      ].join('\n');
+      files.set(rel, body);
+      pages.push({ rel, title: `主张 · ${topic}`, count: rows.length, kind: 'claims' });
+    }
+  }
+
+  if (incidents.length) {
+    const rel = `${OUT_DIR.replace(/\\/g, '/')}/incidents.md`;
+    const body = [
+      '---',
+      'title: 事故记忆',
+      'generated: true',
+      'source: workflow/incidents',
+      '---',
+      '',
+      '# 事故记忆',
+      '',
+      ...incidents.map((i) => `- [${i.title}](${relLink(rel, i.rel)}) — \`${i.rel}\``),
+      '',
+    ].join('\n');
+    files.set(rel, body);
+    pages.push({ rel, title: '事故记忆', count: incidents.length, kind: 'incidents' });
+  }
+
+  if (lessons.length) {
+    const rel = `${OUT_DIR.replace(/\\/g, '/')}/lessons.md`;
+    const body = [
+      '---',
+      'title: 会话经验',
+      'generated: true',
+      'source: .agents/cache/session-logs',
+      '---',
+      '',
+      '# 会话经验（失败 / 纠正 / 拒绝）',
+      '',
+      ...lessons.slice(-40).map((e) => {
+        const ref = e.ref ? ` · \`${e.ref}\`` : '';
+        return `- ${String(e.ts).slice(0, 10)} [${e.type}] ${e.text}${ref}`;
+      }),
+      '',
+    ].join('\n');
+    files.set(rel, body);
+    pages.push({ rel, title: '会话经验', count: lessons.length, kind: 'lessons' });
+  }
+
+  if (papercuts.length) {
+    const rel = `${OUT_DIR.replace(/\\/g, '/')}/papercuts.md`;
+    const body = [
+      '---',
+      'title: 错题与纸割',
+      'generated: true',
+      'source: workflow/papercuts.d',
+      '---',
+      '',
+      '# 错题与纸割',
+      '',
+      ...papercuts.map((p) => `- [${p.title}](${relLink(rel, p.rel)}) — \`${p.rel}\``),
+      '',
+    ].join('\n');
+    files.set(rel, body);
+    pages.push({ rel, title: '错题与纸割', count: papercuts.length, kind: 'papercuts' });
+  }
+
+  const index = [
+    '---',
+    'title: 记忆地图',
+    'generated: true',
+    'source: memory-wiki.mjs',
+    '---',
+    '',
+    '# 记忆地图（INDEX）',
+    '',
+    '> 这是 dreaming 生成的**记忆表示**，不是文档归档。页面只汇总可被后续会话依赖的事实与教训；',
+    '> 原文仍在各自的权威文件里。人工 wiki 不受影响。',
+    '',
+    pages.length ? '| 页面 | 条目 | 类型 |' : '_暂无记忆来源。先积累 claims / incidents / papercuts / session-logs。_',
+    ...(pages.length ? ['|---|---|---|', ...pages.map((p) => `| [${p.title}](${relLink(indexRel, p.rel)}) | ${p.count} | ${p.kind} |`)] : []),
+    '',
+  ].join('\n');
+  files.set(indexRel, index);
+
+  return { files, pages, counts: { claims: claims.length, incidents: incidents.length, lessons: lessons.length, papercuts: papercuts.length } };
+}
+
+export function syncMemoryWiki(root, { check = false, dryRun = false } = {}) {
+  const { files, counts } = buildMemoryWiki(root);
+  const changed = [];
+  for (const [rel, content] of files) {
+    const abs = path.join(root, rel);
+    const current = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+    if (current === content) continue;
+    changed.push(rel);
+    if (!check && !dryRun) {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, content, 'utf8');
+    }
+  }
+  return { changed, counts, checked: check, dryRun };
+}
+
+// ---- CLI ----
+function main() {
+  const argv = process.argv.slice(2);
+  const rootIdx = argv.indexOf('--root');
+  const root = path.resolve(rootIdx >= 0 ? argv[rootIdx + 1] : process.cwd());
+  const check = argv.includes('--check');
+  const dryRun = argv.includes('--dry-run');
+  const res = syncMemoryWiki(root, { check, dryRun });
+  const summary = `claims=${res.counts.claims} incidents=${res.counts.incidents} lessons=${res.counts.lessons} papercuts=${res.counts.papercuts}`;
+  if (check) {
+    if (res.changed.length) {
+      console.error(`✗ memory-wiki 漂移：${res.changed.join(', ')}（${summary}）`);
+      return 1;
+    }
+    console.log(`✅ memory-wiki 最新（${summary}）`);
+    return 0;
+  }
+  if (dryRun) {
+    console.log(`dry-run: 将写 ${res.changed.length} 个文件（${summary}）`);
+    for (const rel of res.changed) console.log(`  ${rel}`);
+    return 0;
+  }
+  console.log(`memory-wiki: 更新 ${res.changed.length} 个文件（${summary}）`);
+  for (const rel of res.changed) console.log(`  ${rel}`);
+  return 0;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('memory-wiki.mjs');
+if (isMain) process.exit(main());

package/templates/engine/.agents/scripts/metrics-core.mjs

@@ -0,0 +1,131 @@
+// metrics-core.mjs — workflow 指标口径共享内核（2026-10-23 board-engine-views A2 抽取）
+// 单源纪律：闭环漏斗 / 复核效果 / 中位周期的**计算口径**只此一份——gen-workflow-metrics.mjs（metrics.md
+// 月度快照）与 workflow-board-server.mjs（看板引擎视图）共同 import；改动任一消费方不得复制逻辑。
+// 本模块只放纯函数与一次性只读采集（git log / 台账分片扫描），无写盘、无主流程。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// 闭环漏斗「协议前」占比阈值（单源，2026-10-23 P2）：s26 动作阈值与 gen-workflow-metrics 的
+// legacy 占比告警共用；此前两处各写 0.30 字面量，靠测试钉同值。
+export const FUNNEL_LEGACY_RATIO_LIMIT = 0.30;
+
+export function cycleDays(addedIso, terminalTs) {
+  if (!addedIso || !terminalTs) return null;
+  const days = (Date.parse(terminalTs) - Date.parse(addedIso)) / 86400000;
+  if (!Number.isFinite(days) || days < 0) return null;
+  return days;
+}
+
+// 日历整月差（2026-10-23 P2）：退役窗口「连续 6 月」按日历月算，不用 183 天近似。
+// 未满整月不计（1-15 → 7-14 = 5，1-15 → 7-15 = 6）；非法输入 null；未来时间按 0。
+export function calendarMonthsBetween(from, to = Date.now()) {
+  const a = new Date(from);
+  const b = new Date(to);
+  if (!Number.isFinite(a.getTime()) || !Number.isFinite(b.getTime())) return null;
+  let months = (b.getFullYear() - a.getFullYear()) * 12 + (b.getMonth() - a.getMonth());
+  if (b.getDate() < a.getDate()) months -= 1;
+  return Math.max(0, months);
+}
+
+// 一次 git log：路径 → 首次加入提交的 committer 时间。失败（非 git / 命令失败）返回 null，调用方整列写 —。
+export function loadFirstAdded(cwd = process.cwd()) {
+  let r;
+  try {
+    r = spawnSync('git', [
+      'log', '--reverse', '--diff-filter=A', '--format=%cI', '--name-only', '--',
+      'workflow/intents', 'workflow/specs', 'workflow/plans', 'workflow/incidents', 'workflow/archive',
+    ], { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  } catch {
+    return null;
+  }
+  if (!r || r.status !== 0) return null;
+  const map = new Map();
+  let ts = null;
+  for (const line of String(r.stdout || '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (/^\d{4}-\d{2}-\d{2}T/.test(trimmed)) { ts = trimmed; continue; }
+    const p = trimmed.replace(/\\/g, '/');
+    if (ts && !map.has(p)) map.set(p, ts);
+  }
+  return map;
+}
+
+export function funnelFromLedger(entries, month, firstAdded) {
+  const byDoc = new Map();
+  for (const e of entries) {
+    if (typeof e.doc !== 'string' || typeof e.ts !== 'string') continue;
+    if (!byDoc.has(e.doc)) byDoc.set(e.doc, []);
+    byDoc.get(e.doc).push(e);
+  }
+  const res = { closed: 0, full: 0, legacy: 0, once: 0, rework: 0, ledgerRows: 0, days: [], items: [] };
+  for (const e of entries) if (typeof e.ts === 'string' && e.ts.slice(0, 7) === month) res.ledgerRows++;
+  for (const [doc, rs] of byDoc) {
+    rs.sort((a, b) => String(a.ts).localeCompare(String(b.ts)));
+    const nonRevert = rs.filter((r) => !/^revert-/.test(String(r.stage || '')));
+    const terminals = nonRevert.filter((r) => r.stage === 'done' || r.stage === 'closed');
+    if (!terminals.length) continue; // 未收口件不进漏斗桶（仍计台账行数）
+    const lastTerm = terminals[terminals.length - 1];
+    if (String(lastTerm.ts).slice(0, 7) !== month) continue; // 月度归桶 = 终态行所在月
+    // 确认阶段按件型（复核 P2-3 收口）：docs=approved；incidents=fixed（两跳确认门 fixed→closed，
+    // 永无 approved 行——按 approved 判会把已走确认门的 incident 误归协议前）
+    const isInc = doc.includes('/incidents/');
+    const confirmStage = isInc ? 'fixed' : 'approved';
+    const confirms = nonRevert.filter((r) => r.stage === confirmStage);
+    const hasChain = confirms.length >= 1;
+    const hasRevert = rs.some((r) => /^revert-/.test(String(r.stage || '')));
+    const kind = !hasChain ? 'legacy' : (hasRevert || confirms.length >= 2 || terminals.length >= 2 ? 'rework' : 'once');
+    const added = firstAdded ? firstAdded.get(String(doc).replace(/\\/g, '/')) : null;
+    const days = cycleDays(added, lastTerm.ts);
+    res.closed++;
+    if (kind === 'legacy') res.legacy++;
+    else { res.full++; res[kind === 'once' ? 'once' : 'rework']++; }
+    if (days != null) res.days.push(days);
+    res.items.push({ doc, kind, days: days == null ? '—' : days.toFixed(1) });
+  }
+  return res;
+}
+
+// 中位周期渲染（median-display）：真实的极小值不得被印成 `0.0`——四舍五入会得 0.0 时写 `<0.1`
+// 显式表达「非零但极小」；null 仍写 `—`（口径与 metrics.md 表头声明一致）。
+export function fmtMedianDays(v) {
+  if (v == null) return '—';
+  const s = v.toFixed(1);
+  return s === '0.0' && v > 0 ? '<0.1' : s;
+}
+
+// 复核效果台账扫描（workflow/reviews.d/ 意见级处置分片）：一行 = 一次独立复核事件，
+// 采纳+拒绝+误报 = 意见数。坏分片/自洽破坏抛错不静默（与 gen-workflow-metrics 同一口径）。
+export function scanReviews(workflowDir = 'workflow') {
+  const dir = path.join(workflowDir, 'reviews.d');
+  if (!fs.existsSync(dir)) return {};
+  const byMonth = {};
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith('.md')) continue;
+    const p = path.join(dir, f);
+    let text;
+    try {
+      text = fs.readFileSync(p, 'utf8');
+    } catch (e) {
+      throw new Error(`复核效果台账分片不可读：${p}（${e.message}）——坏分片不静默跳过`);
+    }
+    for (const line of text.split(/\r?\n/)) {
+      if (!/^\|\s*\d{4}-\d{2}-\d{2}\s*\|/.test(line)) continue; // 表头/分隔线/注记行跳过
+      const cells = line.split('|').slice(1, -1).map((c) => c.trim());
+      const bad = cells.length < 8 || [3, 4, 5, 6].some((i) => !/^\d+$/.test(cells[i]));
+      if (bad) throw new Error(`复核效果台账行字段非法（8 列起，意见数/采纳/拒绝/误报须为非负整数）：${p}\n  行：${line.trim()}`);
+      const [total, adopted, rejected, misreport] = [3, 4, 5, 6].map((i) => Number(cells[i]));
+      if (adopted + rejected + misreport !== total) {
+        throw new Error(`复核效果台账自洽破坏（采纳 ${adopted} + 拒绝 ${rejected} + 误报 ${misreport} = ${adopted + rejected + misreport} ≠ 意见数 ${total}）：${p}\n  行：${line.trim()}`);
+      }
+      const b = (byMonth[cells[0].slice(0, 7)] ||= { events: 0, total: 0, adopted: 0, rejected: 0, misreport: 0 });
+      b.events++;
+      b.total += total;
+      b.adopted += adopted;
+      b.rejected += rejected;
+      b.misreport += misreport;
+    }
+  }
+  return byMonth;
+}