agentic-flow-kit 1.3.0 → 1.5.0

package/templates/_agents/scripts/confirm-doc.test.mjs

@@ -736,5 +736,40 @@ const writeTrust = (root, cfg) => {
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- S40 测试绿凭证按 doc 绑定（2026-10-08 verify-doc-binding）----
+// 核心防线三条：① v6 + 只有**他单**绿行 → advisory 出账（漏洞已堵）；② v6 + 本单绿行 → 静默；
+// ③ **v5 + 只有他单绿行 → 静默**（向后兼容反例——收紧只许对 v6+ 生效，存量装户零变化）。
+// 文案锚点：既有 S38/S39 锚定「无测试绿凭证」六字连续 + 「verify.mjs」出现，本组不得破坏。
+{
+  const mkVerifyRoot = (pv, lines) => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-docbind-'));
+    const docP = path.join(root, 'workflow', 'intents');
+    fs.mkdirSync(docP, { recursive: true });
+    fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+    fs.writeFileSync(path.join(root, '.agents', 'kit.json'), JSON.stringify({ policyVersion: pv }), 'utf8');
+    fs.writeFileSync(path.join(root, '.agents', 'verifications.jsonl'), lines, 'utf8');
+    fs.writeFileSync(path.join(docP, '2026-10-08-m.md'),
+      '---\n状态: approved\n级别: L1\n确认指纹: cccc3333cccc3333\n---\n# I\n\n## 验收标准（可测试）\n- [x] 用例通过（证据:测试全绿）\n', 'utf8');
+    return root;
+  };
+  const green = (doc) => `${JSON.stringify({ ts: new Date().toISOString(), exitCode: 0, suite: 'npm test', passed: 1, failed: 0, ...(doc ? { doc } : {}) })}\n`;
+  const MINE = 'workflow/intents/2026-10-08-m.md';
+  const OTHER = 'workflow/intents/2026-10-08-other.md';
+  const runM = (root) => spawnSync(process.execPath, [CLI, MINE, '--delegated', '可以'], { cwd: root, encoding: 'utf8' });
+
+  const r40 = runM(mkVerifyRoot(6, green(OTHER)));
+  check('S40① v6 + 只有他单绿行 → advisory 出账（跨单背书漏洞已堵）+ 文案带 --doc',
+    r40.status === 0 && /无测试绿凭证/.test(r40.stderr) && /--doc/.test(r40.stderr), String(r40.stderr).slice(0, 200));
+  const r41 = runM(mkVerifyRoot(6, green(MINE)));
+  check('S40② v6 + 本单绿行 → 静默（绑定成立）',
+    r41.status === 0 && !/无测试绿凭证/.test(r41.stderr), String(r41.stderr).slice(0, 200));
+  const r42 = runM(mkVerifyRoot(5, green(OTHER)));
+  check('S40③ v5 + 只有他单绿行 → **静默**（兼容反例：收紧只对 v6+ 生效，存量装户零变化）',
+    r42.status === 0 && !/无测试绿凭证/.test(r42.stderr), String(r42.stderr).slice(0, 200));
+  const r43 = runM(mkVerifyRoot(6, green(null)));
+  check('S40④ v6 + 不带 doc 的绿行（CI 场景）→ 不给本单背书，advisory 出账',
+    r43.status === 0 && /无测试绿凭证/.test(r43.stderr), String(r43.stderr).slice(0, 200));
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/ensure-board.mjs

@@ -105,7 +105,7 @@ function openBrowser(url) {
   try {
     if (process.platform === 'win32') spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
     else spawn(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
-  } catch { }
+  } catch { /* 浏览器拉起失败不阻断看板流程 */ }
 }
 
 // ---- 主流程（返回退出码，自然排水退出——不用 process.exit：强退在 Windows 上会触发 libuv 断言）----
@@ -123,7 +123,7 @@ async function main() {
       board = b;
       const stale = staleCode(b.startedAt);
       if (stale === true) {
-        try { process.kill(b.pid); } catch { } // 进程可能已自行退出，忽略
+        try { process.kill(b.pid); } catch { /* 进程可能已自行退出 */ }
         await sleep(500);
         action = 'restarted (stale code detected)';
       } else if (stale === null) {

package/templates/_agents/scripts/fill-intent.mjs

@@ -31,8 +31,8 @@ const SECTIONS = [
   { title: '目标', hint: '- <可验证的目标>' },
   { title: '非目标（L1 微改动无实质内容可删本节，不硬填）', hint: '- <明确不做的，防止范围蔓延>' },
   { title: '约束（L1 微改动无实质内容可删本节，不硬填）', hint: '- <复用什么、不许动什么>' },
-  { title: '影响面', hint: '- 模块：<词表之一，见 .agents/workflow-modules.txt>\n- 数据库：无 / <表名>（涉及 schema 变更 $\rightarrow$ L3；无 schema 的运行时 / 管线结构面亦为 L3，判据见 .agents/commands/new-task.md §级别判断）\n- 前端页面：<路由或组件，无则删本行>' },
-  { title: '触达红线（对照 AGENTS.md，勾选仅标记触及范围；具体如何满足在同名 spec 或 Quick-Plan 中说明）', hint: '- [ ] <按本项目 AGENTS.md 红线逐行补；无则删本行>\n- [ ] 规则 / 契约变更（编码权威 / 共享契约 / 接口签名 / 既有参数语义 / 全局口径）$\rightarrow$ 级别至少 L2\n- [ ] schema / 迁移 SQL / DI 链 / 认证与中间件管线 $\rightarrow$ 级别 L3\n\n> 触及任一红线即为 L2 / L3，必须立 ../specs/YYYY-MM-DD-<主题>.md 写明如何满足，方可起草 plan。' },
+  { title: '影响面', hint: '- 模块：<词表之一，见 .agents/workflow-modules.txt>\n- 数据库：无 / <表名>（涉及 schema 变更 → L3；无 schema 的运行时 / 管线结构面亦为 L3，判据见 .agents/commands/new-task.md §级别判断）\n- 前端页面：<路由或组件，无则删本行>' },
+  { title: '触达红线（对照 AGENTS.md，勾选仅标记触及范围；具体如何满足在同名 spec 或 Quick-Plan 中说明）', hint: '- [ ] <按本项目 AGENTS.md 红线逐行补；无则删本行>\n- [ ] 规则 / 契约变更（编码权威 / 共享契约 / 接口签名 / 既有参数语义 / 全局口径）→ 级别至少 L2\n- [ ] schema / 迁移 SQL / DI 链 / 认证与中间件管线 → 级别 L3\n\n> 触及任一红线即为 L2 / L3，必须立 ../specs/YYYY-MM-DD-<主题>.md 写明如何满足，方可起草 plan。' },
   { title: '验收标准（可测试）', hint: '- [ ] <逐条可测试；写不出可测试判据 = 还没想清楚>\n\n> **闭环对账**：关单在 test 阶段（不依赖 deploy）。intent 置 done 前逐条勾验，每条补证据——`- [x] <判据>（证据：<commit SHA / 测试用例名 / 冒烟脚本输出>）`。\n> done 状态仍有未勾项会被 check-loop 拦截（2026-09-12 起新建 intent 为 hard-block，存量 intent 仅 warning 提示）；勾选但缺「证据：」为 hard-block。' },
 ];
 

package/templates/_agents/scripts/fill-plan.mjs

@@ -9,7 +9,6 @@ import path from 'node:path';
 import { ENUMS } from './workflow-enums.mjs';
 import { draftGateFor, resolveWorkspace } from './stage-gates.mjs';
 
-const TODAY = new Date().toISOString().slice(0, 10);
 const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/workflow-enums.txt）
 
 function parseArgs(argv) {
@@ -40,7 +39,7 @@ const FULL_SECTIONS = [
   L1_SECTIONS[2],
 ];
 
-export function renderPlan({ topic, level = 'L1', date = TODAY }) {
+export function renderPlan({ topic, level = 'L1' }) {
   if (!LEVELS.includes(level)) throw new Error('level 不在枚举 ' + LEVELS.join('|') + '：' + level);
   const sections = level === 'L1' ? L1_SECTIONS : FULL_SECTIONS;
   const fm = '---\n状态: draft\n级别: ' + level + '\n模块: pipeline\n---\n';

package/templates/_agents/scripts/gate-seg.mjs

@@ -0,0 +1,54 @@
+// gate-seg.mjs — 门禁 ROI 段插桩共用件（2026-10-08 gate-roi-metrics）
+// 为什么独立成件：check-loop.mjs 与 check-hygiene.mjs **互相不能反向 import**（前者已 import 后者，
+// 后者再 import 前者即循环依赖）——而两者都要插桩。判据单源必须只有一处，故抽本件。
+//
+// 机制：每次 gateSeg() 调用先**结算上一段**（段内 warnings/blockers 增量条数 + 耗时），再记本段起点。
+// 统计完全由数组长度差推出——**不改任何 warnings.push / blockers.push 调用点**，判定逻辑与文案零改动。
+// 默认路径（无 --gate-stats）下 segs 只在内存里攒、不打印不写盘 → 输出契约逐字节不变（硬约束：
+// pre-push / pre-commit 消费者 + doctor 的 WARN 行计数 + check-loop.test.mjs 223 断言全依赖它）。
+//
+// 耗时口径**刻意包含子进程时间**（检查 11 调两个生成器 --check、检查 13 调 sh rule-budget.sh）——
+// 门禁真实成本本就要含子进程；不做剔除，但看板与 spec 均显式声明该口径防误读。
+export function gateSeg(collector, id, label) {
+  const now = Date.now();
+  const prev = collector.current;
+  if (prev) {
+    collector.segs.push({
+      id: prev.id,
+      label: prev.label,
+      warns: collector.warnings.length - prev.w,
+      blocks: collector.blockers.length - prev.b,
+      ms: now - prev.t,
+    });
+  }
+  collector.current = { id, label, w: collector.warnings.length, b: collector.blockers.length, t: now };
+}
+
+// finishSegs：结算末段（末段之后没有下一次 gateSeg 调用，须显式收口，否则最后一段不进账）
+export function finishSegs(collector) {
+  if (!collector.current) return collector.segs; // 已结算过（幂等——writeGateStats 与输出段各调一次不会重复入账）
+  gateSeg(collector, '__end__', '__end__'); // 本次调用结算上一段；记下的 current 置空防重复结算
+  collector.current = null;
+  return collector.segs;
+}
+
+// makeCollector：建收集器（引用同一对数组，不复制数据）
+export function makeCollector(warnings, blockers) {
+  return { warnings, blockers, segs: [], current: null };
+}
+
+// appendSegs：并入「在别处结算出的段」，供模块化门禁使用（2026-10-08 gate-roi-metrics 修复）。
+//   背景：check-hygiene.mjs 产出的是**局部** warnings 数组（由 check-loop 事后 spread 进全局），
+//   故它的增量在模块执行期间**不反映**到 check-loop 的数组上。若直接共用游标插桩，后果是确定的错账：
+//   本模块 5 段恒记 0 条命中，而它的全部增量会被误记到模块之后的第一个段（检查 3）头上——
+//   实测已抓到：某次 hygiene 产出 1 条警告被记成「检查 13 命中」。
+//   语义：先结算本收集器当前段（模块前的检查，如检查 1）→ 按序并入外来段 → 游标清空，
+//   下一个 gateSeg 从零起算，Δ 天然正确。
+//   空 segs 直接返回且**不结算**当前段：没有东西可并入时不该改变原有结算时序。
+export function appendSegs(collector, segs) {
+  if (!segs || !segs.length) return collector.segs;
+  finishSegs(collector);
+  collector.segs.push(...segs);
+  collector.current = null;
+  return collector.segs;
+}

package/templates/_agents/scripts/gate-seg.test.mjs

@@ -0,0 +1,112 @@
+// gate-seg.test.mjs — 门禁 ROI 段插桩共用件测试（2026-10-08 gate-roi-metrics）
+// 被测：gateSeg 结算语义 / finishSegs 幂等 / makeCollector 引用同一对数组。
+// 判据单源所在：check-loop.mjs 与 check-hygiene.mjs 都靠本件插桩，故它的正确性是全部门禁成本度量的地基——
+// 段归属算错则整张 ROI 表失真而无人察觉。端到端回归网仍是 check-loop.test.mjs（223 断言）。
+// 用法：node templates/_agents/scripts/gate-seg.test.mjs
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const { gateSeg, finishSegs, makeCollector, appendSegs } =
+  await import(pathToFileURL(path.join(SCRIPT_DIR, 'gate-seg.mjs')).href);
+
+let pass = 0, fail = 0;
+const check = (name, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { fail++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+};
+
+// ---- makeCollector：引用同一对数组（不复制）----
+{
+  const w = [], b = [];
+  const c = makeCollector(w, b);
+  check('makeCollector：引用同一对数组（push 即被看见，无复制）', c.warnings === w && c.blockers === b);
+  check('makeCollector：初始 segs 为空、current 为空', Array.isArray(c.segs) && c.segs.length === 0 && c.current === null);
+}
+
+// ---- gateSeg：每次调用结算上一段，首调不结算 ----
+{
+  const w = [], b = [];
+  const c = makeCollector(w, b);
+  gateSeg(c, '1', '检查一');
+  check('gateSeg：首次调用只记起点不结算（segs 仍空）', c.segs.length === 0 && c.current.id === '1');
+  w.push('a'); b.push('b'); b.push('c');          // 段一产出 1 warn + 2 blocks
+  gateSeg(c, '2', '检查二');
+  check('gateSeg：第二次调用结算上一段（warns=1 blocks=2，id/label 对）',
+    c.segs.length === 1 && c.segs[0].id === '1' && c.segs[0].label === '检查一'
+    && c.segs[0].warns === 1 && c.segs[0].blocks === 2, JSON.stringify(c.segs));
+  check('gateSeg：结算后 current 切到新段', c.current.id === '2');
+  // 零命中段也要入账（死检查识别依赖「声明了但从未命中」——漏记即误判为未声明）
+  gateSeg(c, '3', '检查三');
+  check('gateSeg：零命中段照样入账（warns=0 blocks=0）',
+    c.segs.length === 2 && c.segs[1].id === '2' && c.segs[1].warns === 0 && c.segs[1].blocks === 0, JSON.stringify(c.segs));
+}
+
+// ---- finishSegs：结算末段 + 幂等（writeGateStats 与输出段各调一次不得重复入账）----
+{
+  const w = [], b = [];
+  const c = makeCollector(w, b);
+  gateSeg(c, '1', '检查一');
+  w.push('x');
+  const segs1 = finishSegs(c);
+  check('finishSegs：结算末段（末段后无下次调用否则该段丢失）',
+    segs1.length === 1 && segs1[0].id === '1' && segs1[0].warns === 1, JSON.stringify(segs1));
+  const segs2 = finishSegs(c);
+  check('finishSegs：幂等——二次调用不重复入账（防 __end__ 伪段污染表）',
+    segs2.length === 1 && !segs2.some((s) => s.id === '__end__'), JSON.stringify(segs2));
+  check('finishSegs：结算后 current 置空', c.current === null);
+}
+
+// ---- ms 单调不减（耗时度量地基）----
+{
+  const c = makeCollector([], []);
+  gateSeg(c, '1', 'a');
+  const t = Date.now(); while (Date.now() - t < 5) { /* 占位：保证有可测间隔 */ }
+  gateSeg(c, '2', 'b');
+  check('耗时字段：ms 为非负整数且单调（门禁成本度量的地基）',
+    Number.isInteger(c.segs[0].ms) && c.segs[0].ms >= 0, JSON.stringify(c.segs[0]));
+}
+
+// ---- appendSegs：模块化门禁的段归属（本次实抓到错账的根因，钉死）----
+// 症状：check-hygiene.mjs 的增量不反映到 check-loop 的数组上，直接共用游标会让 hygiene 各段恒记 0，
+//       而它的全部增量被误记到模块之后的第一段（检查 3）。下面是该场景的最小复现与修复后行为。
+{
+  const globalW = [], globalB = [];
+  const g = makeCollector(globalW, globalB);
+  gateSeg(g, '1', '检查1');            // 模块前的一段
+  globalW.push('w-check1');            // 检查 1 产出 1 条
+
+  // 模块（局部数组）：检查 2 → 检查 11 各产出 1 条
+  const localW = [];
+  const l = makeCollector(localW, []);
+  gateSeg(l, '2', '检查2');
+  localW.push('w-check2');
+  gateSeg(l, '11', '检查11');
+  localW.push('w-check11');
+
+  appendSegs(g, finishSegs(l));
+  const order = g.segs.map((s) => s.id);
+  const byId = new Map(g.segs.map((s) => [s.id, s.warns]));
+  check('appendSegs：模块后的一段先结算（检查 1 不被外来段吞掉）',
+    order[0] === '1' && byId.get('1') === 1, JSON.stringify(g.segs));
+  check('appendSegs：外来段按序并入且各自归属正确（2 → 1 条、11 → 1 条，**不都记到后一段**）',
+    order.slice(1).join(',') === '2,11' && byId.get('2') === 1 && byId.get('11') === 1, JSON.stringify(g.segs));
+  check('appendSegs：并入后游标清空，下一段从零起算（不把外来增量算进模块之后的段）',
+    g.current === null, JSON.stringify(g.current));
+  gateSeg(g, '3', '检查3');
+  globalW.push(...['w-check3a', 'w-check3b']);
+  gateSeg(g, '4', '检查4');
+  check('appendSegs：模块之后的第一段只记自己的增量（检查 3 = 2 条，不含 hygiene 的 2 条）',
+    g.segs.find((s) => s.id === '3').warns === 2, JSON.stringify(g.segs));
+
+  // 空外来段：既不并入也不提前结算（不改变原有结算时序）
+  const w2 = [], b2 = [];
+  const g2 = makeCollector(w2, b2);
+  gateSeg(g2, '1', 'a');
+  appendSegs(g2, []);
+  check('appendSegs：空外来段 → 收集器原样不动（不结算、不并入，结算时序不变）',
+    g2.segs.length === 0 && g2.current !== null, JSON.stringify(g2));
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/gen-wiki-board.mjs

@@ -141,7 +141,7 @@ let out = indexText;
 {
   const lines = out.split(/\r?\n/);
   const headIdx = lines.findIndex((l) => /^\| 主题 \|/.test(l));
-  if (headIdx < 0 || !/^[\|:\-\s]+$/.test(lines[headIdx + 1] || '')) {
+  if (headIdx < 0 || !/^[|:\-\s]+$/.test(lines[headIdx + 1] || '')) {
     console.error('❌ INDEX 速览表表头未找到，未写盘');
     process.exit(1);
   }

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

@@ -7,8 +7,13 @@
 // （多次 done 取首关；无台账行的存量单诚实跳过不虚构）。真实分布基准（2026-10-08 本仓 43 单）：P50=0 / P90=7 / max=8。
 // 复用：require('./agg-delegations.cjs') 纯函数（readLedger / metrics / gateMonth / expansionVerdict）——
 //   质量判据零重复（N3 教训）；readLedger 的 root 显式参数 + soft 模式为本批使能导出（原签名行为不变）。
-// isMain 守卫 + 纯函数导出（board-kb-p1 先例）：closeDurations / pickPct / durationVerdict 供测试 import 直测。
-// 用法：node .agents/scripts/gen-workflow-dashboard.mjs [--dry-run]
+// isMain 守卫 + 纯函数导出（board-kb-p1 先例）：closeDurations / pickPct / durationVerdict / normalizeForCheck 供测试 import 直测。
+// 用法：node .agents/scripts/gen-workflow-dashboard.mjs [--dry-run | --check]
+//   --check  不写盘；与磁盘不一致时 exit 1 并打印差异（供 check-loop 检查 11 漂移告警，2026-10-08 selfmeasure-and-modularize）
+//     两道归一缺一不可（均照 gen-workflow-index.mjs 先例）：
+//     ① 行尾：fresh clone 检出 CRLF、生成段恒 LF——直接字符串相等会在克隆环境假阳性「漂移」（2026-09-30 该坑已在
+//        gen-workflow-index 踩过，本件照抄 normEol）；
+//     ② 「生成于 <ISO>」行：每次运行必变，不归一则门禁恒红（不可消退噪声，违反 audit-gate-hardening P3 教训）。
 // 测试：node templates/_agents/scripts/gen-workflow-dashboard.test.mjs
 import fs from 'node:fs';
 import path from 'node:path';
@@ -112,15 +117,52 @@ export function qualityRows(root) {
     verdictMap.set(ym, verdict);
     const pct = (x) => (Number.isFinite(x) ? `${Math.round(x * 100)}%` : '—');
     const avg = Number.isFinite(m.avgRework) ? m.avgRework.toFixed(2) : '—';
-    out.push(`| ${ym} | ${m.total} | ${pct(m.passRate)} | ${avg} | ${pct(m.fallbackRate)} | ${verdict} |`);
+    // 门禁噪声返工单列（2026-10-08 selfmeasure-and-modularize）：设计返工与噪声返工分列可诊断——
+    // 「平均返工」把两者平均在一起时看不出该改门禁还是改设计。
+    out.push(`| ${ym} | ${m.total} | ${pct(m.passRate)} | ${m.reworkSum} | ${m.reworkNoiseSum} | ${avg} | ${pct(m.fallbackRate)} | ${verdict} |`);
   }
   return { rows: out, verdictMap, months };
 }
 
-const USAGE = '用法：node .agents/scripts/gen-workflow-dashboard.mjs [--dry-run]';
+// gateRoiLines：门禁 ROI 节的行（2026-10-08 gate-roi-metrics）
+//   口径声明 + 采集/查看入口。**刻意不把运行数据（次数 / 耗时 / 噪声率）铺进 DASHBOARD**——
+//   本文件被检查 11（--check）覆盖，而采集数据每跑一次门禁就变一次：铺进去等于
+//   「每次采集必产一条漂移 WARN」＝不可消除噪声（audit-gate-hardening P3 的反面教材）。
+//   连「有无数据」也不做分支（cache 已 gitignore → 新克隆必然无 cache，一采集文案就翻转 = 又一次漂移）：
+//   降级语义交由 CLI 承担——agg-gate-stats.mjs 空数据时自己打印「未采集——跑 check-loop --gate-stats」。
+//   故本节恒为静态文案：**任何时候生成本文件，字节恒等**（测试 ⑤ 的两条 --check exit 0 钉的就是这条）。
+export function gateRoiLines() {
+  return [
+    '- 采集：`node .agents/scripts/check-loop.mjs --gate-stats`（数据落 `.agents/cache/gate-stats.jsonl`，该目录已 gitignore；不带 flag 时零写入、输出逐字节不变）',
+    '- 看数值：`node .agents/scripts/agg-gate-stats.mjs [--days 30]`——输出成本排序 + 两类决策依据：噪声率 top（该收窄或该修）、死检查（该拆或该降级）；无采集数据时该命令自己提示「未采集」并给出采集命令',
+    '- 口径：耗时**含子进程时间**（检查 11 调两个生成器 `--check`、检查 13 调 `sh rule-budget.sh`）——门禁真实成本，不做剔除；样本 <5 次时只作线索，不作决策依据',
+    '- 本节为何不铺数值：本文件被检查 11 漂移门覆盖，运行数据每跑一次门禁即变一次，铺进来会让每次采集都产一条漂移 WARN（不可消除噪声）',
+  ];
+}
+
+const USAGE = '用法：node .agents/scripts/gen-workflow-dashboard.mjs [--dry-run | --check]';
+
+// normalizeForCheck：--check 比对前的双归一（纯函数供测试直测）——行尾 CRLF→LF + 「生成于 <ISO>」行抹平。
+//   导出是为了让测试不必 spawn 子进程即可断言「仅时间戳不同 → 归一后相等」（门禁恒红的直接防线）。
+export function normalizeForCheck(s) {
+  return String(s)
+    .replace(/\r\n/g, '\n')
+    .replace(/生成于 \d{4}-\d{2}-\d{2}T[\d:.]+Z/g, '生成于 <TS>');
+}
+
+function firstDiffLine(a, b) {
+  const la = a.split('\n');
+  const lb = b.split('\n');
+  for (let i = 0; i < Math.max(la.length, lb.length); i++) {
+    if (la[i] !== lb[i]) return i + 1;
+  }
+  return -1;
+}
 
 function main() {
-  const dry = process.argv.includes('--dry-run');
+  const args = process.argv.slice(2);
+  const dry = args.includes('--dry-run');
+  const check = args.includes('--check');
   const intents = collectDoneIntents(ROOT);
   const doneMap = collectDoneMap(ROOT);
   const { days, skipped } = closeDurations(intents, doneMap);
@@ -160,18 +202,43 @@ function main() {
     '',
     '## 质量 / 返工（月度，判据复用 agg-delegations）',
     '',
-    '| 月份 | 有效任务 | 一次通过率 | 平均返工 | 主兜底占比 | 扩容门判定 |',
-    '|------|----------|------------|----------|------------|------------|',
-    ...(q.rows.length ? q.rows : ['| — | — | — | — | — | 台账暂无数据 |']),
+    '| 月份 | 有效任务 | 一次通过率 | 设计返工 | 门禁噪声返工 | 平均返工 | 主兜底占比 | 扩容门判定 |',
+    '|------|----------|------------|---------|-------------|--------|------------|------------|',
+    ...(q.rows.length ? q.rows : ['| — | — | — | — | — | — | — | 台账暂无数据 |']),
+    '',
+    '## 门禁 ROI（门禁自身的度量）',
+    '',
+    ...gateRoiLines(),
     '',
   ];
   const out = lines.join('\n');
+  const target = path.join(ROOT, 'workflow', 'DASHBOARD.md');
+  // --check 优先于写盘、--dry-run 优先于 --check（显式不写盘意图最高）：比对模式不改任何盘面。
+  if (check) {
+    let disk;
+    try {
+      disk = fs.readFileSync(target, 'utf8');
+    } catch {
+      console.error(`[check] ❌ ${path.relative(ROOT, target) || 'workflow/DASHBOARD.md'} 不存在或不可读——跑 node .agents/scripts/gen-workflow-dashboard.mjs 生成`);
+      process.exitCode = 1;
+      return;
+    }
+    const a = normalizeForCheck(out);
+    const b = normalizeForCheck(disk);
+    if (a === b) {
+      console.log(`[check] ✅ ${path.relative(ROOT, target) || 'workflow/DASHBOARD.md'} 与盘面一致（行尾与「生成于」时间戳已归一）`);
+      return;
+    }
+    const ln = firstDiffLine(a, b);
+    console.error(`[check] ❌ ${path.relative(ROOT, target) || 'workflow/DASHBOARD.md'} 与当前事实不一致（首个差异在第 ${ln} 行）——跑 node .agents/scripts/gen-workflow-dashboard.mjs 重新生成`);
+    process.exitCode = 1;
+    return;
+  }
   if (dry) {
     console.log(out);
     console.log(`（--dry-run：未写盘。${USAGE}）`);
     return;
   }
-  const target = path.join(ROOT, 'workflow', 'DASHBOARD.md');
   fs.mkdirSync(path.dirname(target), { recursive: true });
   fs.writeFileSync(target, out, 'utf8');
   console.log(`✅ 已生成 ${path.relative(ROOT, target) || 'workflow/DASHBOARD.md'}`);

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

@@ -10,10 +10,8 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const { closeDurations, pickPct, durationVerdict, qualityRows, DURATION_BAND } =
+const { closeDurations, pickPct, durationVerdict, qualityRows, DURATION_BAND, normalizeForCheck, gateRoiLines } =
   await import(pathToFileURL(path.join(SCRIPT_DIR, 'gen-workflow-dashboard.mjs')).href);
-const agg = (await import(pathToFileURL(path.join(SCRIPT_DIR, 'agg-delegations.cjs')).href)).default
-  ?? null; // .cjs 经 import 具名空间取——见下方 createRequire 兜底
 import { createRequire } from 'node:module';
 const require2 = createRequire(import.meta.url);
 const aggCjs = require2(path.join(SCRIPT_DIR, 'agg-delegations.cjs'));
@@ -122,5 +120,68 @@ const INTENT = (fm) => `---\n${fm}\n---\n# INTENT — x\n`;
   fs.rmSync(empty, { recursive: true, force: true });
 }
 
+// ---- ④ --check 漂移门（2026-10-08 selfmeasure-and-modularize）----
+// 归一（CRLF + 「生成于」戳）不过则门禁恒红 = 不可消退噪声（audit-gate-hardening P3），故纯函数层先钉死。
+{
+  const base = '# dash\n> 生成于 2026-10-07T13:56:00.376Z\n| P50 | 0 天 |\n';
+  check('--check 归一：仅「生成于」戳不同 → 归一后相等（否则门禁恒红）',
+    normalizeForCheck(base) === normalizeForCheck(base.replace('2026-10-07T13:56:00.376Z', '2026-10-08T00:00:00.000Z')));
+  check('--check 归一：CRLF 盘面 vs LF 生成段 → 相等（gen-workflow-index 2026-09-30 同坑先例）',
+    normalizeForCheck(base) === normalizeForCheck(base.replace(/\n/g, '\r\n')));
+  check('--check 归一：内容真漂移仍不等（归一不得吞真差异）',
+    normalizeForCheck(base) !== normalizeForCheck(base.replace('| P50 | 0 天 |', '| P50 | 7 天 |')));
+
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-dash-check-'));
+  W(root, 'workflow/intents/2026-10-01-x.md', INTENT('状态: done\n级别: L1\n日期: 2026-10-01\n模块: pipeline'));
+  const gen = path.join(SCRIPT_DIR, 'gen-workflow-dashboard.mjs');
+  const runCheck = () => spawnSync(process.execPath, [gen, '--check'], {
+    cwd: root, encoding: 'utf8', env: { ...process.env, CHECK_LOOP_ROOT: root },
+  });
+  const rMiss = runCheck();
+  check('--check 端到端：盘面缺失 → exit 1 + 提示生成', rMiss.status === 1 && /不存在或不可读/.test(rMiss.stderr || ''), `status=${rMiss.status}`);
+  spawnSync(process.execPath, [gen], { cwd: root, env: { ...process.env, CHECK_LOOP_ROOT: root } });
+  const rOk = runCheck();
+  check('--check 端到端：刚生成 → exit 0', rOk.status === 0 && /一致/.test(rOk.stdout || ''), `status=${rOk.status} ${rOk.stdout || ''}${rOk.stderr || ''}`);
+  fs.appendFileSync(path.join(root, 'workflow', 'DASHBOARD.md'), '\n<!-- drift -->\n');
+  const rDrift = runCheck();
+  check('--check 端到端：内容漂移 → exit 1 + 差异行号 + 修复命令',
+    rDrift.status === 1 && /首个差异在第 \d+ 行/.test(rDrift.stderr || '') && /gen-workflow-dashboard\.mjs 重新生成/.test(rDrift.stderr || ''), `status=${rDrift.status} ${rDrift.stderr || ''}`);
+  const noWrite = fs.readFileSync(path.join(root, 'workflow', 'DASHBOARD.md'), 'utf8');
+  check('--check 端到端：不写盘（漂移态下盘面保持原样）', noWrite.includes('<!-- drift -->'));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- ⑤ 门禁 ROI 节（2026-10-08 gate-roi-metrics）----
+// 本节存在的核心断言不是「有数值」，而是「**不因运行数据而漂移」**：DASHBOARD 被检查 11 --check 覆盖，
+// 采集数值每跑一次门禁就变一次——铺进去等于每次采集必报一条漂移 WARN（不可消除噪声）。
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-dash-roi-'));
+  W(root, 'workflow/intents/2026-10-01-x.md', INTENT('状态: done\n级别: L1\n日期: 2026-10-01\n模块: pipeline'));
+  const gen = path.join(SCRIPT_DIR, 'gen-workflow-dashboard.mjs');
+  const run = (...args) => spawnSync(process.execPath, [gen, ...args], { cwd: root, encoding: 'utf8', env: { ...process.env, CHECK_LOOP_ROOT: root } });
+  const dashOf = () => fs.readFileSync(path.join(root, 'workflow', 'DASHBOARD.md'), 'utf8');
+
+  // 无采集态（先于造 cache 生成）：节恒为静态文案，故与有无数据无关
+  const rl = gateRoiLines();
+  check('门禁ROI：节内容给出采集命令 + 看数值命令 + 无数据时 CLI 自带「未采集」提示（优雅降级不落空节）',
+    rl.join('\n').includes('check-loop.mjs --gate-stats') && rl.join('\n').includes('agg-gate-stats.mjs') && rl.join('\n').includes('未采集'), rl.join('\n'));
+  check('门禁ROI：节内容不含任何耗时/次数运行数值（防检查 11 每次采集报漂移的设计核心）',
+    !/\d+\s*(ms|s)\b/.test(rl.join('\n')) && !/运行\s*\d/.test(rl.join('\n')), rl.join('\n'));
+  run();
+  const dash0 = dashOf();
+  check('门禁ROI：生成物含该节 + 耗时口径显式声明「含子进程」防误读',
+    dash0.includes('## 门禁 ROI') && dash0.includes('含子进程时间'), dash0.slice(-800));
+
+  // 采集数据从无到有 → DASHBOARD 必须仍一致：这是本节设计的核心钉子
+  const cacheRel = path.join(root, '.agents', 'cache', 'gate-stats.jsonl');
+  fs.mkdirSync(path.dirname(cacheRel), { recursive: true });
+  fs.writeFileSync(cacheRel, JSON.stringify({ ts: '2026-10-08T00:00:00Z', segs: [{ id: '8', warns: 3, ms: 11809 }], totalMs: 11809 }) + '\n');
+  check('门禁ROI：采集数据「从无到有」后 --check 仍 exit 0', run('--check').status === 0, `status=${run('--check').status}`);
+  fs.appendFileSync(cacheRel, JSON.stringify({ ts: '2026-10-08T01:00:00Z', segs: [{ id: '8', warns: 9, ms: 99 }], totalMs: 99 }) + '\n');
+  check('门禁ROI：采集数据「再变一次」后 --check 仍 exit 0 且盘面字节恒等（零新增漂移源）',
+    run('--check').status === 0 && dashOf() === dash0, `status=${run('--check').status}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

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

@@ -124,7 +124,7 @@ const run = (root, args = []) => spawnSync(process.execPath, [GEN, ...args], { c
     '状态: draft\n级别: L1\n日期: 2026-09-22\n模块: pipeline',
     'workflow-doc-retrieval',
   ), 'utf8');
-  const r = run(root);
+  run(root);
   const idx = fs.readFileSync(path.join(root, 'workflow', 'INDEX.md'), 'utf8');
   check('场景 5：kebab-case H1 完整保留（未被截成末段）', idx.includes('| workflow-doc-retrieval |') && !idx.includes('| retrieval |'), idx.split('\n').filter((l) => l.includes('retrieval')).join('\n'));
   check('场景 5：em-dash 前缀仍正常剥离', idx.includes('| 在跑的需求甲 |'), '');

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

@@ -48,7 +48,7 @@ const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
 // **不能用固定上溯级数**（2026-09-28 修正）：本脚本在两处运行、深度不同——
 //   包源 `templates/_agents/scripts/` → 上溯 3 级到仓库根
 //   装户 `.agents/scripts/`          → 上溯 2 级到安装根
-// 首版硬编码 3 级，故**在每个装户安装里都解析不到枚举文件**（报错路径 `<install>/..​/.agents/…`）。
+// 首版硬编码 3 级，故**在每个装户安装里都解析不到枚举文件**（报错路径 `<install>/../.agents/…`）。
 // 实测暴露路径：CI 新增「shipped 套件」步骤后，`.agents/scripts/gen-workflow-metrics.test.mjs`
 // 场景 1 即 exit 1（workflow-enums 单源文件不可读），而包源侧同字节跑出全绿。
 // 改为**逐级上溯探测**：找到含 `.agents/workflow-enums.txt` 的那一级即用，找不到则回退标准位置让

package/templates/_agents/scripts/kb-search.mjs

@@ -39,7 +39,6 @@ const USAGE = `用法: node .agents/scripts/kb-search.mjs [选项] <词1> [词2
 
 const args = process.argv.slice(2);
 let scope = '';
-let scopeExplicit = false;
 let typeFilter = null;
 let moduleFilter = '';
 let statusFilter = 'all';
@@ -53,7 +52,7 @@ let rebuild = false;
 const words = [];
 for (let i = 0; i < args.length; i++) {
   const a = args[i];
-  if (a === '--scope') { scope = args[++i] || ''; scopeExplicit = true; }
+  if (a === '--scope') { scope = args[++i] || ''; }
   else if (a === '--type') typeFilter = (args[++i] || '').split(',').map((s) => s.trim()).filter(Boolean);
   else if (a === '--module') moduleFilter = args[++i] || '';
   else if (a === '--status') statusFilter = args[++i] || '';

package/templates/_agents/scripts/kb-search.test.mjs

@@ -109,7 +109,7 @@ const files = (out) => (out.match(/^📄 (workflow\/\S+)/gm) || []).map((l) => l
 // ---- 场景 5：增量失效——warm 后改 1 个源文件，仅该文件重解析且输出与纯扫一致 ----
 {
   const root = mkfix();
-  const base = run(root, ['编码模板']);
+  run(root, ['编码模板']);
   const planP = path.join(root, 'workflow', 'plans', '2026-09-20-ccc.md');
   fs.appendFileSync(planP, '\n## 影响面\n- 新标记NEWWORD：编码模板修订\n', 'utf8');
   const after = run(root, ['编码模板', 'NEWWORD']);

package/templates/_agents/scripts/pipeline-run-docs.mjs

@@ -0,0 +1,76 @@
+// pipeline-run-docs.mjs — 文档纯函数层（2026-10-08 engine-quality-batch，L2 自 pipeline-run.mjs 拆出）
+// fmGet / placeholdersIn / sectionBody / validateDraftContent / closeoutComplete / summarizeDoc——
+// 零 IO、零 process 依赖、单向被 pipeline-run.mjs（CLI 编排层）消费；判据注释随函数原样迁入。
+// export 面 = 原主文件具名导出（placeholdersIn/validateDraftContent/closeoutComplete）+ 层内消费三函数；
+// 主文件经 re-export 保持对外导出面不变（workflow-board-server 等消费方零改动）。
+export function fmGet(text, key) {
+  const m = text.split(/\r?\n/).find((l) => l.startsWith(`${key}:`));
+  return m ? m.slice(key.length + 1).trim() : null;
+}
+
+// 占位符判定（复核 P1-3 收窄，2026-10-02）：先剔除 code span（`…`）与引号串（"…"）——
+// 正文合法的命令语法占位（如 `next --delegated "<原话>"`）几乎总在 code span 内，
+// 模板实占位符（如 <为什么做；写明需求来源…>）从不包 code span；再匹配剩余裸尖括号。
+export function placeholdersIn(text) {
+  const stripped = String(text)
+    .replace(/^```[\s\S]*?^```$/gm, '') // 复核 P2-B：跨行 code fence 整块剔除（围栏内命令示例占位不属模板占位符）
+    .replace(/`[^`\n]*`/g, '')
+    .replace(/"[^"\n]*"/g, '');
+  const hits = [];
+  for (const re of [/<[^>\n]{1,60}>/g, /YYYY-MM-DD 用户/g]) {
+    let m; while ((m = re.exec(stripped))) hits.push(m[0]);
+  }
+  return [...new Set(hits)].slice(0, 5);
+}
+
+export function sectionBody(text, title) {
+  const lines = text.split(/\r?\n/);
+  const i = lines.findIndex((l) => l.trim() === `## ${title}` || l.trim() === `## ${title}（L1 微改动无实质内容可删本节，不硬填）` || l.trim().startsWith(`## ${title}`));
+  if (i < 0) return null;
+  const body = [];
+  for (let j = i + 1; j < lines.length; j++) {
+    if (/^##\s/.test(lines[j])) break;
+    body.push(lines[j]);
+  }
+  return body.join('\n').trim();
+}
+
+export function validateDraftContent(text, kind, level) {
+  const problems = [];
+  if (!text) return ['文件不存在或为空'];
+  const state = fmGet(text, '状态');
+  if (!state) problems.push('frontmatter 缺「状态:」行');
+  if (kind !== 'incident' && !fmGet(text, '级别')) problems.push('frontmatter 缺「级别:」行');
+  const ph = placeholdersIn(text);
+  if (ph.length) problems.push(`模板占位符残留：${ph.join('、')}`);
+  const required = {
+    intent: level === 'L1' ? ['背景与问题', '目标', '验收标准'] : ['背景与问题', '历史教训/防复发', '目标', '非目标', '约束', '验收标准'],
+    spec: ['功能行为', '数据流', '系统改动', '约束遵守映射'],
+    plan: level === 'L1' ? ['改动方案', '约束与风险', '验证计划'] : ['改动方案', '任务拆解', '执行顺序', '验证计划'],
+    incident: ['时间线', '根因', '复盘三件套'],
+  }[kind] || [];
+  for (const sec of required) {
+    const b = sectionBody(text, sec);
+    if (b === null) { if (!(level === 'L1' && ['非目标', '约束', '任务拆解', '执行顺序'].includes(sec))) problems.push(`缺节：## ${sec}`); }
+    else if (!b) problems.push(`节为空：## ${sec}`);
+  }
+  return problems;
+}
+
+export function closeoutComplete(text) {
+  const body = sectionBody(text, '验收标准');
+  if (body === null) return { ok: false, problems: ['缺「## 验收标准」节'] };
+  const lines = body.split(/\r?\n/);
+  const open = lines.filter((l) => /^\s*-\s\[\s\]\s/.test(l));
+  // 复核 P2-6：证据冒号后须直接跟内容（非空白、非收括号）——「（证据：）」空值不算过
+  const checkedNoEv = lines.filter((l) => /^\s*-\s\[x\]\s/.test(l) && !/证据[:：][^）\s]/.test(l));
+  const problems = [];
+  if (open.length) problems.push(`未勾验收 ${open.length} 条`);
+  if (checkedNoEv.length) problems.push(`已勾缺证据 ${checkedNoEv.length} 条`);
+  return { ok: problems.length === 0, problems };
+}
+
+export function summarizeDoc(text) {
+  const body = text.split(/\r?\n/).filter((l) => l.trim() && !l.startsWith('---') && !/^状态:|^级别:|^日期:|^模块:|^备注:|^risk_level:/.test(l));
+  return body.slice(0, 3).join(' / ').slice(0, 200);
+}