agentic-flow-kit 1.8.1 → 1.8.7

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

@@ -14,10 +14,12 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadEnums } from './workflow-enums.mjs';
 import { readLedgerRows as loadLedgerRows } from './ledger-loader.mjs';
+import { analyze, buildDocList, loadLastTouch, loadLedgerTs, parseStatus, ACTIVE } from './archive-sweep.mjs';
 
 const USAGE = `用法：node .agents/scripts/gen-workflow-metrics.mjs [--month YYYY-MM] [--dry-run] [--help]
 
 事实源：workflow/{intents,specs,plans,incidents}/*.md（排除 _TEMPLATE.md）+ workflow/INDEX.md + .agents/rule-budgets.txt
+        + workflow/reviews.d/*.md（独立复核效果台账）+ workflow/specs/*.md 与 workflow/archive/*/specs/*.md（spec 体积观察）
 产物：workflow/metrics.md —— 每月一行（同月重跑即更新该行，不重复追加）；明细打印在 stdout，不落表。
 选项：
   --month YYYY-MM   指定月份键（默认取当前月；用于补记历史）
@@ -201,12 +203,134 @@ const sortedDays = [...funnel.days].sort((a, b) => a - b);
 const medianDays = sortedDays.length
   ? (sortedDays.length % 2 ? sortedDays[(sortedDays.length - 1) / 2] : (sortedDays[sortedDays.length / 2 - 1] + sortedDays[sortedDays.length / 2]) / 2)
   : null;
-const funnelRow = `| ${month} | ${funnel.closed} | ${funnel.full} | ${funnel.legacy} | ${funnel.once} | ${funnel.rework} | ${medianDays === null ? '—' : medianDays.toFixed(1)} | ${funnel.ledgerRows} |`;
+// 中位周期渲染：**真实的极小值不得被印成 `0.0`**。建件与确认常在同一会话内完成时，真实周期可 < 0.05 天，
+// `toFixed(1)` 会把它印成 `0.0`——读者无法区分「真实的亚小时周期」与「口径失效」。
+// 修法（最小）：仅当四舍五入会得到 `0.0` 且值 > 0 时改写 `<0.1`；null 写 `—`；恰好为 0 仍写 `0.0`。
+function fmtMedianDays(v) {
+  if (v == null) return '—';
+  const s = v.toFixed(1);
+  return s === '0.0' && v > 0 ? '<0.1' : s;
+}
+const funnelRow = `| ${month} | ${funnel.closed} | ${funnel.full} | ${funnel.legacy} | ${funnel.once} | ${funnel.rework} | ${fmtMedianDays(medianDays)} | ${funnel.ledgerRows} |`;
 
 const docs = scanDocs();
 const surf = scanSurface();
 const row = `| ${month} | ${docs.files}（活跃 ${docs.active} / 终态 ${docs.terminal}） | ${kb(docs.bytes)} | ${docs.withModule}/${docs.files} | ${kb(surf.total)}（峰值 ${surf.peak ? `${surf.peak.pct.toFixed(1)}% ${surf.peak.label}` : '—'}） | ${kb(idxBytes)}（${Number.isNaN(idxActive) ? '—' : idxActive} 行） |`;
 
+// ---- 复核效果（独立复核效果台账）：workflow/reviews.d/ 意见级处置分片按月聚合 ----
+// 口径：一行 = 一次独立复核事件；自洽不变式 = 采纳+拒绝+误报 = 意见数。台账是「门禁制造返工 vs 拦下问题」
+// 的意见级信号源，脏行比缺行更有害——字段非法 / 自洽破坏一律 throw（文案点名分片与行），不做静默跳过
+// （同本脚本 fail-loud 纪律）。目录不存在 = 合法零数据（机制先于数据建账，出占位行）。
+function scanReviews() {
+  const dir = path.join(WORKFLOW, '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;
+}
+const reviews = scanReviews();
+// 复核效果表头（第三表）。源 = workflow/reviews.d/ 意见级处置分片（一行 = 一次独立复核事件，
+// 采纳+拒绝+误报 = 意见数），整表确定性再生、历史行不落盘保留；区分「门禁制造返工 vs 拦下问题」。
+// 声明须在 DRY 出口之前（--dry-run 也打印该表）。
+const REVIEW_HEAD = [
+  '## 复核效果（源：workflow/reviews.d/ 意见级处置台账；存量未建账期无数据）',
+  '',
+  '| 月份 | 复核事件 | 意见数 | 采纳 | 拒绝 | 误报 | 采纳率 | 误报率 |',
+  '|---|---|---|---|---|---|---|---|',
+];
+// 整表由分片确定性再生（历史行不落盘保留，分片即真源）；率列 = 采纳（误报）÷ 意见数，意见数为 0 写 —。
+const reviewRows = Object.keys(reviews).sort().map((ym) => {
+  const b = reviews[ym];
+  const rate = (n) => (b.total ? `${((n / b.total) * 100).toFixed(0)}%` : '—');
+  return `| ${ym} | ${b.events} | ${b.total} | ${b.adopted} | ${b.rejected} | ${b.misreport} | ${rate(b.adopted)} | ${rate(b.misreport)} |`;
+});
+if (!reviewRows.length) reviewRows.push('| （无记录） | 0 | 0 | 0 | 0 | — | — |'); // 零数据占位——表始终输出，机制可见
+
+// ---- spec 体积观察（spec 生命周期口径）：活跃 specs + 归档 specs 分开统计，先观察后设限 ----
+// advisory 上限显式延后（先让体积可见）：本表只出数、不判限。
+// 口径：份数 = .md 数（排除 _TEMPLATE.md，与 scanDocs 一致）；行数 = 换行数（尾换行不生幻影行，对齐 wc -l）；
+//   验收条数 = `- [ ]`/`- [x]` checkbox 行总数（不区分勾选）；中位 = 升序取中，偶数取中间两数均值（可为 x.5）；
+//   归档 = workflow/archive/<月>/specs/ 各月合并。目录不存在 = 合法（该行出全 0，不报错）。
+const medianOf = (arr) => {
+  if (!arr.length) return 0;
+  const s = [...arr].sort((x, y) => x - y);
+  return s.length % 2 ? s[(s.length - 1) / 2] : (s[s.length / 2 - 1] + s[s.length / 2]) / 2;
+};
+function collectSpecMetrics(dir) {
+  if (!fs.existsSync(dir)) return null;
+  const lines = [];
+  const checks = [];
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
+    const text = fs.readFileSync(path.join(dir, f), 'utf8');
+    const ls = text.split(/\r?\n/);
+    if (ls[ls.length - 1] === '') ls.pop();
+    lines.push(ls.length);
+    checks.push((text.match(/^\s*- \[( |x)\]/gm) || []).length);
+  }
+  return { lines, checks };
+}
+const specStats = (m) => (m ? {
+  n: m.lines.length,
+  medLines: medianOf(m.lines),
+  maxLines: m.lines.length ? Math.max(...m.lines) : 0,
+  medChecks: medianOf(m.checks),
+  maxChecks: m.checks.length ? Math.max(...m.checks) : 0,
+} : null);
+const specActiveStats = specStats(collectSpecMetrics(path.join(WORKFLOW, 'specs')));
+const specArchiveMetrics = { lines: [], checks: [] };
+const archiveRoot = path.join(WORKFLOW, 'archive');
+if (fs.existsSync(archiveRoot)) {
+  for (const ent of fs.readdirSync(archiveRoot, { withFileTypes: true })) {
+    if (!ent.isDirectory()) continue;
+    const sub = collectSpecMetrics(path.join(archiveRoot, ent.name, 'specs'));
+    if (sub) {
+      specArchiveMetrics.lines.push(...sub.lines);
+      specArchiveMetrics.checks.push(...sub.checks);
+    }
+  }
+}
+const specArchiveStats = specStats(specArchiveMetrics);
+const fmtSpecNum = (v) => (Number.isInteger(v) ? String(v) : v.toFixed(1));
+const specRow = (label, st) => st
+  ? `| ${label} | ${st.n} | ${fmtSpecNum(st.medLines)} | ${st.maxLines} | ${fmtSpecNum(st.medChecks)} | ${st.maxChecks} |`
+  : `| ${label} | 0 | 0 | 0 | 0 | 0 |`;
+// spec 体积表头（第四表。先观察后设限：advisory 上限延后、不设门——口径单源 = workflow/README.md
+// 「spec 生命周期口径」条目）。整表每次确定性再生。
+const SPEC_HEAD = [
+  '## spec 体积观察（源：specs 活跃+归档全量扫描；advisory 上限延后——口径见 workflow/README.md「spec 生命周期口径」）',
+  '',
+  '| 范围 | 份数 | 行数中位 | 行数最大 | 验收条数中位 | 验收条数最大 |',
+  '|---|---|---|---|---|---|',
+];
+const specRows = [specRow('活跃', specActiveStats), specRow('归档', specArchiveStats)];
+
+
 // ---- 明细（stdout，不落表）：类型分布 + 逐条预算占用 ----
 console.log(`📅 ${month} 快照`);
 console.log(`  文档：${docs.files} 篇 / ${kb(docs.bytes)}（活跃 ${docs.active} / 终态 ${docs.terminal}${docs.invalid ? ` / 状态缺失或非法 ${docs.invalid}` : ''}）；模块已填 ${docs.withModule}/${docs.files}`);
@@ -214,12 +338,33 @@ for (const [t, v] of Object.entries(docs.perType)) console.log(`    ${t.padEnd(1
 console.log(`  索引：workflow/INDEX.md ${kb(idxBytes)}（活跃 ${Number.isNaN(idxActive) ? '—' : idxActive} 行）`);
 for (const e of surf.entries) console.log(`    ${e.label.padEnd(44)} ${String(e.max).padStart(6)} / ${String(e.lim).padStart(6)} B（${e.pct.toFixed(1)}%）`);
 console.log(`  常驻面合计：${kb(surf.total)}`);
-console.log(`  闭环漏斗：收口 ${funnel.closed}（完整链 ${funnel.full} = 一次通过 ${funnel.once} + 返工 ${funnel.rework}；协议前 ${funnel.legacy}）｜中位周期 ${medianDays === null ? '—' : `${medianDays.toFixed(1)} 天`}｜台账行 ${funnel.ledgerRows}`);
+console.log(`  闭环漏斗：收口 ${funnel.closed}（完整链 ${funnel.full} = 一次通过 ${funnel.once} + 返工 ${funnel.rework}；协议前 ${funnel.legacy}）｜中位周期 ${fmtMedianDays(medianDays)} 天｜台账行 ${funnel.ledgerRows}`);
 for (const it of funnel.items) console.log(`    ${String(it.doc).padEnd(58)} ${it.kind.padEnd(7)} ${it.days} 天`);
 if (funnel.items.length) console.log('  ℹ️ 机器口径可与 workflow/delegations.md 自做表的人工自报交叉对照（差异即信号，不对账）');
+// 归档积压提醒（2026-10-15 减重手段⑥ 自源仓回灌，回路别等人喊）：滚动归档已随确认门自动跑
+// （confirm-doc archive-on-close），历史积压走 archive-sweep 手工批次——月度 stdout 报候选数使积压可见。
+// 判定单源 = archive-sweep.analyze（21 天窗，禁第二套口径）；analyze/loadLastTouch 抛错（如
+// 浅克隆无 git 历史）fail-open 静默——观测提醒不挡快照。
+try {
+  const allDocs = buildDocList(process.cwd());
+  const arch = analyze({
+    docs: allDocs,
+    ledgerTs: loadLedgerTs(process.cwd()),
+    lastTouch: loadLastTouch(process.cwd()),
+    activeTexts: allDocs.filter((d) => ACTIVE.has(parseStatus(d.text))).map((d) => d.text),
+    windowDays: 21,
+  });
+  const fams = new Set(arch.candidates.map((x) => x.file));
+  console.log(`  归档积压：候选 ${arch.candidates.length} 篇 / ${fams.size} 族（21 天窗）${arch.candidates.length ? '——node .agents/scripts/archive-sweep.mjs 查看，--execute 执行' : ''}`);
+} catch { /* fail-open */ }
 console.log(`  ${DRY ? '（--dry-run，未写盘）' : ''}`);
 
-if (DRY) { console.log(`\n将写入行：\n${row}\n${funnelRow}`); process.exit(0); }
+if (DRY) {
+  console.log(`\n将写入行：\n${row}\n${funnelRow}`);
+  console.log(`\n复核效果表（整表再生）：\n${[...REVIEW_HEAD, ...reviewRows].join('\n')}`);
+  console.log(`\nspec 体积观察表（整表再生）：\n${[...SPEC_HEAD, ...specRows].join('\n')}`);
+  process.exit(0);
+}
 
 // ---- 组装：GENERATED 区内的月表按月份键 upsert（同月重跑覆盖，行序按月升序）----
 const HEADER = `# workflow 规模与规则面月度快照
@@ -231,9 +376,10 @@ const TABLE_HEAD = [
   '| 月份 | 文档（活跃/终态） | 文档字节 | 模块已填/总 | 常驻面字节（预算峰值） | INDEX（活跃行） |',
   '|---|---|---|---|---|---|',
 ];
-// 漏斗表头（第二表）
+// 漏斗表头（第二表）。中位渲染契约：取不到写 —；恰好 0 写 0.0；四舍五入会得 0.0 的真实极小值写 <0.1
+//（建件与确认常在同会话内完成时该列常态即亚小时级，勿读作口径失效）。
 const FUNNEL_HEAD = [
-  '## 闭环漏斗（机器口径，源：.agents/confirmations.jsonl）',
+  '## 闭环漏斗（机器口径，源：.agents/confirmations.jsonl。中位周期 = 该文件首次进入 git 到终态确认；取不到写 —，不写 0.0；真实极小值写 <0.1）',
   '',
   '| 月份 | 收口 | 完整链 | 协议前 | 一次通过 | 返工件 | 中位周期(天) | 台账行数 |',
   '|---|---|---|---|---|---|---|---|',
@@ -243,9 +389,12 @@ let rows = [];
 let funnelRows = [];
 if (existing.includes(BEGIN) && existing.includes(END)) {
   const section = existing.slice(existing.indexOf(BEGIN), existing.indexOf(END));
-  const marker = FUNNEL_HEAD[0];
-  const bodyPart = section.includes(marker) ? section.slice(0, section.indexOf(marker)) : section;
-  const funnelPart = section.includes(marker) ? section.slice(section.indexOf(marker)) : '';
+  // 分段标记用短语而非表头全文——表头措辞会随口径演进，回吸判据须与之解耦（旧文件的旧表头也能正确分段）
+  const funnelMarker = '## 闭环漏斗';
+  const reviewMarker = '## 复核效果'; // 复核行同为 `| YYYY-MM |` 形态，不切出会被误吸进漏斗行
+  const bodyPart = section.includes(funnelMarker) ? section.slice(0, section.indexOf(funnelMarker)) : section;
+  const restPart = section.includes(funnelMarker) ? section.slice(section.indexOf(funnelMarker)) : '';
+  const funnelPart = restPart.includes(reviewMarker) ? restPart.slice(0, restPart.indexOf(reviewMarker)) : restPart;
   rows = bodyPart.split(/\r?\n/).filter((l) => /^\|\s*\d{4}-\d{2}\s*\|/.test(l));
   funnelRows = funnelPart.split(/\r?\n/).filter((l) => /^\|\s*\d{4}-\d{2}\s*\|/.test(l));
 }
@@ -255,7 +404,7 @@ rows.sort((a, b) => a.slice(2, 9).localeCompare(b.slice(2, 9)));
 funnelRows = funnelRows.filter((l) => !l.startsWith(`| ${month} `));
 funnelRows.push(funnelRow);
 funnelRows.sort((a, b) => a.slice(2, 9).localeCompare(b.slice(2, 9)));
-const inner = `${BEGIN}\n\n${[...TABLE_HEAD, ...rows].join('\n')}\n\n${[...FUNNEL_HEAD, ...funnelRows].join('\n')}\n\n${END}`;
+const inner = `${BEGIN}\n\n${[...TABLE_HEAD, ...rows].join('\n')}\n\n${[...FUNNEL_HEAD, ...funnelRows].join('\n')}\n\n${[...REVIEW_HEAD, ...reviewRows].join('\n')}\n\n${[...SPEC_HEAD, ...specRows].join('\n')}\n\n${END}`;
 let out;
 if (existing.includes(BEGIN) && existing.includes(END)) {
   out = existing.slice(0, existing.indexOf(BEGIN)) + inner + existing.slice(existing.indexOf(END) + END.length);

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

@@ -216,6 +216,125 @@ const mkfixLedger = (lines) => {
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+{
+  // L8：亚小时真实周期（同会话建件+确认）→ 渲染 <0.1，不印 0.0（「取不到」与「极快」不得同形）
+  const root = mkfixLedger([
+    LROW({ ts: '2026-10-01T00:30:00.000Z' }),
+    LROW({ ts: '2026-10-01T01:00:00.000Z', stage: 'done', prev: 'approved' }),
+  ]);
+  const r = run(root, ['--month', '2026-10']);
+  const md = readMetrics(root);
+  check('漏斗 L8 亚小时真实周期渲染 <0.1（表行与 stdout 同步，不印 0.0）',
+    r.status === 0 && /\| 2026-10 \| 1 \| 1 \| 0 \| 1 \| 0 \| <0\.1 \| 2 \|/.test(md) && /中位周期 <0\.1 天/.test(r.stdout),
+    `${r.stdout}${md}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 复核效果台账：workflow/reviews.d/ 意见级处置分片 → 第三表 ----
+// mkfixReviews：在 mkfix 基础上写复核效果台账分片（shards: { 分片文件名: [数据行...] }，含表头）
+const mkfixReviews = (shards) => {
+  const root = mkfix();
+  fs.mkdirSync(path.join(root, 'workflow', 'reviews.d'), { recursive: true });
+  for (const [name, rows] of Object.entries(shards)) {
+    fs.writeFileSync(path.join(root, 'workflow', 'reviews.d', name), [
+      `# 独立复核效果台账 — ${name.replace(/\.md$/, '')}`,
+      '',
+      '| 日期 | 对象 | 复核员(宿主) | 意见数 | 采纳 | 拒绝 | 误报 | 备注 |',
+      '|------|------|--------------|--------|------|------|------|------|',
+      ...rows,
+      '',
+    ].join('\n'), 'utf8');
+  }
+  return root;
+};
+{
+  // R1：同月两行聚合 + 跨月分片各一行、按月升序（率列 = 采纳/误报 ÷ 意见数，toFixed(0)%）
+  const root = mkfixReviews({
+    '2026-10.md': [
+      '| 2026-10-14 | workflow/specs/2026-10-14-x.md | independent-reviewer(zcode) | 5 | 3 | 1 | 1 | P1 修 1；P2 采纳 3 拒 1 误 1 |',
+      '| 2026-10-16 | diff 318922a9..7c8d9eb7 | independent-reviewer(新会话) | 4 | 2 | 2 | 0 | P2×4 全采纳 |',
+    ],
+    '2026-09.md': [
+      '| 2026-09-30 | workflow/plans/2026-09-30-y.md | independent-reviewer(zcode) | 2 | 1 | 0 | 1 | 误报=指向已被覆盖的代码 |',
+    ],
+  });
+  const r = run(root, ['--month', '2026-10']);
+  const md = readMetrics(root);
+  check('复核 R1：同月两行聚合（事件 2 / 意见 9 / 采纳 5 / 拒绝 3 / 误报 1 / 采纳率 56% / 误报率 11%）',
+    r.status === 0 && /\| 2026-10 \| 2 \| 9 \| 5 \| 3 \| 1 \| 56% \| 11% \|/.test(md), `exit=${r.status}\n${r.stdout}${r.stderr}\n${md}`);
+  check('复核 R1：跨月分片各一行且按月升序（9 月 1/2/1/0/0 → 50%/50% 紧邻 10 月行）',
+    /## 复核效果[\s\S]*?\| 2026-09 \| 1 \| 2 \| 1 \| 0 \| 1 \| 50% \| 50% \|\n\| 2026-10 \|/.test(md), md);
+  check('复核 R1：复核行不被误吸进漏斗表（漏斗段零 2026-09 行——分段回吸切开了同形日期行）',
+    (() => { const seg = md.slice(md.indexOf('## 闭环漏斗'), md.indexOf('## 复核效果')); return !/\| 2026-09 \|/.test(seg); })(), md);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+{
+  // R2：自洽破坏（采纳+拒绝+误报 ≠ 意见数）→ fail-loud（exit 1，报文点名分片与不变式）
+  const root = mkfixReviews({
+    '2026-10.md': [
+      '| 2026-10-14 | workflow/specs/2026-10-14-x.md | independent-reviewer(zcode) | 5 | 2 | 1 | 1 | 2+1+1=4 ≠ 5，应被拦 |',
+    ],
+  });
+  const r = run(root, ['--month', '2026-10']);
+  check('复核 R2：自洽破坏（5 ≠ 2+1+1）→ exit 1 且报文含「自洽破坏」并点名分片 2026-10.md',
+    r.status === 1 && /自洽破坏/.test(r.stderr) && /2026-10\.md/.test(r.stderr), `exit=${r.status}\n${r.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+{
+  // R3：目录不存在 / 分片存在但空表 → 合法零数据，占位行不崩
+  const rootNone = mkfix(); // 不建 reviews.d
+  const rNone = run(rootNone, ['--month', '2026-10']);
+  const mdNone = readMetrics(rootNone);
+  check('复核 R3：目录不存在 → exit 0 且出「（无记录）」占位行',
+    rNone.status === 0 && /\| （无记录） \| 0 \| 0 \| 0 \| 0 \| — \| — \|/.test(mdNone), `exit=${rNone.status}\n${rNone.stderr}\n${mdNone}`);
+  fs.rmSync(rootNone, { recursive: true, force: true });
+  const rootEmpty = mkfixReviews({ '2026-10.md': [] }); // 分片存在、表为空
+  const rEmpty = run(rootEmpty, ['--month', '2026-10']);
+  const mdEmpty = readMetrics(rootEmpty);
+  check('复核 R3b：分片空表 → exit 0 且出「（无记录）」占位行',
+    rEmpty.status === 0 && /\| （无记录） \| 0 \| 0 \| 0 \| 0 \| — \| — \|/.test(mdEmpty), `exit=${rEmpty.status}\n${rEmpty.stderr}\n${mdEmpty}`);
+  fs.rmSync(rootEmpty, { recursive: true, force: true });
+}
+
+// ---- spec 体积观察（spec 生命周期口径）：活跃 specs + 归档 specs 分开统计 ----
+// mkSpec：生成恰好 lines 行（尾换行对齐 wc -l）、其中 checks 行为 checkbox 的 spec 文本
+const mkSpec = (lines, checks) => {
+  const rows = [`# spec 夹具 ${lines}行${checks}验收`];
+  for (let i = 0; i < checks; i++) rows.push(`- [${i % 2 ? 'x' : ' '}] 验收 ${i + 1}`);
+  while (rows.length < lines) rows.push('填充');
+  return rows.join('\n') + '\n';
+};
+{
+  // S1：活跃 2 份（10 行/3 验收、12 行/5 验收 → 偶数中位取均值）+ 归档 3 份跨单月目录（6/8/10 行 → 奇数中位取中）
+  const root = mkfix();
+  fs.writeFileSync(path.join(root, 'workflow', 'specs', '2026-10-01-a1.md'), mkSpec(10, 3), 'utf8');
+  fs.writeFileSync(path.join(root, 'workflow', 'specs', '2026-10-02-a2.md'), mkSpec(12, 5), 'utf8');
+  fs.writeFileSync(path.join(root, 'workflow', 'specs', '_TEMPLATE.md'), mkSpec(999, 9), 'utf8'); // 模板不计入
+  fs.mkdirSync(path.join(root, 'workflow', 'archive', '2026-09', 'specs'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'workflow', 'archive', '2026-09', 'specs', '2026-09-01-b1.md'), mkSpec(6, 2), 'utf8');
+  fs.writeFileSync(path.join(root, 'workflow', 'archive', '2026-09', 'specs', '2026-09-02-b2.md'), mkSpec(8, 4), 'utf8');
+  fs.writeFileSync(path.join(root, 'workflow', 'archive', '2026-09', 'specs', '2026-09-03-b3.md'), mkSpec(10, 1), 'utf8');
+  const r = run(root, ['--month', '2026-10']);
+  const md = readMetrics(root);
+  check('spec S1：活跃行（2 份 / 行数中位 11 = (10+12)/2 / 最大 12 / 验收中位 4 / 最大 5；_TEMPLATE 不计）',
+    r.status === 0 && /\| 活跃 \| 2 \| 11 \| 12 \| 4 \| 5 \|/.test(md), `exit=${r.status}\n${r.stderr}\n${md}`);
+  check('spec S1：归档行（3 份 / 行数中位 8 取中 / 最大 10 / 验收中位 2 / 最大 4）',
+    /\| 归档 \| 3 \| 8 \| 10 \| 2 \| 4 \|/.test(md), md);
+  check('spec S1：表序正确（复核效果表之后、GENERATED:END 之前）',
+    /## 复核效果[\s\S]*## spec 体积观察[\s\S]*<!-- GENERATED:END -->/.test(md), md);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+{
+  // S2：specs 目录空 + 无 archive 目录 → 两行全 0 不崩（合法零数据）
+  const root = mkfix();
+  const r = run(root, ['--month', '2026-10']);
+  const md = readMetrics(root);
+  check('spec S2：specs 空目录 + 无 archive → 活跃/归档两行全 0，exit 0',
+    r.status === 0 && /\| 活跃 \| 0 \| 0 \| 0 \| 0 \| 0 \|/.test(md) && /\| 归档 \| 0 \| 0 \| 0 \| 0 \| 0 \|/.test(md),
+    `exit=${r.status}\n${r.stderr}\n${md}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log(`\n${USAGE}`);

package/templates/_agents/scripts/lane-surface-audit.test.mjs

@@ -89,5 +89,5 @@ const run = (root, ...args) => {
   check('场景 4：incident（发现键）×3 → db/procs 候选', r.code === 0 && r.out.includes('db/procs'), r.out);
 }
 
-console.log(`\n${fail ? `❌ ${fail} failed` : '✅ all passed'}（${pass} passed）`);
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

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

@@ -226,8 +226,30 @@ export function renderShard(name, rows, eol = '\n') {
   return out.length ? `${out.join(eol)}${eol}` : '';
 }
 
+// insertIntoSection(text, section, lines)：把行插进已有分片的对应 ## 节（下一节标题之前）。
+// 节不存在则整节追加到文末。无 section 的行不走这里（保持追加到文末 = 末表）。
+function insertIntoSection(text, section, lines) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const parts = text.split(/\r?\n/);
+  if (parts.length && parts[parts.length - 1] === '') parts.pop();
+  const start = parts.findIndex((l) => l.startsWith('## ') && l.includes(section));
+  if (start < 0) {
+    return `${parts.join(eol)}${eol}${eol}## ${section}${eol}${eol}${lines.join(eol)}${eol}`;
+  }
+  let end = parts.length;
+  for (let i = start + 1; i < parts.length; i++) {
+    if (parts[i].startsWith('## ')) { end = i; break; }
+  }
+  let at = end;
+  while (at > start && parts[at - 1].trim() === '') at--;
+  parts.splice(at, 0, ...lines);
+  return `${parts.join(eol)}${eol}`;
+}
+
 // appendRows(root, name, rows, { month, section })：把数据行追加进指定月分片（缺省取行内日期月）。
 // rows 可为字符串数组或 { line, section } 数组（多表台账须带 section 才能归对表）。
+// 分片已存在时：带 section 的行插入该节（不落到文末自做表）；不带 section 的行仍追加到文末
+// （2026-10-16 自源仓 13f67ef7 回灌——修「合并丢共有行」时新增行误落末表）。
 // 返回实际写入的分片路径列表。写失败 fail-loud（不静默吞）。
 export function appendRows(root, name, rows, { month, section = '' } = {}) {
   const written = [];
@@ -247,9 +269,21 @@ export function appendRows(root, name, rows, { month, section = '' } = {}) {
     const existingRows = new Set(existing.split(/\r?\n/).filter((l) => l.trim()));
     const fresh = rs.filter((r) => !existingRows.has(r.line));
     if (!fresh.length) { written.push(p); continue; } // 已在分片 → 幂等跳过
-    const next = existing
-      ? `${existing.replace(/\s*$/, '')}\n${fresh.map((r) => r.line).join('\n')}\n`
-      : renderShard(name, fresh, '\n');
+    let next;
+    if (!existing) next = renderShard(name, fresh, '\n');
+    else {
+      const placed = fresh.filter((r) => r.section);
+      const tail = fresh.filter((r) => !r.section);
+      let text = existing;
+      const bySec = new Map();
+      for (const r of placed) {
+        if (!bySec.has(r.section)) bySec.set(r.section, []);
+        bySec.get(r.section).push(r.line);
+      }
+      for (const [sec, lines] of bySec) text = insertIntoSection(text, sec, lines);
+      if (tail.length) text = `${text.replace(/\s*$/, '')}\n${tail.map((r) => r.line).join('\n')}\n`;
+      next = text.endsWith('\n') ? text : `${text}\n`;
+    }
     fs.writeFileSync(p, next, 'utf8');
     written.push(p);
   }
@@ -296,11 +330,14 @@ function main() {
     if (!row) { console.error('--append 须带 --row "<数据行>"'); process.exit(2); }
     const mIdx = argv.indexOf('--month');
     const month = mIdx >= 0 ? argv[mIdx + 1] : undefined;
-    const written = appendRows(root, name, [row], { month });
+    const sIdx = argv.indexOf('--section');
+    const section = sIdx >= 0 ? argv[sIdx + 1] : '';
+    if (sIdx >= 0 && !section) { console.error('--section 须带节标题（如 委派结果）'); process.exit(2); }
+    const written = appendRows(root, name, [row], { month, section });
     console.log(`✓ 追加 1 行 → ${written.map((p) => path.relative(root, p).split(path.sep).join('/')).join(', ')}`);
     return;
   }
-  console.error('用法：node .agents/scripts/ledger-shards.mjs --check | --split <ledger> [--dry-run] | --append <ledger> --row "<行>" [--month YYYY-MM]');
+  console.error('用法：node .agents/scripts/ledger-shards.mjs --check | --split <ledger> [--dry-run] | --append <ledger> --row "<行>" [--month YYYY-MM] [--section <节标题>]');
   process.exit(2);
 }
 

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

@@ -247,6 +247,23 @@ const wf = (root, ...p) => path.join(root, 'workflow', ...p);
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- S20 appendRows --section（2026-10-16 自源仓 13f67ef7 回灌）：已有双表时委派行插入委派节，
+//      不带 section 仍落文末（修「合并丢共有行」时新增行误落末表）----
+{
+  const root = mkroot();
+  appendRows(root, 'delegations', ['| 2026-10-15 | model | 委派甲 | 一次通过 | 备注 | |'], { section: '委派结果' });
+  appendRows(root, 'delegations', ['| 2026-10-15 | 自做甲 | 一次通过 | 备注 | |'], { section: '自做任务结果' });
+  appendRows(root, 'delegations', ['| 2026-10-15 | model | 委派乙 | 一次通过 | 备注 | |'], { section: '委派结果' });
+  appendRows(root, 'delegations', ['| 2026-10-15 | 自做乙 | 一次通过 | 备注 | |']);
+  const shard = fs.readFileSync(shardPathFor(root, 'delegations', '2026-10'), 'utf8');
+  const iSelf = shard.indexOf('## 自做任务结果');
+  const iDelegRow = shard.indexOf('委派乙');
+  const iSelfRow = shard.indexOf('自做乙');
+  check('S20 后追加的委派行仍在自做节之前', iDelegRow >= 0 && iDelegRow < iSelf, shard);
+  check('S20b 不带 section 的行落在文末', iSelf >= 0 && iSelf < iSelfRow, shard);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 // ---- S18 appendRows 幂等：同行走两次只落一次 ----
 {
   const root = mkroot();

package/templates/_agents/scripts/mechanism-retire-watch.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// mechanism-retire-watch.mjs — 机制退役催办自动化（2026-10-14 源仓 L5 自举接线 1b/1c；2026-10-16 回灌 kit）
+// 用途：读机制台账「退役阈值/最近触发」+ judgments 聚合，阈值触达自动产动作项——让机制的「死」与「生」同样强制。
+//   自动化的是**感知/排序**（谁触达了阈值），处置仍人放行（改状态/删代码走人 + 一进一出）。
+// 口径单源：.agents/mechanism-registry.md 列序（机制|门禁位置|触发统计口径|退役阈值|最近触发|状态|处置期限）
+//   与 .agents/judgments.jsonl（check-loop 每次真实运行落账，per-rule WARN/BLOCK 计数）。
+// 判定（确定性，无 LLM）：
+//   ① 现役行 + 阈值形态「连续 N 月 = 0」+ 口径列含「规则名」→ 以有数据的末月为终点取 N 个日历月，缺月不算零命中，全 0 即触达 → 动作项。
+//   ② 待退役行 + 处置期限为日期且已过 → 动作项（逾期）。
+//   ③ 其余阈值形态（不退役主干 / 使用率型 / 数据源型）→ 非自动可判，仅计数，交人工月判。
+//   缺月不算零命中（2026-10-15 源仓修正）：漏跑数月后陈旧月份不得凑成「连续」——日历窗口内有缺月即
+//   交人工判，不产触达动作（与 agg-judgments --retire-candidates 的「数据月」口径互补：彼按有数据月，
+//   此按日历连续）。
+// 退出码恒 0（催办报告不该阻断调度器；测量失败打 [ERROR] 行）。
+// 用法：node .agents/scripts/mechanism-retire-watch.mjs [--json] [--root <仓库根>] [--now <ISO 日期>]
+// 测试：node .agents/scripts/mechanism-retire-watch.test.mjs（纯函数 evaluate 进程内断言）
+// kit 适配（源仓→kit）：台账路径 `.agents/config/mechanism-registry.md` → kit 平铺
+//   `.agents/mechanism-registry.md`（同 check-registry.mjs 检查 22 口径）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { aggFromRows } from './agg-judgments.mjs';
+
+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 asJson = argv.includes('--json');
+const ROOT = path.resolve(argOf('--root') || path.join(SCRIPT_DIR, '..', '..'));
+const NOW = argOf('--now') ? new Date(argOf('--now')) : new Date();
+
+const REGISTRY_REL = path.join('.agents', 'mechanism-registry.md');
+const LEDGER_REL = path.join('.agents', 'judgments.jsonl');
+
+// parseRegistry(text)：7 列管道表 → 行对象数组。列序固定（check-loop §22 按此解析）。
+export function parseRegistry(text) {
+  const rows = [];
+  for (const l of String(text).split(/\r?\n/)) {
+    if (!/^\|/.test(l)) continue;
+    if (/^\|[\s:|-]+\|?\s*$/.test(l)) continue; // 分隔行
+    const cells = l.split('|').slice(1, -1).map((c) => c.trim());
+    if (cells.length !== 7) continue;
+    if (cells[0] === '机制') continue; // 表头
+    const [name, gate, criterion, threshold, lastTrigger, status, deadline] = cells;
+    rows.push({ name, gate, criterion, threshold, lastTrigger, status, deadline });
+  }
+  return rows;
+}
+
+// ruleNamesOf(criterion)：从「触发统计口径」列抽「」内规则名（/ 分隔）。无「」= 无法自动映射。
+export function ruleNamesOf(criterion) {
+  const names = [];
+  for (const m of String(criterion).matchAll(/「([^」]+)」/g)) {
+    for (const n of m[1].split('/')) {
+      const t = n.trim();
+      if (t) names.push(t);
+    }
+  }
+  return names;
+}
+
+// zeroMonthsOf(threshold)：阈值形态「连续 N 月 = 0」→ N；否则 null（非自动可判）。
+export function zeroMonthsOf(threshold) {
+  const m = String(threshold).match(/连续\s*(\d+)\s*月\s*=\s*0/);
+  return m ? Number(m[1]) : null;
+}
+
+// localDay(d)：本地日历日 YYYY-MM-DD。期限比较不用 UTC 零点，避免北京时 08:00 后把当天判逾期。
+export function localDay(d) {
+  const dt = d instanceof Date ? d : new Date(d);
+  const m = String(dt.getMonth() + 1).padStart(2, '0');
+  const day = String(dt.getDate()).padStart(2, '0');
+  return `${dt.getFullYear()}-${m}-${day}`;
+}
+
+// calendarWindow(endYm, n)：以有数据的末月为终点，向前取 n 个日历月（含终点）。
+export function calendarWindow(endYm, n) {
+  const [y, m] = String(endYm).split('-').map(Number);
+  const out = [];
+  for (let i = n - 1; i >= 0; i--) {
+    const d = new Date(Date.UTC(y, m - 1 - i, 1));
+    out.push(`${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`);
+  }
+  return out;
+}
+
+// evaluate(registryRows, judgmentRows, now)：纯函数——产动作项。测试进程内断言。
+export function evaluate(registryRows, judgmentRows, now = new Date()) {
+  const { byMonth } = aggFromRows(judgmentRows || [], null);
+  const months = Object.keys(byMonth).sort(); // 升序
+  const actions = [];
+  const notAuto = [];
+
+  for (const r of registryRows) {
+    if (r.status === '已退役') continue;
+
+    if (r.status === '待退役') {
+      const d = String(r.deadline).match(/\d{4}-\d{2}-\d{2}/);
+      if (d && localDay(now) > d[0]) {
+        actions.push({ kind: 'overdue', name: r.name, detail: `待退役处置期限 ${d[0]} 已过（今 ${localDay(now)}）——按台账维护纪律「退役动作」当日删代码+测试+更新本表` });
+      } else if (!d) {
+        actions.push({ kind: 'no-deadline', name: r.name, detail: `待退役但处置期限非日期（${r.deadline || '空'}）——补时间表或改回现役` });
+      }
+      continue;
+    }
+
+    // 现役
+    const n = zeroMonthsOf(r.threshold);
+    const rules = ruleNamesOf(r.criterion);
+    if (n === null) { notAuto.push({ name: r.name, reason: '阈值形态非「连续 N 月 = 0」' }); continue; }
+    if (!rules.length) { notAuto.push({ name: r.name, reason: '口径列未列规则名（无法映射 judgments）' }); continue; }
+    if (months.length < n) { notAuto.push({ name: r.name, reason: `judgments 仅 ${months.length} 月 < 阈值 ${n} 月（数据不足）` }); continue; }
+
+    // 日历连续：缺月不算零命中（漏跑数月后陈旧月份不得凑成「连续」）。
+    const window = calendarWindow(months[months.length - 1], n);
+    const missing = window.filter((ym) => !byMonth[ym]);
+    if (missing.length) {
+      notAuto.push({ name: r.name, reason: `日历窗口 ${window.join(' / ')} 缺月 ${missing.join(' / ')}（断档不算零命中）` });
+      continue;
+    }
+    const hits = window.map((ym) => {
+      const cell = byMonth[ym].rules;
+      let c = 0;
+      for (const rule of rules) {
+        const e = cell[rule];
+        if (e) c += (e.WARN || 0) + (e.BLOCK || 0);
+      }
+      return { ym, count: c };
+    });
+    const total = hits.reduce((s, h) => s + h.count, 0);
+    if (total === 0) {
+      actions.push({ kind: 'threshold', name: r.name, detail: `连续 ${n} 月零触发（${window.join(' / ')}；规则 ${rules.join('、')}）——阈值触达，评估退役（改状态「待退役」并填处置期限）` });
+    }
+  }
+  return { actions, notAuto, months, monthCount: months.length };
+}
+
+function readJudgments(root) {
+  const p = path.join(root, LEDGER_REL);
+  if (!fs.existsSync(p)) return { rows: [], missing: true };
+  const rows = [];
+  for (const line of fs.readFileSync(p, 'utf8').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try { rows.push(JSON.parse(line)); } catch { /* 坏行跳过，不中断 */ }
+  }
+  return { rows, missing: false };
+}
+
+function main() {
+  const regPath = path.join(ROOT, REGISTRY_REL);
+  if (!fs.existsSync(regPath)) {
+    console.error(`[ERROR] mechanism-retire-watch: 台账不存在 ${REGISTRY_REL}`);
+    if (asJson) console.log(JSON.stringify({ error: 'registry-missing', actions: [] }, null, 2));
+    process.exit(0);
+  }
+  const registryRows = parseRegistry(fs.readFileSync(regPath, 'utf8'));
+  const { rows: judgmentRows, missing } = readJudgments(ROOT);
+  const { actions, notAuto, monthCount } = evaluate(registryRows, judgmentRows, NOW);
+
+  if (asJson) {
+    console.log(JSON.stringify({ registryRows: registryRows.length, judgmentMonths: monthCount, judgmentsMissing: missing, actions, notAuto }, null, 2));
+    return;
+  }
+
+  console.log(`# 机制退役催办（${NOW.toISOString()}）`);
+  console.log('');
+  console.log(`台账 ${REGISTRY_REL}｜机制行 ${registryRows.length}｜judgments 月数 ${monthCount}${missing ? '（台账缺失——尚无运行记录）' : ''}`);
+  console.log('');
+  if (!actions.length) {
+    console.log('✅ 无阈值触达 / 无逾期——本轮无动作项。');
+  } else {
+    console.log(`## 动作项 ${actions.length} 条`);
+    for (const a of actions) console.log(`- [${a.kind}] ${a.name}：${a.detail}`);
+  }
+  if (notAuto.length) {
+    console.log('');
+    console.log(`## 非自动可判（${notAuto.length} 条，交人工月判）`);
+    for (const x of notAuto) console.log(`- ${x.name}：${x.reason}`);
+  }
+  console.log('');
+  console.log('> 处置仍人放行：改状态/删代码走人 + 一进一出（台账维护纪律）。本报告不自动改文件。');
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) main();