agentic-flow-kit 1.8.2 → 2.0.0

package/templates/engine/.agents/scripts/agg-judgments.mjs

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+// agg-judgments.mjs — check-loop 判定流水月度聚合（judgment-ledger）
+// 用法：node .agents/scripts/agg-judgments.mjs [--month=YYYY-MM]
+//       node .agents/scripts/agg-judgments.mjs --retire-candidates [--months=6]
+//       node .agents/scripts/agg-judgments.mjs --emit-month[=YYYY-MM]
+// 源：.agents/judgments.jsonl（check-loop.mjs 每次真实运行追加一行，本地 gitignore；
+//     缺文件 = 尚无运行记录，提示后 exit 0——与 delegations 台账「必在」不同，这是渐积数据）。
+// 仓库级数据面（gate-metrics-shard 2026-10-22）：--emit-month 把某月聚合落成
+//     workflow/gate-metrics.d/<YYYY-MM>.jsonl（每月一行，随提交入库；多机并集）。
+//     --retire-candidates 读「本地台账 ∪ 分片」——换机/换树不再归零，退役判据才有燃料。
+// 消费：mechanism-registry 月度对账（「触发统计口径」列的 WARN/BLOCK 计数）与 advisory→hard
+//     升格 / 退役判定的直接查账面——替代原「人工 grep check-loop 输出」。
+// --retire-candidates（2026-10-15 减重手段①，规则的死亡机制）：列出「连续 N 个有数据月零命中
+//     （WARN+BLOCK 全为 0）」的规则作为退役候选——月度对账时按 mechanism-registry「退役判据」列
+//     逐条裁决（安全主干/级别闭环主干等「不退役」行除外；「且 X 停滞」类附加条件由人判）。
+//     台账不足 N 个数据月 → 数据不充分，不产候选（年轻遥测不得制造假候选）。判定口径 = 尾部
+//     N 个「有运行的月」（非日历月——遥测断档的月不算零命中，防漏跑误判退役）。
+// 测试面已随引擎减重退役（2026-10-28，owner 决策），本脚本现无测试兜底
+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 ROOT = path.resolve(SCRIPT_DIR, '..', '..');
+const LEDGER = path.join(ROOT, '.agents', 'judgments.jsonl');
+
+const argMonth = (process.argv.find((a) => a.startsWith('--month=')) || '').split('=')[1] || null;
+
+// aggFromRows(rows, month)：按月×规则×级别聚合。rows = 已解析的台账行数组；
+// month = 'YYYY-MM' 过滤（null = 全部）。输出 { byMonth: { 'YYYY-MM': { runs, rules: { rule: { WARN, BLOCK } } } } }。
+export function aggFromRows(rows, month = null) {
+  const byMonth = {};
+  for (const row of rows || []) {
+    if (typeof row.ts !== 'string' || !/^\d{4}-\d{2}/.test(row.ts)) continue;
+    const ym = row.ts.slice(0, 7);
+    if (month && ym !== month) continue;
+    const b = (byMonth[ym] ||= { runs: 0, rules: {} });
+    b.runs++;
+    for (const r of Array.isArray(row.rules) ? row.rules : []) {
+      if (!r || typeof r.rule !== 'string') continue;
+      const cell = (b.rules[r.rule] ||= { WARN: 0, BLOCK: 0 });
+      if (r.level === 'WARN') cell.WARN += r.count || 0;
+      else if (r.level === 'BLOCK') cell.BLOCK += r.count || 0;
+    }
+  }
+  return { byMonth };
+}
+
+function readRowsAt(root) {
+  const p = path.join(root, '.agents', 'judgments.jsonl');
+  if (!fs.existsSync(p)) return null;
+  const rows = [];
+  let bad = 0;
+  for (const line of fs.readFileSync(p, 'utf8').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      rows.push(JSON.parse(line));
+    } catch {
+      bad++;
+    }
+  }
+  return { rows, bad };
+}
+
+function readRows() {
+  return readRowsAt(ROOT);
+}
+
+// ---- 月度分片（gate-metrics-shard 2026-10-22）----
+// judgments.jsonl 是 per-worktree / gitignore 的本地台账——换机、换 worktree 即归零，退役判据
+// （连续 N 月 = 0）永远缺燃料。分片 = 仓库级事实：workflow/gate-metrics.d/<YYYY-MM>.jsonl，
+// 每月一行（与台账同构：ts + rules），多机并集（.gitattributes merge=jsonl-union）。
+// 读侧 mergeJudgmentRows 按月×规则取 max（分片是月末快照，本地可能更新；max 幂等、不重复计）。
+export const SHARD_DIR_REL = path.join('workflow', 'gate-metrics.d');
+
+export function shardPath(root, ym) {
+  return path.join(root, SHARD_DIR_REL, `${ym}.jsonl`);
+}
+
+/** 读全部分片 → 行数组（坏行跳过；目录缺失 = 空）。 */
+export function readShards(root) {
+  const dir = path.join(root, SHARD_DIR_REL);
+  if (!fs.existsSync(dir)) return [];
+  const rows = [];
+  for (const f of fs.readdirSync(dir).filter((x) => /^\d{4}-\d{2}\.jsonl$/.test(x)).sort()) {
+    for (const line of fs.readFileSync(path.join(dir, f), 'utf8').split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try { rows.push(JSON.parse(line)); } catch { /* 坏行跳过，不中断 */ }
+    }
+  }
+  return rows;
+}
+
+/** 按月×规则聚合（内部用；与 aggFromRows 同口径，不做 month 过滤）。 */
+function monthRuleCounts(rows) {
+  const out = {};
+  for (const row of rows || []) {
+    if (typeof row.ts !== 'string' || !/^\d{4}-\d{2}/.test(row.ts)) continue;
+    const ym = row.ts.slice(0, 7);
+    const b = (out[ym] ||= { runs: 0, rules: {} });
+    b.runs++;
+    for (const r of Array.isArray(row.rules) ? row.rules : []) {
+      if (!r || typeof r.rule !== 'string') continue;
+      const cell = (b.rules[r.rule] ||= { WARN: 0, BLOCK: 0 });
+      if (r.level === 'WARN') cell.WARN += r.count || 0;
+      else if (r.level === 'BLOCK') cell.BLOCK += r.count || 0;
+    }
+  }
+  return out;
+}
+
+/**
+ * 合并本地台账行 ∪ 分片行：按月×规则取 max（幂等；同月不重复计）。
+ * 返回合成行（每月一行，ts = 月初），可直接喂 aggFromRows / evaluate。
+ */
+export function mergeJudgmentRows(localRows, shardRows) {
+  const a = monthRuleCounts(localRows);
+  const b = monthRuleCounts(shardRows);
+  const months = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+  const out = [];
+  for (const ym of months) {
+    const rules = {};
+    for (const src of [a[ym], b[ym]]) {
+      if (!src) continue;
+      for (const [rule, cell] of Object.entries(src.rules)) {
+        const cur = (rules[rule] ||= { WARN: 0, BLOCK: 0 });
+        cur.WARN = Math.max(cur.WARN, cell.WARN);
+        cur.BLOCK = Math.max(cur.BLOCK, cell.BLOCK);
+      }
+    }
+    const list = [];
+    for (const rule of Object.keys(rules).sort()) {
+      const c = rules[rule];
+      if (c.WARN) list.push({ rule, level: 'WARN', count: c.WARN });
+      if (c.BLOCK) list.push({ rule, level: 'BLOCK', count: c.BLOCK });
+    }
+    out.push({ ts: `${ym}-01T00:00:00.000Z`, mode: 'monthly', rev: null, blockers: 0, warnings: 0, rules: list });
+  }
+  return out;
+}
+
+/** 读本地台账 + 分片并合并（退役判据的仓库级数据面）。 */
+export function readAllJudgments(root = ROOT) {
+  const local = readRowsAt(root);
+  const localRows = local ? local.rows : [];
+  const shardRows = readShards(root);
+  return {
+    rows: mergeJudgmentRows(localRows, shardRows),
+    localRows,
+    shardRows,
+    missing: localRows.length === 0 && shardRows.length === 0,
+  };
+}
+
+/** 生成某月分片（幂等：本地 ∪ 既有分片取 max）。无命中记录 → 不写空分片；内容未变 → 不重写。 */
+export function emitMonth(root, ym) {
+  const local = readRowsAt(root);
+  const localRows = (local ? local.rows : []).filter((r) => String(r.ts || '').slice(0, 7) === ym);
+  const existing = readShards(root).filter((r) => String(r.ts || '').slice(0, 7) === ym);
+  const merged = mergeJudgmentRows(localRows, existing).find((r) => String(r.ts).slice(0, 7) === ym);
+  if (!merged || !merged.rules.length) return { written: false, reason: 'no-data' };
+  const p = shardPath(root, ym);
+  const next = `${JSON.stringify(merged)}\n`;
+  let prev = '';
+  try { prev = fs.readFileSync(p, 'utf8'); } catch { /* 首次生成 */ }
+  if (prev === next) return { written: false, unchanged: true, path: p, rules: merged.rules.length };
+  fs.mkdirSync(path.join(root, SHARD_DIR_REL), { recursive: true });
+  fs.writeFileSync(p, next);
+  return { written: true, changed: true, path: p, rules: merged.rules.length };
+}
+
+/** 默认月 = 上一个 UTC 日历月（月度聚合只归档已结束的月）。 */
+export function prevMonthKey(now = new Date()) {
+  const d = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1));
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+
+// retireCandidates(rows, windowMonths)：退役候选 = 「尾部 windowMonths 个有数据月零命中」的规则。
+// 口径：数据月 = 该月至少一次运行（断档月不参与，不按零命中计）；候选须在全历史出现过（含只剩
+//   零命中的月）且尾部窗口内 WARN+BLOCK 全 0。输出按全历史命中数升序（最冷门在前）。
+//   rows 不足 windowMonths 个数据月 → { sufficient:false }——年轻遥测不产候选。
+export function retireCandidates(rows, windowMonths = 6) {
+  const { byMonth } = aggFromRows(rows);
+  const months = Object.keys(byMonth).sort();
+  if (months.length < windowMonths) {
+    return { sufficient: false, dataMonths: months.length, windowMonths, candidates: [], recentHits: [] };
+  }
+  const trailing = new Set(months.slice(-windowMonths));
+  const allRules = new Set();
+  for (const ym of months) for (const r of Object.keys(byMonth[ym].rules)) allRules.add(r);
+  const candidates = [];
+  const recentHits = [];
+  for (const rule of allRules) {
+    let total = 0;
+    let lastHit = null;
+    let inWindow = 0;
+    for (const ym of months) {
+      const cell = byMonth[ym].rules[rule];
+      const n = cell ? (cell.WARN + cell.BLOCK) : 0;
+      total += n;
+      if (n > 0) {
+        lastHit = ym;
+        if (trailing.has(ym)) inWindow += n;
+      }
+    }
+    const row = { rule, total, lastHit };
+    if (inWindow === 0) candidates.push(row);
+    else recentHits.push(row);
+  }
+  candidates.sort((a, b) => a.total - b.total || a.rule.localeCompare(b.rule));
+  recentHits.sort((a, b) => b.total - a.total || a.rule.localeCompare(b.rule));
+  return {
+    sufficient: true,
+    dataMonths: months.length,
+    windowMonths,
+    windowFrom: months.slice(-windowMonths)[0],
+    windowTo: months[months.length - 1],
+    candidates,
+    recentHits,
+  };
+}
+
+function printRetireCandidates(read) {
+  const wArg = Number((process.argv.find((a) => a.startsWith('--months=')) || '').split('=')[1]);
+  const windowMonths = Number.isFinite(wArg) && wArg >= 1 ? Math.floor(wArg) : 6;
+  const r = retireCandidates(read.rows, windowMonths);
+  if (!r.sufficient) {
+    console.log(`agg-judgments: 退役候选窗口 ${windowMonths} 个月——数据月仅 ${r.dataMonths} 个（台账 ${read.rows.length} 行），数据不充分不产候选。继续积累运行记录。`);
+    return;
+  }
+  console.log(`退役候选（零命中窗口 ${r.windowFrom}..${r.windowTo}，共 ${r.windowMonths} 个数据月）——仅机械筛查，裁决走 mechanism-registry「退役判据」列（「不退役」主干除外）：`);
+  if (!r.candidates.length) {
+    console.log('  （无候选——尾部窗口内所有规则均有命中）');
+  }
+  for (const c of r.candidates) {
+    console.log(`  候选  ${c.rule.padEnd(24)} 全历史命中 ${String(c.total).padStart(4)}  末次命中 ${c.lastHit || '—'}`);
+  }
+  for (const c of r.recentHits) {
+    console.log(`  在役  ${c.rule.padEnd(24)} 全历史命中 ${String(c.total).padStart(4)}  末次命中 ${c.lastHit}`);
+  }
+  if (read.bad) console.error(`agg-judgments: 跳过坏行 ${read.bad}（JSON 解析失败，不中断聚合）`);
+}
+
+function main() {
+  // --emit-month[=YYYY-MM]：把某月判定聚合落成入库分片（默认上一个 UTC 月）。
+  const emitArg = process.argv.find((a) => a === '--emit-month' || a.startsWith('--emit-month='));
+  if (emitArg) {
+    const explicit = emitArg.includes('=') ? emitArg.split('=')[1] : '';
+    const ym = explicit || prevMonthKey();
+    if (!/^\d{4}-\d{2}$/.test(ym)) {
+      console.error(`agg-judgments: --emit-month 须为 YYYY-MM（现 ${ym}）`);
+      process.exit(2);
+    }
+    const r = emitMonth(ROOT, ym);
+    if (r.reason === 'no-data') {
+      console.log(`agg-judgments: ${ym} 无命中记录——不生成空分片（本地台账 ${(readRows()?.rows || []).length} 行）`);
+      return;
+    }
+    if (r.unchanged) {
+      console.log(`agg-judgments: ${ym} 分片已是最新（${r.rules} 条规则）`);
+      return;
+    }
+    console.log(`✅ 已生成 ${path.relative(ROOT, r.path)}（${r.rules} 条规则）——随同提交入库（退役判据的仓库级燃料）`);
+    return;
+  }
+  if (process.argv.includes('--retire-candidates')) {
+    // 仓库级数据面：本地台账 ∪ 月度分片（换机/换树不再归零）。
+    const all = readAllJudgments(ROOT);
+    if (all.missing) {
+      console.error(`agg-judgments: ${path.relative(ROOT, LEDGER)} 与 ${SHARD_DIR_REL} 均无记录——尚无运行记录（check-loop 真实运行一次即有一行）`);
+      process.exit(0);
+    }
+    printRetireCandidates({ rows: all.rows, bad: 0 });
+    return;
+  }
+  const read = readRows();
+  if (!read) {
+    console.error(`agg-judgments: ${path.relative(ROOT, LEDGER)} 不存在——尚无运行记录（check-loop 真实运行一次即有一行）`);
+    process.exit(0);
+  }
+  const { byMonth } = aggFromRows(read.rows, argMonth);
+  const months = Object.keys(byMonth).sort();
+  if (!months.length) {
+    console.log(`agg-judgments: ${argMonth || '全部月份'} 无记录（台账共 ${read.rows.length} 行）`);
+    return;
+  }
+  for (const ym of months) {
+    const b = byMonth[ym];
+    console.log(`📅 ${ym}｜运行 ${b.runs} 次`);
+    const rules = Object.keys(b.rules).sort();
+    if (!rules.length) { console.log('    （无规则判定）'); continue; }
+    for (const rule of rules) {
+      const { WARN, BLOCK } = b.rules[rule];
+      console.log(`    ${rule.padEnd(24)} WARN×${WARN}  BLOCK×${BLOCK}`);
+    }
+  }
+  if (read.bad) console.error(`agg-judgments: 跳过坏行 ${read.bad}（JSON 解析失败，不中断聚合）`);
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('agg-judgments.mjs');
+if (isMain) main();

package/templates/engine/.agents/scripts/agg-kb-usage.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// agg-kb-usage — 笔记层置信度衰减聚合（2026-11-11，对照 Anthropic《The components of agent memory》Dreaming「记忆负债」）
+// 定位：把 kb-search 的命中遥测（.agents/cache/kb-usage.jsonl）聚合成「冷数据候选」——
+//   对 workflow/wiki 文档做「访问/命中 + 内容更新」双维度置信度衰减筛查。只做机械筛查与候选输出，
+//   裁决由主智能体/用户执行（归档 archive-sweep / 更新 wiki 技能 / 删除须用户单独指令）。
+// 用法：
+//   node .agents/scripts/agg-kb-usage.mjs                      # 默认：3 个数据月起步、90 天未命中且未更新
+//   node .agents/scripts/agg-kb-usage.mjs --months 6           # 数据月下限（有遥测行的自然月数）
+//   node .agents/scripts/agg-kb-usage.mjs --stale-days 180     # 冷数据阈值（天）
+// 口径：
+//   - 「有数据月」= 遥测文件出现过的自然月；有数据月 < --months → 数据不充分，不产候选
+//     （年轻遥测不得制造假候选，与 agg-judgments --retire-candidates 同口径）
+//   - 候选 = lastHitDays > stale-days 且 lastTouchDays > stale-days（阈值天数内既未被 kb-search 命中、内容也未更新）
+//   - lastTouch 用 git log -1 --format=%cI（cwd=仓库根），无提交记录回退文件 mtime
+//   - 扫描范围：workflow 四目录活跃态文档（排除 _TEMPLATE.md，状态单源 workflow-enums.mjs）+ wiki 递归
+//     （排除 drafts-archive/、INDEX.md、知识沉淀总览.html、*.visual-check.*、>180KB bulk 文件）
+//   - 遥测文件在 .agents/cache/（gitignore），本脚本只读不写；退出码 0 正常（含数据不充分）
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { ENUMS } from './workflow-enums.mjs';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = process.env.CHECK_LOOP_ROOT || path.resolve(SCRIPT_DIR, '..', '..');
+const CACHE_DIR = path.join(ROOT, '.agents', 'cache');
+const TELEMETRY_FILE = path.join(CACHE_DIR, 'kb-usage.jsonl');
+
+const ACTIVE_STATUS = new Set([...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']]);
+const DAY_MS = 86400000;
+const WORKFLOW_TYPES = ['plans', 'specs', 'intents', 'incidents'];
+const WIKI_EXTS = /\.(md|sql|html|txt)$/i;
+const WIKI_MAX_KB = 180;
+
+// ---------- 参数 ----------
+const args = process.argv.slice(2);
+let minMonths = 3;
+let staleDays = 90;
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--months') minMonths = Number.parseInt(args[++i] ?? '', 10);
+  else if (a === '--stale-days') staleDays = Number.parseInt(args[++i] ?? '', 10);
+  else if (a === '--help') {
+    console.log(`用法: node .agents/scripts/agg-kb-usage.mjs [--months N] [--stale-days N]
+  --months N        有数据月下限（默认 3）——遥测月数不足不产候选
+  --stale-days N    冷数据阈值（默认 90）：最近 N 天既未被命中、内容也未更新 → 候选`);
+    process.exit(0);
+  } else {
+    console.error(`未知选项: ${a}`);
+    process.exit(2);
+  }
+}
+if (!Number.isInteger(minMonths) || minMonths < 1) {
+  console.error('--months 须为正整数');
+  process.exit(2);
+}
+if (!Number.isInteger(staleDays) || staleDays < 1) {
+  console.error('--stale-days 须为正整数');
+  process.exit(2);
+}
+
+const now = Date.now();
+
+// ---------- 读遥测 ----------
+const rows = [];
+if (fs.existsSync(TELEMETRY_FILE)) {
+  const raw = fs.readFileSync(TELEMETRY_FILE, 'utf8');
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const r = JSON.parse(line);
+      if (r && typeof r.ts === 'string' && Array.isArray(r.docs)) rows.push(r);
+    } catch { /* 坏行跳过 */ }
+  }
+}
+
+const dataMonths = new Set(rows.map((r) => r.ts.slice(0, 7)));
+if (dataMonths.size < minMonths) {
+  console.log(`agg-kb-usage: 遥测数据月仅 ${dataMonths.size} 个（下限 ${minMonths}）——数据不充分，不产冷数据候选。继续积累运行记录。`);
+  process.exit(0);
+}
+
+// ---------- 每文档命中聚合 ----------
+// doc -> { lastHit: ms, months: Set<YYYY-MM> }
+const hitByDoc = new Map();
+for (const r of rows) {
+  const ym = r.ts.slice(0, 7);
+  const hitMs = new Date(r.ts).getTime();
+  if (Number.isNaN(hitMs)) continue;
+  for (const d of r.docs) {
+    if (typeof d !== 'string' || !d) continue;
+    const norm = d.replace(/\\/g, '/');
+    if (!hitByDoc.has(norm)) hitByDoc.set(norm, { lastHit: hitMs, months: new Set() });
+    const cell = hitByDoc.get(norm);
+    if (hitMs > cell.lastHit) cell.lastHit = hitMs;
+    cell.months.add(ym);
+  }
+}
+
+// ---------- 工具 ----------
+function lastTouch(relPath) {
+  const r = spawnSync('git', ['log', '-1', '--format=%cI', '--', relPath], { encoding: 'utf8', cwd: ROOT, windowsHide: true });
+  const iso = r.status === 0 ? (r.stdout || '').trim() : '';
+  if (iso) {
+    const ms = Date.parse(iso);
+    if (!Number.isNaN(ms)) return ms;
+  }
+  // 回退：文件 mtime（未提交文件 git log 无输出）
+  try {
+    return fs.statSync(path.join(ROOT, relPath)).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function parseStatus(relPath) {
+  try {
+    const head = fs.readFileSync(path.join(ROOT, relPath), 'utf8').slice(0, 2000);
+    const m = head.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!m) return '';
+    const sm = m[1].match(/^status:\s*(.+)$/m);
+    return sm ? sm[1].trim() : '';
+  } catch {
+    return '';
+  }
+}
+
+// ---------- 扫描候选 ----------
+const candidates = [];
+let scanned = 0;
+
+const consider = (relPath) => {
+  scanned += 1;
+  const hit = hitByDoc.get(relPath);
+  const lastHitMs = hit ? hit.lastHit : null;
+  const lastHitDays = lastHitMs == null ? Infinity : (now - lastHitMs) / DAY_MS;
+  const touchMs = lastTouch(relPath);
+  const lastTouchDays = touchMs == null ? Infinity : (now - touchMs) / DAY_MS;
+  if (lastHitDays > staleDays && lastTouchDays > staleDays) {
+    candidates.push({
+      doc: relPath,
+      lastHit: lastHitMs == null ? '—' : new Date(lastHitMs).toISOString().slice(0, 10),
+      lastTouch: touchMs == null ? '—' : new Date(touchMs).toISOString().slice(0, 10),
+      hitMonths: hit ? hit.months.size : 0,
+    });
+  }
+};
+
+// workflow 四目录：直下 .md，排除 _TEMPLATE.md，frontmatter 状态须在活跃枚举内
+for (const type of WORKFLOW_TYPES) {
+  const dir = path.join(ROOT, 'workflow', type);
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir);
+  } catch { continue; }
+  for (const f of entries.sort()) {
+    if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
+    const rel = `workflow/${type}/${f}`;
+    if (!ACTIVE_STATUS.has(parseStatus(rel))) continue;
+    consider(rel);
+  }
+}
+
+// wiki 递归：排除 drafts-archive/、INDEX.md、知识沉淀总览.html、*.visual-check.*、>180KB
+const walkWiki = (dir) => {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch { return; }
+  for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (e.name === 'drafts-archive') continue;
+    const abs = path.join(dir, e.name);
+    const rel = path.relative(ROOT, abs).replace(/\\/g, '/');
+    if (e.isDirectory()) { walkWiki(abs); continue; }
+    if (!WIKI_EXTS.test(e.name)) continue;
+    if (e.name === 'INDEX.md' || e.name === '知识沉淀总览.html') continue;
+    if (/\.visual-check\./.test(e.name)) continue;
+    try {
+      if (fs.statSync(abs).size / 1024 > WIKI_MAX_KB) continue;
+    } catch { continue; }
+    consider(rel);
+  }
+};
+walkWiki(path.join(ROOT, 'wiki'));
+
+// ---------- 输出 ----------
+candidates.sort((a, b) => a.doc.localeCompare(b.doc));
+console.log(`冷数据候选（${staleDays} 天未命中且未更新）——仅机械筛查，裁决走主智能体/用户（归档/更新/删除须用户指令）：`);
+if (candidates.length === 0) {
+  console.log('  无');
+} else {
+  for (const c of candidates) {
+    console.log(`  ${c.doc}  末次命中 ${c.lastHit}  末次更新 ${c.lastTouch}  命中月数 ${c.hitMonths}`);
+  }
+}
+console.log(`（扫描 ${scanned} 份 workflow/wiki 文档，候选 ${candidates.length} 份）`);

package/templates/engine/.agents/scripts/append-compensation.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// append-compensation.mjs — 关单后裁定回填补偿行生成器（maintain.md §4.4，2026-10-24）
+// 背景：2026-10-24 采购合同合入评审整改批踩坑——补偿行指纹按「直接哈希当前内容」手搓，被 check-loop 15
+//   「确认内容漂移」HARD-BLOCK（正确口径 = bindingSha256：状态行回填 prev 后再哈希）。本工具把口径收口为单源。
+// 判据单源（三处全部复用既有权威实现，禁手搓）：
+//   - 指纹 = check-loop-kit.mjs 的 bindingSha256（与 s15 校验端同一函数）
+//   - prev = 该 doc 末次同 stage 台账行的 prev（§4.4「prev 沿用原行」）
+//   - 写入 = confirm-doc.mjs 的 appendLedger（分片/主台账口径与确认门同一出口）
+// 拒绝面（fail-loud；防把 s15 的绑定降级路径改造成失配 hard）：
+//   - 文档非终态（approved/open 等）→ 前向跳转走 confirm-doc，无补偿面
+//   - 台账无该 doc+stage 行 / 末次行缺 prev（schema 演进前存量）→ 无补偿基底，追加反而制造失配
+//   - 内容未变（与末次确认行指纹一致）→ 无可补偿的漂移
+//   - 缺 --quote → 用户裁定原话是补偿行的法律依据，禁空
+// 用法：node .agents/scripts/append-compensation.mjs <doc...> --quote "<用户原话>"
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import { bindingSha256 } from './check-loop-kit.mjs';
+import { loadAllConfirmations } from './ledger-loader.mjs';
+import { appendLedger } from './confirm-doc.mjs';
+
+export const TERMINAL_STAGES = ['done', 'closed', 'superseded', 'cancelled'];
+
+// pickLastRow(rows, rel, stage)：该 doc 指定 stage 的末次台账行（append-only 末次生效，与 s15 同口径）
+export function pickLastRow(rows, rel, stage) {
+  const hits = rows.filter((e) => e && e.doc === rel && e.stage === stage && typeof e.fingerprint === 'string');
+  return hits.length ? hits[hits.length - 1] : null;
+}
+
+// buildCompensation(lines, stage, lastRow, quote, ts)：纯函数——产出补偿行或拒绝原因
+export function buildCompensation(lines, stage, lastRow, quote, ts) {
+  if (!TERMINAL_STAGES.includes(stage)) {
+    return { ok: false, reason: `非终态（${stage}）——前向跳转走 confirm-doc，无补偿面` };
+  }
+  if (!lastRow) {
+    return { ok: false, reason: `台账无 stage=${stage} 行——未经确认门落态，无补偿基底` };
+  }
+  if (!lastRow.prev) {
+    return { ok: false, reason: `末次 stage=${stage} 行缺 prev（schema 演进前存量）——s15 本就绑定降级，追加补偿行反而制造失配` };
+  }
+  const fp = bindingSha256(lines, lastRow.prev);
+  if (fp === lastRow.fingerprint) {
+    return { ok: false, reason: '内容与末次确认行一致——无可补偿的漂移（先改正文再跑本工具）' };
+  }
+  return {
+    ok: true,
+    row: {
+      ts, doc: lastRow.doc, stage, fingerprint: fp, prev: lastRow.prev,
+      source: 'chat-delegated', quote, quoteGrounding: 'verbatim',
+      batch: randomBytes(3).toString('hex'), seq: 1, of: 1,
+    },
+  };
+}
+
+// fmStatusOf(lines)：frontmatter（首 --- 块）内「状态:」值；无 frontmatter/键 → ''
+function fmStatusOf(lines) {
+  if (!/^---\s*$/.test(lines[0] || '')) return '';
+  const end = lines.findIndex((l, i) => i > 0 && /^---\s*$/.test(l));
+  for (let i = 1; i > 0 && i < (end === -1 ? lines.length : end); i++) {
+    const m = lines[i].match(/^状态:\s*(\S+)/);
+    if (m) return m[1];
+  }
+  return '';
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const docs = [];
+  let quote = '';
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--quote') quote = args[++i] ?? '';
+    else docs.push(args[i]);
+  }
+  if (!docs.length || !quote) {
+    console.error('用法：node .agents/scripts/append-compensation.mjs <doc...> --quote "<用户原话>"');
+    console.error('  done/closed 等终态文档改正文后，按 §4.4 同批补重确认补偿行（指纹=bindingSha256 单源口径）');
+    process.exit(2);
+  }
+  const root = process.cwd();
+  const ledger = loadAllConfirmations(root);
+  let fail = 0;
+  for (const p of docs) {
+    const rel = path.relative(root, path.resolve(p)).split(path.sep).join('/');
+    let lines;
+    try {
+      lines = fs.readFileSync(path.resolve(p), 'utf8').split(/\r?\n/);
+    } catch {
+      console.error(`✗ ${rel}：文件不可读`);
+      fail++;
+      continue;
+    }
+    const stage = fmStatusOf(lines);
+    const lastRow = pickLastRow(ledger, rel, stage);
+    const r = buildCompensation(lines, stage, lastRow, quote, new Date().toISOString());
+    if (!r.ok) {
+      console.error(`✗ ${rel}：${r.reason}`);
+      fail++;
+      continue;
+    }
+    appendLedger(root, r.row);
+    console.log(`✓ ${rel} ${stage} 补偿行（prev=${r.row.prev}，指纹 ${r.row.fingerprint.slice(0, 16)}，quote=「${quote}」）`);
+  }
+  if (fail) console.error(`完成：${docs.length - fail} 成功 / ${fail} 拒绝`);
+  process.exitCode = fail ? 1 : 0;
+}
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) main();