agentic-flow-kit 1.8.7 → 2.1.0

package/templates/engine/.agents/scripts/gen-verify-evidence.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// gen-verify-evidence.mjs — 验证绿凭证摘要入库生成器（2026-10-09 AI-Native 架构审查 P2-3）
+// 背景：verifications.jsonl 是 gitignore 的本地台账（24h 窗口、跨机不可见）——历史提交「当时验证过什么」
+//   的机器事实只活在本地。本脚本把全绿行按 headShort 去重（同 SHA 取最新 ts）渲染进仓内
+//   workflow/verify-evidence.md，使绿凭证成为随库持久、跨机可对质的生成物（全量台账仍留本地）。
+// 语义：一行 = 「**验证时刻的工作树**（其基线提交 = 短 SHA，工作树可含未提交改动）过全量门禁全绿
+//   （N 门 / 断言计数）」；非证据链签名——本地台账可伪造的诚实边界不变（check-loop 检查 15 头注释口径），
+//   入库摘要只是把「曾有凭证」从易失升级为难失。
+// 归因提醒（2026-10-10 实证）：短 SHA 只是**基线提交**，不等于被测内容。关单应「先提交、后跑门」，
+//   否则绿行 SHA 指向未含本次改动的上一提交——同一 SHA 可能既有绿行（脏工作区跑）又有红记录。
+// 追加保全（2026-10-10 复核 S2，用户裁定采纳）：已入仓的行不因本地台账缺失而被抹掉——台账 per-worktree
+//   且 gitignore，整段重写会让跨机/换 worktree 的历史凭证消失。合并口径 = 仓内既有行 ∪ 本地台账绿行，
+//   同 headShort 取更新 ts（平局取本地台账，保持「重跑刷新凭证」语义）。代价（已接受）：仓内错行不会被
+//   重生成自动纠正——须人工改正；若本地台账仍持同一 SHA，重生成会按台账重写该行（须连同台账处理）。
+// 时机：verify.mjs 全绿尾部自动重生成（2026-10-11 C4 事件原子化——检查 23 收敛硬门读本文件，滞后即误拦）
+//   + 关单时随三件套同笔提交；CI 侧重生成于 CI 工作区、不回流本仓，无副作用；--check 只供本地自检。
+// 用法：node .agents/scripts/gen-verify-evidence.mjs [--root <dir>] [--check]
+// 测试面已随引擎减重退役（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 argv = process.argv.slice(2);
+const argOf = (k) => {
+  const i = argv.indexOf(k);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : '';
+};
+const ROOT = argOf('--root') || path.resolve(SCRIPT_DIR, '..', '..');
+const LEDGER = path.join(ROOT, '.agents', 'verifications.jsonl');
+const OUT = path.join(ROOT, 'workflow', 'verify-evidence.md');
+
+const ROW_RE = /^\|\s*`([0-9a-f]{7,40})`\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|\s*$/;
+
+/** 按本地台账条目渲染数据行 */
+function renderRow(e) {
+  const cnt = Number.isFinite(e.passed) ? `PASS ${e.passed} / FAIL ${e.failed ?? 0}` : '—';
+  // scope 标记（verify-diet 2026-10-21 ②）：增量关单绿行末列自带面与基线——审计可对质「跳了哪些门」；
+  // 门数列显示实跑数（如 10），与全量 16 行天然可辨。baseSource=evidence（verify-evidence-fallback
+  // 2026-10-22）显式标注「基线取自仓库凭证而非本地台账」——诚实边界不降，来源可对质。
+  const scopeNote = e.scope
+    ? `scope=${e.scope.mode}(base=${e.scope.base}${e.scope.baseSource === 'evidence' ? ',src=evidence' : ''},skip=${(e.scope.skipped || []).length})`
+    : '';
+  // flaky 重跑绿（gate-health 2026-10-22）：末列标 `flaky=<门>`——首跑红、重跑绿的事实不丢。
+  const flakyNote = Array.isArray(e.flaky) && e.flaky.length ? `flaky=${e.flaky.join('+')}` : '';
+  // 分层跑（2026-10-23）：diff 档 engine-tests 用 --fast——末列标 `fast=engine-tests`，审计可对质。
+  const fastNote = e.fastTests ? 'fast=engine-tests' : '';
+  // envSkips（2026-10-27 anchor-envskip）：CI-only 门被 loud-skip 的绿行实跑门数 < 门表，
+  // 但此前末列仍显示 `—`，外观与全量绿行无异（实测 11 条被下游当基线用了 20 次）。
+  // 显式渲染跳过事实，使「该行没跑哪些门」在摘要面可见，且 parseEvidenceGreens 也会拒作全量锚。
+  const envNote = Array.isArray(e.envSkips) && e.envSkips.length ? `skip-env=${e.envSkips.join('+')}` : '';
+  return `| \`${e.headShort}\` | ${e.ts} | ${e.gates} | ${cnt} | ${[scopeNote, flakyNote, fastNote, envNote, e.runId].filter(Boolean).join(' ') || '—'} |`;
+}
+
+/**
+ * 解析本文件既有数据行（追加保全用，2026-10-10 复核 S2）。
+ * 只认形态完整的数据行；说明行 / 表头 / 注释一律忽略。读不到文件 = 无既有行。
+ */
+function parseCommittedRows() {
+  const out = [];
+  let disk = '';
+  try { disk = fs.readFileSync(OUT, 'utf8'); } catch { return out; }
+  for (const raw of disk.split(/\r?\n/)) {
+    const m = raw.trim().match(ROW_RE);
+    if (m) out.push({ headShort: m[1], ts: m[2].trim(), line: raw.trim() });
+  }
+  return out;
+}
+
+function render() {
+  const rows = [];
+  try {
+    for (const line of fs.readFileSync(LEDGER, 'utf8').split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        const e = JSON.parse(line);
+        if (e.exitCode === 0 && e.suite === 'all-gates' && e.headShort) rows.push(e);
+      } catch { /* 坏行跳过——台账是 append-only 事实流，不因单行格式失败中断 */ }
+    }
+  } catch { /* 无台账 = 空表（新装户/新 clone 首跑前） */ }
+  // 行统一形态 { headShort, ts, line }。先放**仓内既有行**（追加保全），再叠加本地台账绿行。
+  const bySha = new Map();
+  for (const r of parseCommittedRows()) bySha.set(r.headShort, r);
+  // 同 headShort 取更新 ts（重跑刷新凭证，不堆行）；平局取本地台账
+  for (const e of rows) {
+    const prev = bySha.get(e.headShort);
+    if (!prev || String(e.ts) >= String(prev.ts)) bySha.set(e.headShort, { headShort: e.headShort, ts: String(e.ts), line: renderRow(e) });
+  }
+  const ordered = [...bySha.values()].sort((a, b) => String(a.ts).localeCompare(String(b.ts)));
+  const lines = [];
+  lines.push('# 验证绿凭证摘要（生成物，勿手改）');
+  lines.push('');
+  lines.push('> 生成器 `node .agents/scripts/gen-verify-evidence.mjs`（verify.mjs 全绿尾部自动重生成，2026-10-11 C4 起；源 .agents/verifications.jsonl 为本地台账）。');
+  lines.push('> 一行 = 验证时刻**工作树**过全量门禁全绿（短 SHA 为该时刻的**基线提交**，工作树可能含未提交改动——关单宜「先提交、后跑门」）；`计数` 为断言 PASS/FAIL（无汇总行时缺省）。末列 `scope=diff(base=…,skip=N)` 行为增量关单凭证（verify --scope：未触产品重门，实跑门数见门数列，口径见 verify-scope.mjs）；`src=evidence` 表示基线取自本文件（仓库凭证）而非本地台账；`flaky=<门>` 表示该门首跑红、隔离重跑绿（gate-health 2026-10-22）；`fast=engine-tests` 表示 diff 档 engine-tests 用了 --fast（2026-10-23 分层跑）；`skip-env=<门>` 表示本地 loud-skip 了 CI-only 门（2026-10-27 anchor-envskip）——带此前缀的行**不作全量锚**，与 scope/fast 同属裁剪凭证。非签名链——诚实边界同 check-loop 检查 15。');
+  lines.push('> 行来源 = 本地台账绿行 ∪ 本文件既有行（**追加保全**：跨机 / 换 worktree 不失历史；代价：错行不会被重生成自动纠正，须人工改正后重跑）。');
+  lines.push('');
+  lines.push('| 提交(短SHA) | 时间(UTC) | 门数 | 断言计数 | runId |');
+  lines.push('|---|---|---|---|---|');
+  for (const e of ordered) lines.push(e.line);
+  lines.push('');
+  lines.push(`<!-- GENERATED:END — 共 ${ordered.length} 行；gen-verify-evidence.mjs 生成（既有行追加保全，勿手改） -->`);
+  return lines.join('\n') + '\n';
+}
+
+const text = render();
+if (argv.includes('--check')) {
+  let disk = '';
+  try { disk = fs.readFileSync(OUT, 'utf8'); } catch { /* 缺文件走漂移分支 */ }
+  if (disk === text) { console.log('[verify-evidence] ✅ 与磁盘一致'); process.exit(0); }
+  console.error('[verify-evidence] 漂移：本地台账有新绿行未入摘要——关单时跑 node .agents/scripts/gen-verify-evidence.mjs 并随同提交');
+  process.exit(1);
+}
+fs.mkdirSync(path.dirname(OUT), { recursive: true });
+fs.writeFileSync(OUT, text);
+console.log(`✅ 已生成 ${path.relative(process.cwd(), OUT)}（绿凭证 ${text.split('\n').length - 8} 行）`);

package/templates/engine/.agents/scripts/gen-wiki-board.mjs

@@ -0,0 +1,221 @@
+// wiki 索引生成器：磁盘 + INDEX 速览表「用途」列 → 自动重生成 INDEX 速览计数/映射表 + 看板 DATA
+// 2026-09-13 引入：消除三层手工双写（短板①）。人工只维护两样：磁盘文件本身 + 速览表用途列。
+// 用法：node .agents/scripts/gen-wiki-board.mjs [--dry-run] [--help]
+//   （收录/删除/移动 wiki 文件后必跑，随后跑 verify-wiki-consistency.mjs）
+// 测试面已随引擎减重退役（2026-10-28，owner 决策），本脚本现无测试兜底
+// 生成范围（锚点内整段重写，锚点外字节原样保留）：
+//   INDEX.md 速览表数据行 / 「合计」行数字 / 「## 文件 → 主题 → 归属目录 映射表」到「## 命名规则」之间
+//   看板 知识沉淀总览.html 的 `const DATA = {...};` 整块
+// 注意：映射表节内的手工注记会被清除——背景说明请写进速览表「用途」列（人工列，生成器不覆盖）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+const USAGE = `用法：node .agents/scripts/gen-wiki-board.mjs [--dry-run] [--help]
+
+事实源：磁盘 wiki/<主题>/ 一层文件 + INDEX.md 速览表「用途」列（人工列）。重生成：
+  - wiki/INDEX.md：速览表数据行与文件计数、「合计」行数字、映射表节
+    （「## 文件 → 主题 → 归属目录 映射表」到「## 命名规则」之间整段）
+  - wiki/知识沉淀总览.html：const DATA = {...} 整块（summary 统计 + topics 文件清单 + dir 链接）
+两处生成区手改会被覆盖；锚点外内容原样保留。人工只维护磁盘文件 + 速览表「用途」列。
+
+选项：
+  --dry-run   只打印将生成内容的摘要与逐行差异，不写盘
+  --help      打印本说明`;
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(USAGE);
+  process.exit(0);
+}
+const unknown = args.filter((a) => a !== '--dry-run');
+if (unknown.length) {
+  console.error(`❌ 未知参数：${unknown.join(' ')}\n\n${USAGE}`);
+  process.exit(1);
+}
+const DRY = args.includes('--dry-run');
+
+const WIKI = 'wiki';
+const INDEX_P = path.join(WIKI, 'INDEX.md');
+const BOARD_P = path.join(WIKI, '知识沉淀总览.html');
+
+// ---- 磁盘枚举（事实源：文件在哪个主题目录就属于哪个主题）----
+// 登记口径（2026-09-17 起，与 verify-wiki-consistency.mjs 保持一致）：
+//   主题目录顶层：全量文件登记（现状不变）；
+//   直属子目录：仅登记 md/html 知识文档（排除 *.visual-check.* 工具产物；.json/.png 不计入）；
+//   数据维护主题例外——其子目录（schema变更/<批次>/ 等）走 README.md 台账，不参与登记。
+// gitignore 豁免（F4，incident 2026-09-23-code-review-f3-f4-closeout；p2-batch2 扩面到全 wiki/——
+// 活跃主题目录内的本机文件（如 *.xlsx）同样会造成生成物计数在 fresh clone 漂移）：
+// 排除 .gitignore 忽略的本机文件，git 不可用时退化为全量计数
+const gitIgnoredArchive = (() => {
+  try {
+    const out = execSync('git -c core.quotepath=false status --ignored=matching --porcelain -uall -- wiki',
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const prefix = 'wiki/';
+    return new Set(out.split(/\r?\n/)
+      .filter((l) => l.startsWith('!! '))
+      .map((l) => l.slice(3).trim().replace(/\/$/, ''))
+      .filter((p) => p.startsWith(prefix))
+      .map((p) => p.slice(prefix.length)));
+  } catch {
+    return new Set();
+  }
+})();
+const isKnowledgeDoc = (f) => /\.(md|html)$/i.test(f) && !/\.visual-check\./i.test(f);
+const diskTopics = new Map(); // name -> [{ name: '文件名或 子目录/文件名', dir: 'wiki/主题[/子目录]/' }]
+for (const d of fs.readdirSync(WIKI)) {
+  const p = path.join(WIKI, d);
+  if (!fs.statSync(p).isDirectory() || d === 'drafts-archive') continue;
+  // gitignore 豁免消费（p2-batch2 扩面落点）：gitIgnoredArchive 集合现为全 wiki/ 的忽略件相对路径——
+  // 活跃区 entries 构建处按「主题/文件」与「主题/子目录/文件」过滤（复核 P1-2：扩面集合此前无消费点=死代码）
+  const isIgnored = (rel) => { const k = rel.endsWith('/') ? rel.slice(0, -1) : rel; return gitIgnoredArchive.has(`${d}/${k}`) || gitIgnoredArchive.has(`${d}/${k}/`); }; // 尾斜杠归一（复核 P2-a；endsWith 替代正则——此文件转义层过于嘈杂）
+  const entries = fs.readdirSync(p)
+    .filter((f) => fs.statSync(path.join(p, f)).isFile() && !isIgnored(f))
+    .map((f) => ({ name: f, dir: `wiki/${d}/` }));
+  if (d !== '数据维护') {
+    for (const sub of fs.readdirSync(p)) {
+      const sp = path.join(p, sub);
+      if (!fs.statSync(sp).isDirectory() || isIgnored(`${sub}/`)) continue;
+      for (const f of fs.readdirSync(sp)) {
+        if (fs.statSync(path.join(sp, f)).isFile() && isKnowledgeDoc(f) && !isIgnored(`${sub}/${f}`)) {
+          entries.push({ name: `${sub}/${f}`, dir: `wiki/${d}/${sub}/` });
+        }
+      }
+    }
+  }
+  entries.sort((a, b) => a.name.localeCompare(b.name, 'zh'));
+  diskTopics.set(d, entries);
+}
+
+const archiveCount = (() => {
+  let n = 0;
+  const walk = (dir, rel = '') => {
+    for (const e of fs.readdirSync(dir)) {
+      const p = path.join(dir, e);
+      // 集合键带 drafts-archive/ 前缀（扫描面扩全 wiki/ 后），walk rel 须拼前缀比对（复核 P2-b）
+      const r = rel ? `drafts-archive/${rel}/${e}` : `drafts-archive/${e}`;
+      if (fs.statSync(p).isDirectory()) walk(p, rel ? `${rel}/${e}` : e);
+      else if (!gitIgnoredArchive.has(r)) n++;
+    }
+  };
+  if (fs.existsSync(path.join(WIKI, 'drafts-archive'))) walk(path.join(WIKI, 'drafts-archive'));
+  else console.error('⚠️ wiki/drafts-archive/ 不存在，归档计数按 0 处理（wiki 协议目录，建议恢复）');
+  return n;
+})();
+
+// ---- 读 INDEX 现速览表：主题顺序 + 用途列（人工，不覆盖）----
+// 切行须容忍 CRLF：按 '\n' 切会在行尾留 '\r'，速览表行锚定正则（\|$）整表失配 →
+// 「用途」列（唯一人工维护位）被静默重置为 <待补>（papercut 2026-09-17；fixture 见 gen-wiki-board.test.mjs 场景 1）
+// 用途列管道转义（p2-batch2）：生成侧对单元格 `|` → `\|`（行内码 \`|\`），解析侧容忍转义——
+// 否则含管道的用途描述会切坏表格行、下次生成该行解析失配走「新主题追加」把人工文本静默重置
+const BS = String.fromCharCode(92); // 反斜杠字符（转义写法在此文件里反复出错，用 charCode 表达）
+const PIPE_CH = '|';
+const escCell = (s) => String(s).split(PIPE_CH).join(BS + PIPE_CH);
+const unescCell = (s) => String(s).split(BS + PIPE_CH).join(PIPE_CH);
+const indexText = fs.readFileSync(INDEX_P, 'utf8');
+const overview = []; // {name, usage}
+// 解析正则（p2-batch2）：用途列允许转义管道 \|--`(?:\\.|[^|])*` 吃掉「转义字符+任一字符」或普通字符，
+// 裸管道才是列分隔。unescCell 还原人工原文。
+for (const line of indexText.split(/\r?\n/)) {
+  const m = line.match(/^\| ([^|]+) \| (\d+) \|((?:\\.|[^|])*)\|$/);
+  if (m && m[1].trim() !== '主题') overview.push({ name: m[1].trim(), usage: unescCell(m[3].trim()) });
+}
+// 主题顺序 = 速览表现顺序在前，磁盘新主题按中文排序追加
+const ordered = [...overview.filter((o) => diskTopics.has(o.name))];
+for (const t of [...diskTopics.keys()].sort((a, b) => a.localeCompare(b, 'zh'))) {
+  if (!ordered.some((o) => o.name === t)) ordered.push({ name: t, usage: '<待补：新主题用途描述>' });
+}
+
+const totalFiles = [...diskTopics.values()].reduce((n, f) => n + f.length, 0);
+
+// ---- 生成 INDEX 三段 ----
+const eol = indexText.includes('\r\n') ? '\r\n' : '\n';
+const overviewRows = ordered.map((o) => `| ${o.name} | ${diskTopics.get(o.name).length} | ${escCell(o.usage)} |`);
+const mappingSection = ordered.map((o) => {
+  const rows = diskTopics.get(o.name).map((e) => `| ${e.name} | ${o.name} | ${e.dir} |`);
+  return [`### ${o.name}（${diskTopics.get(o.name).length}）`, '', '| 文件名 | 主题 | 归属目录 |', '|---|---|---|', ...rows].join(eol);
+}).join(eol + eol);
+
+let out = indexText;
+// 速览表数据行（表头「| 主题 |」+ 分隔行之后的连续数据行整组替换）
+{
+  const lines = out.split(/\r?\n/);
+  const headIdx = lines.findIndex((l) => /^\| 主题 \|/.test(l));
+  if (headIdx < 0 || !/^[\|:\-\s]+$/.test(lines[headIdx + 1] || '')) {
+    console.error('❌ INDEX 速览表表头未找到，未写盘');
+    process.exit(1);
+  }
+  let lastData = headIdx + 1;
+  while (lastData + 1 < lines.length && lines[lastData + 1].startsWith('|')) lastData++;
+  const fixedRows = [...overviewRows, '| drafts-archive | — | 原文档备份（按 日期-主题 分目录） |'];
+  out = [...lines.slice(0, headIdx), '| 主题 | 文件数 | 用途 |', '|---|---|---|', ...fixedRows, ...lines.slice(lastData + 1)].join(eol);
+}
+// 合计行数字（锚点缺失即 fail-loud——静默 no-op 会让合计行悄悄陈旧，2026-09-24 审查修复）
+const totalRe = /合计：\*\*\d+ 份\*\*知识文档，\*\*\d+ 个主题\*\*/;
+if (!totalRe.test(out)) {
+  console.error('❌ INDEX「合计」行锚点未找到（须形如「合计：**N 份**知识文档，**M 个主题**」），未写盘');
+  process.exit(1);
+}
+out = out.replace(totalRe, `合计：**${totalFiles} 份**知识文档，**${diskTopics.size} 个主题**`);
+// 映射表区（节标题之间整段重写）
+{
+  const lines = out.split(/\r?\n/);
+  const s = lines.findIndex((l) => l.startsWith('## 文件 → 主题 → 归属目录 映射表'));
+  const e = lines.findIndex((l) => l.startsWith('## 命名规则'));
+  if (s >= 0 && e > s) {
+    out = [...lines.slice(0, s + 1), '', mappingSection, '', '---', '', ...lines.slice(e)].join(eol);
+  } else {
+    // 锚点缺失即 fail-loud（对齐速览表/合计行口径）——曾静默跳过致映射表悄悄陈旧仍报 ✅（2026-09-24 审查修复）
+    console.error('❌ INDEX 映射表锚点未找到（须有「## 文件 → 主题 → 归属目录 映射表」与其后的「## 命名规则」），未写盘');
+    process.exit(1);
+  }
+}
+
+// ---- 生成看板 DATA ----
+const boardText = fs.readFileSync(BOARD_P, 'utf8');
+const topicsJs = ordered.map((o) => {
+  // dir 相对看板自身（wiki/）——旧值带 wiki/ 前缀会被解析为 wiki/wiki/... 死链
+  const files = diskTopics.get(o.name).map((e) => `      { "file": ${JSON.stringify(e.name)}, "topic": ${JSON.stringify(o.name)}, "dir": ${JSON.stringify(`./${e.dir.slice('wiki/'.length)}`)} }`);
+  return `    { "name": ${JSON.stringify(o.name)}, "files": [\n${files.join(',\n')}\n    ]}`;
+}).join(',\n');
+const dataJs = `const DATA = {\n  "summary": { "total": ${totalFiles}, "topics": ${diskTopics.size}, "files": ${totalFiles}, "archive": ${archiveCount} },\n  "topics": [\n${topicsJs}\n  ]\n};`;
+const boardOut = boardText.replace(/const DATA = \{[\s\S]*?\n\};/, dataJs);
+if (boardOut === boardText && !/const DATA = \{[\s\S]*?\n\};/.test(boardText)) {
+  console.error('❌ 看板中未找到 const DATA = {...} 块，未写盘');
+  process.exit(1);
+}
+
+// ---- 写盘（dry-run 只预览差异）----
+if (DRY) {
+  console.log('🔎 --dry-run：未写盘，差异预览如下');
+  previewDiff('wiki/INDEX.md', indexText, out);
+  previewDiff('wiki/知识沉淀总览.html', boardText, boardOut);
+} else {
+  fs.writeFileSync(INDEX_P, out, 'utf8');
+  fs.writeFileSync(BOARD_P, boardOut, 'utf8');
+}
+
+const tail = DRY ? '将重写' : '已重写';
+console.log(`${DRY ? '🔎 [dry-run] 将生成' : '✅ 已生成'}：文件 ${totalFiles} 份 / 主题 ${diskTopics.size} 个 / 归档 ${archiveCount} 份；速览表 ${overviewRows.length} 行、映射表 ${ordered.length} 节、看板 DATA ${tail}`);
+console.log('   人工仅维护：磁盘文件 + 速览表「用途」列（新主题为 <待补> 的请补描述后重跑本脚本）');
+
+// dry-run 差异预览：首尾对齐后取中段变更块（逐行），各方向最多显示 10 行
+function previewDiff(label, before, after) {
+  if (before === after) {
+    console.log(`• ${label}：无变化`);
+    return;
+  }
+  const b = before.split(/\r?\n/);
+  const a = after.split(/\r?\n/);
+  let head = 0;
+  while (head < b.length && head < a.length && b[head] === a[head]) head++;
+  let tailN = 0;
+  while (tailN < b.length - head && tailN < a.length - head && b[b.length - 1 - tailN] === a[a.length - 1 - tailN]) tailN++;
+  const removed = b.slice(head, b.length - tailN);
+  const added = a.slice(head, a.length - tailN);
+  console.log(`• ${label}：第 ${head + 1} 行起变更，删 ${removed.length} 行 / 增 ${added.length} 行`);
+  for (const l of removed.slice(0, 10)) console.log(`    - ${l.slice(0, 120)}`);
+  if (removed.length > 10) console.log(`    - …（其余 ${removed.length - 10} 行略）`);
+  for (const l of added.slice(0, 10)) console.log(`    + ${l.slice(0, 120)}`);
+  if (added.length > 10) console.log(`    + …（其余 ${added.length - 10} 行略）`);
+}

package/templates/engine/.agents/scripts/gen-workflow-index.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// workflow 活跃层索引生成器（2026-09-21，intent 2026-09-21-workflow-doc-retrieval）
+// 用法：node .agents/scripts/gen-workflow-index.mjs [--dry-run] [--check] [--help]
+//   --dry-run  只打印差异预览，不写盘
+//   --check    不写盘；与磁盘不一致时 exit 1 并打印差异（供 check-loop 漂移告警）
+// 测试面已随引擎减重退役（2026-10-28，owner 决策），本脚本现无测试兜底
+// 口径：扫磁盘（对照 gen-wiki-board.mjs 与看板）；排除 _TEMPLATE.md。活跃 = draft / approved / open
+//   逐行列出（在跑的工作）；其余状态折叠进「档案计数」——fixed 未 closed 的 incident 与 approved
+//   孤儿 plan 属「待收口」，看板会告警；查档案用 kb-search（默认含全部状态）。
+// 生成区：INDEX.md 的 GENERATED:BEGIN/END 锚点注释之间整段重写，锚点外内容原样保留。
+import fs from 'node:fs';
+import path from 'node:path';
+import { ENUMS } from './workflow-enums.mjs';
+
+const USAGE = `用法：node .agents/scripts/gen-workflow-index.mjs [--dry-run] [--check] [--help]
+
+事实源：workflow/{intents,specs,plans,incidents}/*.md 的 frontmatter（状态/级别/日期/发现/模块）
+        + H1 标题 + 「## 验收标准」勾验统计；排除 _TEMPLATE.md。
+生成物：workflow/INDEX.md —— 活跃层逐行（类型|级别|状态|日期|模块|标题|验收）+ 档案计数（类型×模块）。
+选项：
+  --dry-run   只打印将生成内容的摘要与差异，不写盘
+  --check     不写盘；INDEX 与磁盘不一致时 exit 1（供 check-loop 漂移告警）
+  --help      打印本说明`;
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) { console.log(USAGE); process.exit(0); }
+const unknown = args.filter((a) => !['--dry-run', '--check'].includes(a));
+if (unknown.length) { console.error(`❌ 未知参数：${unknown.join(' ')}\n\n${USAGE}`); process.exit(1); }
+const DRY = args.includes('--dry-run');
+const CHECK = args.includes('--check');
+
+const WORKFLOW = 'workflow';
+const INDEX_P = path.join(WORKFLOW, 'INDEX.md');
+const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
+const TYPE_LABEL = { intents: 'INTENT', specs: 'SPEC', plans: 'PLAN', incidents: 'INCIDENT' };
+// 活跃口径 = 单源 doc.status.active ∪ incident.status.active；其余状态折叠进档案计数
+const ACTIVE_STATUS = [...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']];
+
+const BEGIN = '<!-- GENERATED:BEGIN — gen-workflow-index.mjs 整段重写，手工说明写在本行之前 -->';
+const END = '<!-- GENERATED:END -->';
+const HEADER = `# workflow 索引 — 活跃层与档案（生成物，勿手改）
+
+> 生成器 \`node .agents/scripts/gen-workflow-index.mjs\`（状态变更 / 新建文档后重跑；\`--check\` 校验漂移，check-loop 会告警）。
+> 活跃 = ${ACTIVE_STATUS.join(' / ')}（在跑）；其余状态折叠进档案计数，检索用 \`node .agents/scripts/kb-search.mjs "<词>"\`（默认含全部状态、活跃优先排序）。
+> 模块词表见 \`.agents/config/workflow-modules.txt\`。
+`;
+
+// ---- frontmatter（受限子集：每行 `键: 值`）+ H1 标题（去「INTENT — 」前缀），对照 workflow/README.md 文档协议 ----
+function parseDoc(text) {
+  const meta = {};
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (m) {
+    for (const line of m[1].split(/\r?\n/)) {
+      const kv = line.match(/^(\S+):\s*(.*)$/);
+      if (kv) meta[kv[1].trim()] = kv[2].trim();
+    }
+  }
+  const h1 = text.match(/^# (.+)$/m);
+  let title = h1 ? h1[1] : '';
+  // 前缀分隔只认 em/en dash（任意间距）或带空格的 ASCII 连字符——裸连字符是 kebab-case 的一部分，不截断（2026-09-24）
+  const dash = title.match(/\S+\s*(?:[—–]+|\s-\s)\s*(.+)$/);
+  if (dash) title = dash[1];
+  return { meta, title };
+}
+
+// ---- 验收勾验统计：仅「## 验收标准」节内（至下一个 ## 标题），无该节返回 null（对照看板口径）----
+function parseAcceptance(text) {
+  const h = text.match(/^## 验收标准.*$/m);
+  if (!h) return null;
+  const rest = text.slice(h.index + h[0].length);
+  const next = rest.match(/^## /m);
+  const section = next ? rest.slice(0, next.index) : rest;
+  const total = (section.match(/^\s*[-*] \[[ xX]\]/gm) || []).length;
+  if (!total) return null;
+  const done = (section.match(/^\s*[-*] \[[xX]\]/gm) || []).length;
+  return { done, total };
+}
+
+const esc = (s) => String(s).replace(/\|/g, '\\|'); // 表格单元格内管道转义
+
+function scan() {
+  const docs = [];
+  for (const type of DOC_TYPES) {
+    const dir = path.join(WORKFLOW, type);
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
+      const name = f.slice(0, -3);
+      const text = fs.readFileSync(path.join(dir, f), 'utf8');
+      const { meta, title } = parseDoc(text);
+      docs.push({
+        type,
+        file: `${type}/${f}`,
+        status: meta['状态'] || '（未填）',
+        level: meta['级别'] || '—',
+        date: meta['日期'] || meta['发现'] || name.slice(0, 10),
+        module: meta['模块'] || '—',
+        title: title || name,
+        accept: parseAcceptance(text),
+      });
+    }
+  }
+  return docs;
+}
+
+function render(docs) {
+  const active = docs.filter((d) => ACTIVE_STATUS.includes(d.status));
+  active.sort((a, b) => b.date.localeCompare(a.date) || a.type.localeCompare(b.type) || a.file.localeCompare(b.file));
+  const arch = docs.filter((d) => !ACTIVE_STATUS.includes(d.status));
+
+  const rows = active.map((d) =>
+    `| ${TYPE_LABEL[d.type]} | ${esc(d.level)} | ${esc(d.status)} | ${esc(d.date)} | ${esc(d.module)} | ${esc(d.title)} | ${d.accept ? `☑${d.accept.done}/${d.accept.total}` : '—'} |`);
+
+  const counts = new Map(); // `${type}|${module}` → 数量
+  for (const d of arch) {
+    const k = `${d.type}|${d.module}`;
+    counts.set(k, (counts.get(k) || 0) + 1);
+  }
+  const archRows = [...counts.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([k, n]) => {
+    const [type, module] = k.split('|');
+    return `| ${TYPE_LABEL[type]} | ${esc(module)} | ${n} |`;
+  });
+  const byStatus = new Map();
+  for (const d of arch) byStatus.set(d.status, (byStatus.get(d.status) || 0) + 1);
+  const statusLine = [...byStatus.entries()].sort((a, b) => b[1] - a[1]).map(([s, n]) => `${s} ${n}`).join(' · ');
+
+  return [
+    `## 活跃（${active.length}）`,
+    '',
+    '| 类型 | 级别 | 状态 | 日期 | 模块 | 标题 | 验收 |',
+    '|---|---|---|---|---|---|---|',
+    ...rows,
+    '',
+    `## 档案计数（${arch.length}，不进表）`,
+    '',
+    '| 类型 | 模块 | 数量 |',
+    '|---|---|---|',
+    ...archRows,
+    '',
+    `终态构成：${statusLine}；查档案用 \`node .agents/scripts/kb-search.mjs "<词>" --status all\`。`,
+  ].join('\n');
+}
+
+// ---- 组装：锚点内整段重写，锚点外（含首次创建时的 HEADER）原样保留 ----
+const docs = scan();
+const existing = fs.existsSync(INDEX_P) ? fs.readFileSync(INDEX_P, 'utf8') : '';
+const inner = `${BEGIN}\n\n${render(docs)}\n\n${END}`;
+let out;
+if (existing.includes(BEGIN) && existing.includes(END) && existing.indexOf(BEGIN) < existing.indexOf(END)) {
+  out = existing.slice(0, existing.indexOf(BEGIN)) + inner + existing.slice(existing.indexOf(END) + END.length);
+} else if (existing.includes(BEGIN) || existing.includes(END)) {
+  // 锚点残缺（END 被手工截断 / 顺序颠倒）：fail-loud 不写盘——曾走 append 分支产生双 GENERATED 区，旧区永不清理（2026-09-24）
+  console.error('❌ workflow/INDEX.md 生成锚点不完整（GENERATED:BEGIN/END 须成对且 BEGIN 在前）——手工修复锚点后重跑，未写盘');
+  process.exit(1);
+} else {
+  out = (existing ? existing.replace(/\s*$/, '') + '\n\n' : HEADER) + inner + '\n';
+}
+
+const nActive = docs.filter((d) => ACTIVE_STATUS.includes(d.status)).length;
+const nArch = docs.length - nActive;
+const summary = `活跃 ${nActive} 行 / 档案 ${nArch} 篇 / ${Buffer.byteLength(out, 'utf8')} B`;
+
+// 差异预览：首尾对齐后取中段变更块（逐行），各方向最多 10 行
+function previewDiff(before, after) {
+  if (before === after) return;
+  const b = before.split(/\r?\n/);
+  const a = after.split(/\r?\n/);
+  let head = 0;
+  while (head < b.length && head < a.length && b[head] === a[head]) head++;
+  let tailN = 0;
+  while (tailN < b.length - head && tailN < a.length - head && b[b.length - 1 - tailN] === a[a.length - 1 - tailN]) tailN++;
+  const removed = b.slice(head, b.length - tailN);
+  const added = a.slice(head, a.length - tailN);
+  console.log(`  第 ${head + 1} 行起变更：删 ${removed.length} 行 / 增 ${added.length} 行`);
+  for (const l of removed.slice(0, 10)) console.log(`    - ${l.slice(0, 140)}`);
+  if (removed.length > 10) console.log(`    - …（其余 ${removed.length - 10} 行略）`);
+  for (const l of added.slice(0, 10)) console.log(`    + ${l.slice(0, 140)}`);
+  if (added.length > 10) console.log(`    + …（其余 ${added.length - 10} 行略）`);
+}
+
+// 行尾归一比较（2026-09-30：fresh clone 检出 CRLF、生成段恒 LF——直接字符串相等会在克隆环境假阳性
+// 「漂移」（doctor §6 与 check-loop 检查 11 均经 --check 判定）；仅内容差异才算漂移）
+const normEol = (s) => String(s).replace(/\r\n/g, '\n');
+
+if (CHECK) {
+  if (normEol(out) === normEol(existing)) {
+    console.log(`✅ workflow/INDEX.md 与磁盘一致（${summary}）`);
+    process.exit(0);
+  }
+  console.error(`❌ workflow/INDEX.md 与磁盘不一致（${summary}）——跑 node .agents/scripts/gen-workflow-index.mjs 重新生成`);
+  previewDiff(existing, out);
+  process.exit(1);
+}
+
+if (DRY) {
+  console.log(`🔎 --dry-run：未写盘（${summary}）`);
+  if (normEol(out) === normEol(existing)) console.log('• workflow/INDEX.md：无变化');
+  else previewDiff(existing, out);
+} else {
+  fs.writeFileSync(INDEX_P, out, 'utf8');
+  console.log(`✅ 已生成 workflow/INDEX.md：${summary}`);
+}