agentic-flow-kit 1.7.15 → 1.8.0

package/templates/_agents/scripts/archive-sweep.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// archive-sweep — workflow 终态件滚动归档（2026-10-09；2026-10-13 修锚；B9 自 Shipyard.Material
+//   回灌——判定面逐字对齐，出处沿革留痕在包源仓 git 历史与 CHANGELOG，装户径不引实例路径）
+// **归档单位 = 同名家族**（intent/spec/plan/incident 同名文件同进同退）：check-loop 检查 1 的结构配对
+//   是「家族双向在场」审计——intent 缺 spec/plan、spec/plan 缺 intent、incident 缺 plan/spec 均为
+//   hard-block（源仓首批按单篇准入产生数十处配对断裂的返工实证，留痕在包源仓 git 历史与 CHANGELOG）。
+//   家族任一成员不满足条件（非终态/未满窗/被活跃引用/无日期），整族留守。
+// 终态时间三级锚（2026-10-13 修锚）：confirmations 终态行 ts（精确）→ **内容 last-touch**（回退）→ 文件名日期
+// 回退级原用 git last-touch，会被批量提交系统性污染：实例仓曾发生大规模 frontmatter 迁移与两步式
+// 留痕补录（数百文件量级），把存量老文档的 last-touch 集体刷成当日 → 21 天窗口恒不满足、活跃目录
+// 只进不出。修法：回退级改「最后一次**正文**变更」——frontmatter-only 提交（状态/确认指纹/备注行增删改）
+// 不计入，因其不改变文档的实质内容与归档安全性（归档只依赖终态 + 无活跃引用，二者均由当前 frontmatter
+// 与引用扫描独立判定）。污染事件与修锚实测数据留痕在包源仓 git 历史与 CHANGELOG。
+// 判定：逐提交比对 blob，剥 frontmatter 区后正文逐字节相同 → 视为 frontmatter-only，跳过。
+// 归档形态：git mv → workflow/archive/<家族最晚终态月>/{类型}/，整族同批 = 整体退出活跃面——
+//   check-loop 配对门 / gen-workflow-index / kb-search 活跃语料均只扫四目录直下，归档不产生配对断裂
+//   （check-ledger-invariant 已归档感知：台账行原路径未命中再探 workflow/archive/*/）。
+//   差异收敛（B10a 随动）：kb-search 已同源仓扩 archive/<批次>/<type> 检索覆盖——归档件退出活跃目录
+//   但不退出 kb 检索面，防复发不丢历史。
+// 用法：
+// node .agents/scripts/archive-sweep.mjs # dry-run（缺省），--window 21
+// node .agents/scripts/archive-sweep.mjs --window 21 --execute # git mv 执行
+// 验证：node .agents/scripts/archive-sweep.test.mjs
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { readLedgerRows } from './ledger-loader.mjs';
+
+const DIRS = ['intents', 'specs', 'plans', 'incidents'];
+export const TERMINAL = new Set(['done', 'superseded', 'cancelled', 'closed']);
+export const ACTIVE = new Set(['draft', 'approved', 'open', 'fixed']);
+
+export function parseStatus(text) {
+  const lines = text.split(/\r?\n/);
+  const end = lines.indexOf('---', 1);
+  for (let i = 1; i < (end === -1 ? Math.min(lines.length, 15) : end); i++) {
+    const s = /^状态:\s*(\S+)/.exec(lines[i]);
+    if (s) return s[1];
+  }
+  return '';
+}
+
+// bodyOf(text)：剥 frontmatter 区（首 --- 至闭合 ---）后的正文，CRLF 归一。
+// 用途：判定一次提交是否只动了 frontmatter（状态/确认指纹/备注）——此类提交不改变文档实质内容，
+// 不应刷新「内容 last-touch」（2026-10-13 修锚，见文件头注释）。无 frontmatter → 全文即正文。
+export function bodyOf(text) {
+  const norm = String(text).replace(/\r\n/g, '\n');
+  const lines = norm.split('\n');
+  if (!/^---\s*$/.test(lines[0] || '')) return norm;
+  for (let i = 1; i < lines.length; i++) {
+    if (/^---\s*$/.test(lines[i])) return lines.slice(i + 1).join('\n');
+  }
+  return norm; // 未闭合 → 保守视全文为正文（宁可刷新，不误判为 frontmatter-only）
+}
+
+// 纯函数：候选分析（fixture 测试直接驱动；docs 项 = { rel, file, dir, text }）
+// 归档单位 = 同名家族：家族候选 ⇔ 全成员终态 + 全成员有终态时间且超窗 + 无成员被活跃引用
+export function analyze({ docs, ledgerTs = {}, lastTouch = {}, activeTexts = [], windowDays = 21, today = Date.now() }) {
+  const referenced = new Set();
+  const fams = new Map();
+  for (const d of docs) {
+    if (d.file.startsWith('_TEMPLATE')) continue;
+    if (!fams.has(d.file)) fams.set(d.file, []);
+    fams.get(d.file).push(d);
+  }
+  for (const text of activeTexts) for (const file of fams.keys()) if (text.includes(file)) referenced.add(file);
+
+  const active = [];
+  const terminal = [];
+  const candidates = [];
+  const tooRecent = [];
+  const noDate = [];
+  for (const [, members] of fams) {
+    const enriched = members.map((d) => {
+      const st = parseStatus(d.text);
+      const tTime = ledgerTs[d.rel] || lastTouch[d.rel] || /^(\d{4}-\d{2}-\d{2})/.exec(d.file)?.[1] || '';
+      const src = ledgerTs[d.rel] ? 'ledger' : lastTouch[d.rel] ? 'git' : 'name';
+      return { ...d, st, tTime, src };
+    });
+    const allTerminal = enriched.every((x) => TERMINAL.has(x.st));
+    const refd = enriched.some((x) => referenced.has(x.file));
+    const undated = enriched.filter((x) => !x.tTime);
+    const recent = enriched.filter((x) => x.tTime && Math.floor((today - new Date(x.tTime).getTime()) / 864e5) <= windowDays);
+    const archivable = allTerminal && !refd && !undated.length && !recent.length;
+    for (const x of enriched) {
+      if (TERMINAL.has(x.st)) terminal.push(x);
+      if (ACTIVE.has(x.st)) active.push(x);
+    }
+    if (!archivable) {
+      if (undated.length) noDate.push(...undated);
+      if (recent.length) tooRecent.push(...recent);
+      continue;
+    }
+    const month = enriched.map((x) => x.tTime).sort().pop().slice(0, 7); // 家族最晚终态月，整族同批
+    for (const x of enriched) candidates.push({ ...x, month });
+  }
+  return { active, terminal, candidates, referenced, tooRecent, noDate };
+}
+
+export function buildDocList(root, dirs = DIRS) {
+  const docs = [];
+  for (const d of dirs) {
+    const dir = path.join(root, 'workflow', d);
+    if (!fs.existsSync(dir)) continue; // 目录缺失（fixture / 部分类型未建）→ 跳过，不抛
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.md')) continue;
+      const rel = `workflow/${d}/${f}`;
+      docs.push({ rel, file: f, dir: d, text: fs.readFileSync(path.join(dir, f), 'utf8') });
+    }
+  }
+  return docs;
+}
+
+function loadLedgerTs(root) {
+  const out = {};
+  // 台账统一视图（主台账+分片透明合并，坏行跳过）。源仓走 ledger-loader.loadAllConfirmations
+  // （同 doc|stage|fingerprint 键去重取末次）；kit 读侧单源 = readLedgerRows（不去重）。对本判据
+  // 无语义差：loadLedgerTs 取「每 doc 终态行最大日期」，同键末次行的日期 ≥ 该键其余行，两侧 max
+  // 恒等——不为锚查询给 loader 加第二个出口（读侧出口越少越不易漂移）。
+  for (const e of readLedgerRows(root)) {
+    if (TERMINAL.has(e.stage) && e.doc) {
+      const d = (e.ts || '').slice(0, 10);
+      if (d && (!out[e.doc] || d > out[e.doc])) out[e.doc] = d;
+    }
+  }
+  return out;
+}
+
+// loadLastTouch(root)：每篇 workflow 文档的「最后一次正文变更」日期（YYYY-MM-DD）。
+// 逐提交（新→旧）取该文件的 blob 与上一版比对：正文（bodyOf）逐字节相同 → frontmatter-only 提交，
+// 跳过不记；正文有变 → 记该提交日期并停止追踪该文件（新→旧遍历，首遇即最近一次正文变更）。
+// 批量迁移/补录提交（只改状态与确认指纹）因此不再刷新锚——2026-10-13 修锚的核心。
+// 实现：单次 `git log --raw` 拿「提交 × 文件 × 前后 blob sha」，再按需 `git cat-file --batch` 取内容
+// （同 blob 内容天然去重，批量提交里数十文件多为同一份 frontmatter 改写，实际读取量远小于文件数）。
+export function loadLastTouch(root) {
+  const out = {};
+  const raw = execFileSync('git', ['log', '--raw', '--no-renames', '--format=%x01%cI', '--', 'workflow'], {
+    cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024,
+  });
+  // 收集待比对项：按 path 分组，保留**全部**历史条目（新→旧），逐条比对直到找到正文变更
+  const byPath = new Map();
+  for (const entry of raw.split('\u0001')) {
+    const lines = entry.split('\n');
+    const date = (lines[0] || '').slice(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) continue;
+    for (const line of lines.slice(1)) {
+      // `:<oldmode> <newmode> <oldsha> <newsha> <status>\t<path>`
+      const m = /^:\d+ \d+ ([0-9a-f]+) ([0-9a-f]+) [A-Z]\d*\t(.+)$/.exec(line);
+      if (!m) continue;
+      const [, oldSha, newSha, p] = m;
+      if (!byPath.has(p)) byPath.set(p, []);
+      byPath.get(p).push({ date, oldSha, newSha });
+    }
+  }
+  // 批量取 blob 内容（--batch 一次喂全部 sha，输出 `<full-sha> blob <size>\n<content>\n`）
+  // 注意：--batch 回显**完整** sha，而输入是 core.abbrev 缩写——按输入顺序回填，键用请求时的缩写，
+  // 否则 blobs.get(缩写) 恒 miss → 全部走保守回退（2026-10-13 实测踩中）。
+  const shas = [...new Set([...byPath.values()].flat().flatMap((x) => [x.oldSha, x.newSha]).filter((s) => s && !/^0+$/.test(s)))];
+  const blobs = new Map();
+  if (shas.length) {
+    const outBuf = execFileSync('git', ['cat-file', '--batch'], {
+      cwd: root, input: shas.join('\n') + '\n', maxBuffer: 512 * 1024 * 1024,
+    });
+    // 按 header 行切分（内容可能含任意字节，故按 size 精确切片）；第 i 个响应 ↔ shas[i]
+    let pos = 0;
+    let idx = 0;
+    while (pos < outBuf.length && idx < shas.length) {
+      const nl = outBuf.indexOf(0x0a, pos);
+      if (nl === -1) break;
+      const header = outBuf.toString('utf8', pos, nl);
+      const hm = /^([0-9a-f]+) blob (\d+)$/.exec(header);
+      if (!hm) { pos = nl + 1; continue; }
+      const size = Number(hm[2]);
+      const start = nl + 1;
+      blobs.set(shas[idx], outBuf.toString('utf8', start, start + size));
+      pos = start + size + 1; // 跳过内容后的换行
+      idx++;
+    }
+  }
+  // 逐 path 新→旧扫描：首个「正文有变」的提交日期即内容 last-touch；全为 frontmatter-only → 不记
+  // （调用方回退到文件名日期）。新增文件（oldSha 全 0）→ 该次提交即首次入库，记为正文变更。
+  for (const [p, entries] of byPath) {
+    for (const { date, oldSha, newSha } of entries) {
+      // 全 0 sha（新增文件，git 按 core.abbrev 输出 7 位 `0000000`）→ 首次入库即正文变更
+      if (/^0+$/.test(oldSha)) { out[p] = date; break; }
+      const before = blobs.get(oldSha);
+      const after = blobs.get(newSha);
+      // 取不到内容（异常态）→ 保守记为正文变更（宁可刷新，不误跳过）
+      if (before === undefined || after === undefined) { out[p] = date; break; }
+      if (bodyOf(before) !== bodyOf(after)) { out[p] = date; break; }
+    }
+  }
+  return out;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const execute = argv.includes('--execute');
+  const wArg = argv.find((a) => a.startsWith('--window='));
+  const windowDays = wArg ? Number(wArg.split('=')[1]) : 21;
+  if (!Number.isFinite(windowDays) || windowDays < 0) {
+    console.error('archive-sweep: --window 须为非负数字');
+    process.exit(2);
+  }
+  const root = process.cwd();
+  const docs = buildDocList(root);
+  const r = analyze({
+    docs,
+    ledgerTs: loadLedgerTs(root),
+    lastTouch: loadLastTouch(root),
+    activeTexts: docs.filter((d) => ACTIVE.has(parseStatus(d.text))).map((d) => d.text),
+    windowDays,
+  });
+  const byDir = {};
+  for (const d of DIRS) byDir[d] = r.candidates.filter((x) => x.dir === d).length;
+  const fams = new Set(r.candidates.map((x) => x.file));
+  console.log(`窗口 ${windowDays} 天｜候选 ${r.candidates.length} 篇 / ${fams.size} 族（${JSON.stringify(byDir)}）｜活跃 ${r.active.length}｜未满窗 ${r.tooRecent.length}｜被活跃引用排除 ${r.referenced.size}｜无日期 ${r.noDate.length}`);
+  if (!execute) {
+    for (const x of r.candidates) console.log(`  [dry] ${x.rel} → workflow/archive/${x.month}/${x.dir}/${x.file}`);
+    console.log('dry-run 结束（加 --execute 执行 git mv）');
+    return;
+  }
+  let moved = 0;
+  for (const x of r.candidates) {
+    const destDir = path.join(root, 'workflow', 'archive', x.month, x.dir);
+    fs.mkdirSync(destDir, { recursive: true });
+    execFileSync('git', ['mv', x.rel, path.join('workflow', 'archive', x.month, x.dir, x.file)], { cwd: root });
+    moved++;
+  }
+  console.log(`execute 完成：git mv ${moved} 篇 → workflow/archive/<家族最晚终态月>/`);
+}
+
+if (process.argv[1] && process.argv[1].endsWith('archive-sweep.mjs')) main();

package/templates/_agents/scripts/archive-sweep.test.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// archive-sweep.test.mjs — analyze 纯函数 fixture（2026-10-09；2026-10-13 加 bodyOf 与内容锚回归；B9 自 Shipyard.Material 回灌）
+import { analyze, parseStatus, bodyOf, loadLastTouch } from './archive-sweep.mjs';
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? '\n      ' + detail : ''}`); }
+};
+const doc = (dir, file, st) => ({ rel: `workflow/${dir}/${file}`, file, dir, text: `---\n状态: ${st}\n---\n# t\n` });
+const daysAgo = (n) => new Date(Date.now() - n * 864e5).toISOString().slice(0, 10);
+
+// 场景 1：状态解析（CRLF 容忍）
+check('parseStatus 基础+CRLF', parseStatus('---\r\n状态: done\r\n---\nx') === 'done' && parseStatus('---\n状态: open\n') === 'open');
+
+// 场景 1b：bodyOf——剥 frontmatter（2026-10-13 修锚的判定基元）
+{
+  const a = '---\n状态: approved\n级别: L1\n---\n\n# T\n\n正文 A\n';
+  const b = '---\n状态: done\n确认指纹: abc\n级别: L1\n---\n\n# T\n\n正文 A\n';
+  check('bodyOf：frontmatter-only 变更 → 正文相等', bodyOf(a) === bodyOf(b));
+  const c = '---\n状态: done\n级别: L1\n---\n\n# T\n\n正文 B\n';
+  check('bodyOf：正文变更 → 正文不等', bodyOf(b) !== bodyOf(c));
+  check('bodyOf：无 frontmatter → 全文即正文', bodyOf('# T\n\n正文\n') === '# T\n\n正文\n');
+  check('bodyOf：未闭合 frontmatter → 保守返回全文', bodyOf('---\n状态: done\n正文\n') === '---\n状态: done\n正文\n');
+  check('bodyOf：CRLF 归一', bodyOf('---\r\n状态: done\r\n---\r\n正文\r\n') === bodyOf('---\n状态: done\n---\n正文\n'));
+}
+
+// 场景 2：终态/活跃分类 + 模板排除
+{
+  const docs = [doc('intents', 'a.md', 'done'), doc('plans', 'b.md', 'draft'), doc('intents', '_TEMPLATE.md', 'draft'), doc('incidents', 'c.md', 'closed')];
+  const r = analyze({ docs, windowDays: 21 });
+  check('分类：终态 2 / 活跃 1 / 模板排除', r.terminal.length === 2 && r.active.length === 1 && !JSON.stringify(r).includes('_TEMPLATE'));
+}
+
+// 场景 3：窗口过滤（台账 ts 优先于 git 回退）
+{
+  const docs = [doc('specs', 'old.md', 'done'), doc('specs', 'new.md', 'done')];
+  const r = analyze({
+    docs, windowDays: 21,
+    ledgerTs: { 'workflow/specs/old.md': daysAgo(30) },
+    lastTouch: { 'workflow/specs/old.md': daysAgo(2), 'workflow/specs/new.md': daysAgo(2) },
+  });
+  check('窗口：台账 30 天入候选、git 2 天未满窗', r.candidates.length === 1 && r.candidates[0].file === 'old.md' && r.candidates[0].src === 'ledger' && r.tooRecent.length === 1);
+}
+
+// 场景 4：活跃引用排除（git 回退源）+ 无时间源兜底文件名日期
+{
+  const docs = [doc('intents', '2026-09-01-refd.md', 'done'), doc('intents', '2026-09-01-fallback.md', 'done')];
+  const r = analyze({
+    docs, windowDays: 21,
+    activeTexts: ['参见 ../intents/2026-09-01-refd.md 的结论'],
+    lastTouch: { 'workflow/intents/2026-09-01-fallback.md': daysAgo(30) },
+  });
+  check('引用排除 + git 回退源入候选', r.candidates.length === 1 && r.candidates[0].file === '2026-09-01-fallback.md' && r.candidates[0].src === 'git' && r.referenced.has('2026-09-01-refd.md'));
+}
+
+// 场景 4b：台账/git 均无时间源 → 文件名日期兜底
+{
+  const r = analyze({ docs: [doc('specs', '2026-09-01-nodate.md', 'done')], windowDays: 21 });
+  check('文件名日期兜底', r.candidates.length === 1 && r.candidates[0].src === 'name' && r.candidates[0].month === '2026-09');
+}
+
+// 场景 5：归档月份取终态时间当月
+{
+  const r = analyze({ docs: [doc('plans', '2026-09-03-x.md', 'done')], windowDays: 21, ledgerTs: { 'workflow/plans/2026-09-03-x.md': '2026-09-05' } });
+  check('归档月 = 终态时间当月', r.candidates[0] !== undefined && r.candidates[0].month === '2026-09');
+}
+
+// 场景 6：家族原子——intent 未终态锚住同名家族整族留守；全终态家族整族入候选
+{
+  const docs = [
+    doc('intents', '2026-09-05-live.md', 'approved'),
+    doc('plans', '2026-09-05-live.md', 'done'),
+    doc('intents', '2026-09-04-family.md', 'done'),
+    doc('specs', '2026-09-04-family.md', 'done'),
+    doc('plans', '2026-09-04-family.md', 'done'),
+  ];
+  const r = analyze({
+    docs, windowDays: 21,
+    ledgerTs: { 'workflow/plans/2026-09-05-live.md': daysAgo(30), 'workflow/intents/2026-09-04-family.md': daysAgo(30), 'workflow/specs/2026-09-04-family.md': daysAgo(30), 'workflow/plans/2026-09-04-family.md': daysAgo(30) },
+  });
+  check('家族原子：非终态 intent 整族留守', r.candidates.length === 3 && !r.candidates.some((x) => x.file === '2026-09-05-live.md'));
+  check('家族原子：全终态家族三成员同批', r.candidates.filter((x) => x.file === '2026-09-04-family.md').length === 3);
+}
+
+// 场景 7：loadLastTouch 集成——真实 git 仓库，钉住「frontmatter-only 提交不刷新内容锚」
+// （2026-10-13 修锚回归：原实现用 git last-touch，被批量迁移/补录提交污染 → 21 天窗口恒不满足。
+//  本场景同时覆盖 cat-file --batch 回显完整 sha 而输入为缩写这一踩坑点——键错则全部走保守回退。）
+{
+  const { execFileSync } = await import('node:child_process');
+  const os = await import('node:os');
+  const path = await import('node:path');
+  const fs = await import('node:fs');
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archive-sweep-git-'));
+  const git = (...a) => execFileSync('git', a, { cwd: root, encoding: 'utf8' });
+  git('init', '-q');
+  git('config', 'user.email', 't@t');
+  git('config', 'user.name', 't');
+  const dir = path.join(root, 'workflow', 'plans');
+  fs.mkdirSync(dir, { recursive: true });
+  const p = path.join(dir, '2026-09-01-x.md');
+  const commit = (msg, date) => {
+    git('add', '-A');
+    execFileSync('git', ['commit', '-q', '-m', msg], { cwd: root, env: { ...process.env, GIT_AUTHOR_DATE: date, GIT_COMMITTER_DATE: date } });
+  };
+  // ① 首次入库（正文 v1）
+  fs.writeFileSync(p, '---\n状态: draft\n级别: L1\n---\n\n# T\n\n正文 v1\n', 'utf8');
+  commit('c1', '2026-09-01T10:00:00+08:00');
+  // ② frontmatter-only（状态 draft→approved）
+  fs.writeFileSync(p, '---\n状态: approved\n级别: L1\n---\n\n# T\n\n正文 v1\n', 'utf8');
+  commit('c2', '2026-09-20T10:00:00+08:00');
+  // ③ frontmatter-only（approved→done + 确认指纹）
+  fs.writeFileSync(p, '---\n状态: done\n级别: L1\n确认指纹: abc\n---\n\n# T\n\n正文 v1\n', 'utf8');
+  commit('c3', '2026-09-28T10:00:00+08:00');
+  const rel = 'workflow/plans/2026-09-01-x.md';
+  const t1 = loadLastTouch(root);
+  check('loadLastTouch：frontmatter-only 提交不刷新锚（锚停在正文变更日 2026-09-01）',
+    t1[rel] === '2026-09-01', `got ${t1[rel]}`);
+  // ④ 正文变更 → 锚前移到该日
+  fs.writeFileSync(p, '---\n状态: done\n级别: L1\n确认指纹: abc\n---\n\n# T\n\n正文 v2\n', 'utf8');
+  commit('c4', '2026-10-05T10:00:00+08:00');
+  const t2 = loadLastTouch(root);
+  check('loadLastTouch：正文变更刷新锚（2026-10-05）', t2[rel] === '2026-10-05', `got ${t2[rel]}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/check-attribution.mjs

@@ -0,0 +1,37 @@
+// check-attribution.mjs — 检查 24：incident 归因字段核查 [warning]（2026-10-13 B6b-2 自 Shipyard.Material
+//   check-loop-sections/s24-incident-attribution.mjs 回灌；段体判据逐字对齐，出处沿革留痕在包源仓 git
+//   历史与 CHANGELOG——装户径不引实例路径）
+// 背景（incident-attribution）：incident 无「来源」标准字段，「来源×环境」分布只能逐件人工判读，
+// 两轮口径相抵不可机器复算。本段把归因变成机器校验收敛面：模板新增「来源:」/「影响环境:」两枚枚举键
+// （单源 .agents/workflow-enums.txt incident.source.all / incident.env.all），
+// 锚起的件「发现」日 ≥ attributionSince（policy v9；v1–v8 缺键 → 整段跳过）时必填且值须在枚举内 → 否则 WARN。
+// 只查字段存在性与枚举合法性，不判读内容（判读留给 gen-workflow-metrics 的机器复算表）。
+// 存量豁免：发现日 < 锚 → 整体跳过；`流程: legacy` 回填件 → 跳过（同检查 3 口径）。
+// kit 适配（源仓→kit 逐条）：告警文案里的枚举单源路径平铺 .agents/config/workflow-enums.txt → .agents/workflow-enums.txt。
+import path from 'node:path';
+
+export function run(ctx) {
+  const { ENUMS, inSet, docFiles, fmGet, kitPolicy, warnings } = ctx;
+  // --- 24. incident 归因字段核查 [warning]（锚 attributionSince）---
+  {
+    const anchor = kitPolicy.attributionSince;
+    if (anchor) {
+      const KEY_SOURCE = '来源';
+      const KEY_ENV = '影响环境';
+      for (const inc of docFiles('incidents')) {
+        const name = path.basename(inc);
+        if (fmGet(inc, '流程') === 'legacy') continue; // 回填件豁免（同检查 3）
+        // 生效日锚：发现日优先、缺则取文件名前缀（与检查 12 moduleSince 同款退化）
+        let d = fmGet(inc, '发现') || fmGet(inc, '日期');
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(d)) d = /^\d{4}-\d{2}-\d{2}/.test(name) ? name.slice(0, 10) : '';
+        if (!d || d < anchor) continue; // 锚前存量不回填
+        const src = fmGet(inc, KEY_SOURCE);
+        const env = fmGet(inc, KEY_ENV);
+        if (!src) warnings.push(`- [WARN 归因缺字段] ${name} 缺「${KEY_SOURCE}:」字段（${anchor} 起新建 incident 必填，取值见 .agents/workflow-enums.txt incident.source.all）`);
+        else if (!inSet(src, ENUMS['incident.source.all'])) warnings.push(`- [WARN 归因非法值] ${name}「${KEY_SOURCE}: ${src}」不在枚举（${ENUMS['incident.source.all'].join('/')}）`);
+        if (!env) warnings.push(`- [WARN 归因缺字段] ${name} 缺「${KEY_ENV}:」字段（${anchor} 起新建 incident 必填，取值见 .agents/workflow-enums.txt incident.env.all）`);
+        else if (!inSet(env, ENUMS['incident.env.all'])) warnings.push(`- [WARN 归因非法值] ${name}「${KEY_ENV}: ${env}」不在枚举（${ENUMS['incident.env.all'].join('/')}）`);
+      }
+    }
+  }
+}

package/templates/_agents/scripts/check-convergence.mjs

@@ -0,0 +1,119 @@
+// check-convergence.mjs — 检查 23：判据级收敛对账（2026-10-13 B6b-2 自 Shipyard.Material
+//   check-loop-sections/s23-convergence-audit.mjs 回灌；段体判据逐字对齐，出处沿革留痕在包源仓 git
+//   历史与 CHANGELOG——装户径不引实例路径）
+// 背景（convergence-audit，参照 GitHub spec-kit converge 机理「完成声明不是证据」）：
+// spec 的验证承诺此前只落在叙述节（检查 21 对节内引用做存在性扫描），没有逐判据 × 逐证据的机器对账。
+// 本段把「验收判据」表（workflow/specs/_TEMPLATE.md 承重节）变成机器输入：L2/L3 done spec（锚后）逐行解析
+//   判据 → 证据。状态列自报「覆盖」而证据无效 → 仍判未覆盖。
+// 两档（convergence-hard）：
+//   advisory（有 convergenceSince、无 hard 键，或日期 < convergenceHardSince）：证据 = 存在的路径，或命令白名单声明。WARN。
+//   hard（日期 ≥ convergenceHardSince）：路径仍只认存在，不读正文、不判与判据是否相关（判断题留给新会话复核）；
+//     命令必须是全量门实际跑的那几个，且 workflow/verify-evidence.md 有不早于本 spec 日期的全绿行。
+//     答不了（空、路径不存在、命令不在全量门、没有对应全绿行）= 未覆盖，HARD-BLOCK。人工走查且证据为空仍合法。
+// 无「验收判据」节或表无数据行 → 两档都是 WARN「收敛无判据」。
+// 存量豁免：日期 < convergenceSince → 跳过。缺键（v1–v9）→ 整段跳过。缺 hard 键（v1–v10）→ 不升 hard。
+// kit 适配（源仓→kit 逐条）：① 命令白名单收 kit 全量门口径——verify.mjs 全量门实际跑的就是
+//   `npm test` 与 `node .agents/scripts/verify.mjs` 自身（verify.mjs 编排七门、测试面走 run-tests 套件），
+//   源仓的 dotnet build / npm run build / verify-ui 等实例门随 instance-ref 门修法剔除；② hard 档解锁序
+//   文案对齐 kit：verify.mjs 全绿尾部自动重生成 verify-evidence.md（gen-verify-evidence 单源），
+//   不再单独点名 gen-verify-evidence 步骤。
+import fs from 'node:fs';
+import path from 'node:path';
+
+// advisory 档的声明白名单（文本命中即认）。hard 档不再凭命中放行。命令面 = kit 全量门口径（见头注）。
+const CMD_RE = /npm\s+(run\s+)?test|verify\.mjs/;
+// 引用切分：每一处引用单独取出，防「npm test 与路径同格」被整格误判。长短形态都认。
+const CITE_RE = /npm\s+(?:run\s+)?test|verify\.mjs/g;
+// verify.mjs 全绿行（verifications.jsonl 绿凭证）实际覆盖的命令。不在此集的白名单命令没有对应绿记录。
+const GATE_CMD = new Set(['npm test', 'npm run test', 'verify.mjs']);
+const PATH_RE = /[\w.@\-\\/]+\.(mjs|js|ts|tsx|cs|md|json|html|sql)/g;
+const SEC_RE = /^##\s+.*验收判据/;
+// 与 gen-verify-evidence.mjs 数据行同形态（kit 六列：短 SHA | ISO 时间 | 门数 | 套件计数 | 绑定单 | runId）。
+// 只取日期，不复述门数。
+const EVIDENCE_ROW_RE = /^\|\s*`[0-9a-f]{7,40}`\s*\|\s*([^|]+?)\s*\|/;
+
+export function run(ctx) {
+  const { ROOT, WF, docFiles, fmGet, linesOf, addedDateOf, kitPolicy, warnings, blockers } = ctx;
+  // --- 23. 判据级收敛对账（锚 convergenceSince / convergenceHardSince）---
+  function greenEvidenceDates() {
+    const dates = [];
+    let text = '';
+    try { text = fs.readFileSync(path.join(ROOT, WF, 'verify-evidence.md'), 'utf8'); } catch { return dates; }
+    for (const raw of text.split(/\r?\n/)) {
+      const m = raw.trim().match(EVIDENCE_ROW_RE);
+      if (!m) continue;
+      const day = m[1].trim().slice(0, 10);
+      if (/^\d{4}-\d{2}-\d{2}$/.test(day)) dates.push(day);
+    }
+    return dates;
+  }
+
+  // 命令格：每一处引用都须落在全量门里，且有不早于 spec 日期的全绿行。解析不出引用 → 不放行。
+  // 两侧日期同须 UTC 口径（台账渲染 UTC ts；spec「日期」fill-spec 默认 UTC，手写见 _TEMPLATE.md 验收判据注）：
+  // 本地时区手写日期会在 UTC+8 0–8 点窗与全绿行错位一天——fail-closed，不误放。
+  function commandCovered(ev, specDate, greenDates) {
+    const cites = ev.match(CITE_RE) || [];
+    if (!cites.length) return false;
+    const fresh = greenDates.some((g) => g >= specDate);
+    return cites.every((c) => GATE_CMD.has(c) && fresh);
+  }
+
+  {
+    const anchor = kitPolicy.convergenceSince;
+    const hardAnchor = kitPolicy.convergenceHardSince;
+    if (anchor) {
+      const greenDates = greenEvidenceDates();
+      const isPlaceholder = (s) => !s || /^<.*>$/.test(s);
+      for (const spec of docFiles('specs')) {
+        const st = fmGet(spec, '状态');
+        const lvl = fmGet(spec, '级别');
+        if (st !== 'done' || !['L2', 'L3'].includes(lvl)) continue;
+        // 生效日锚：frontmatter「日期」优先（fill-spec 必写），缺则 git 首加日 / 文件名前缀（同检查 12 退化序）
+        let d = fmGet(spec, '日期') || addedDateOf(spec);
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(d)) d = /^\d{4}-\d{2}-\d{2}/.test(path.basename(spec)) ? path.basename(spec).slice(0, 10) : '';
+        if (!d || d < anchor) continue; // 锚前存量不回填
+        const hard = !!(hardAnchor && d >= hardAnchor);
+        const lines = linesOf(spec) || [];
+        const secLines = [];
+        let inSec = false;
+        for (const l of lines) {
+          if (SEC_RE.test(l)) { inSec = true; continue; }
+          if (inSec && /^##\s+/.test(l)) { inSec = false; continue; }
+          if (inSec) secLines.push(l);
+        }
+        // 解析表数据行（表头才是数据边界——沿用 agg-delegations splitTables 口径；分隔行/表头行/占位行跳过）
+        const rows = secLines
+          .filter((l) => /^\|.*\|\s*$/.test(l))
+          .filter((l) => !/^\|[\s:|-]+\|\s*$/.test(l))
+          .map((l) => l.split('|').slice(1, -1).map((c) => c.trim().replace(/^`|`$/g, '')))
+          .filter((cells) => cells.length >= 3)
+          .filter((cells) => !cells[1].startsWith('证据（')) // 表头行
+          .filter((cells) => !isPlaceholder(cells[0])); // 模板占位行
+        const base = path.basename(spec);
+        if (!rows.length) {
+          warnings.push(`- [WARN 收敛无判据] ${base} 无「验收判据」表或表为空——L2/L3 done spec 须逐条登记可验判据（检查 23，模板 workflow/specs/_TEMPLATE.md）`);
+          continue;
+        }
+        const missed = [];
+        for (const [crit, ev, stat] of rows.map((c) => [c[0], c[1], (c[2] || '').trim()])) {
+          if (stat === '人工' && isPlaceholder(ev)) continue; // 人工走查判据：空证据合法
+          let ok = false;
+          if (!isPlaceholder(ev)) {
+            if (hard && CMD_RE.test(ev)) ok = commandCovered(ev, d, greenDates);
+            else if (CMD_RE.test(ev)) ok = true; // advisory：命令白名单认声明
+            else {
+              const cands = ev.match(PATH_RE) || [];
+              ok = cands.some((p) => fs.existsSync(path.join(ROOT, p)));
+            }
+          }
+          if (!ok) missed.push(`${crit}→${ev || '（空）'}`);
+        }
+        if (missed.length) {
+          const detail = `${base} ${rows.length} 条判据中 ${missed.length} 条证据无效（${missed.join('; ')}）`;
+          if (hard) blockers.push(`- [收敛未覆盖] ${detail}——状态列自报不作数；命令须是全量门（npm test / verify.mjs）且 workflow/verify-evidence.md 有不早于本 spec 日期的全绿行；路径只认存在（检查 23）。若本 spec 已标 done：先标后补会与本门互为前提（verify 门序含 check-loop）——解锁序：状态临时改回非 done → 跑 node .agents/scripts/verify.mjs 全量门（全绿尾部自动重生成 workflow/verify-evidence.md 全绿行）→ 再标 done`);
+          else warnings.push(`- [WARN 收敛未覆盖] ${detail}——状态列自报不作数，证据须存在或为验证命令（检查 23）`);
+        }
+      }
+    }
+  }
+}