agentic-flow-kit 1.3.0 → 1.4.0

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

@@ -0,0 +1,167 @@
+// check-hygiene.mjs — check-loop 卫生类检查模块（2026-10-08 selfmeasure-and-modularize，L2）
+// 承载 check-loop.mjs 的检查 2 / 9 / 11 / 12 / 13（拆分先例 = check-metric-claims.mjs 承载检查 16）：
+//   2. 模板字段占位符残留            [warning]
+//   9. 文件名英文 kebab-case          [warning]
+//  11. 生成物漂移（INDEX + DASHBOARD）[warning]  ← 本次扩 DASHBOARD（原仅 INDEX）
+//  12. frontmatter「模块:」合法性      [warning]
+//  13. 常驻面体积预算                 [warning]
+//
+// 为什么是这五个：它们无跨检查共享状态——判据只依赖 ctx 里既有的 helper（docFiles / linesOf / fmGet /
+// isTracked / readdirOrNull）与 policy，不消费其他检查的中间产物。耦合高的检查 1/5（共享文档循环）、
+// 8（证据核验）、15（指纹对账）留后续批次，拆它们需先解耦，不与本批混（2026-10-08-checkloop-importable
+// 教训：1600+ 行变换与行为修复混批 diff 巨大且不可审）。
+//
+// **判定零复刻铁律**：ctx 里每个 helper 都从 check-loop.mjs 原样传入，模块内**不得**重新实现
+// docFiles / fmGet / linesOf / isTracked——它们各自承载不可漂移的语义（docFiles 的「仓库模式只扫
+// tracked(HEAD)」、fmGet 的 frontmatter 受限子集、linesOf 的读异常响亮出账 + 按空文档降级）。复刻即造口径分叉。
+//
+// 输出契约：本模块**只返回文案数组**，不打印、不 exit、不改 ctx。调用方 `warnings.push(...ret)`——
+// check-loop 在 `audit:false`（init 新装）下把 `warnings.push` 替换为 no-op，卫生项因此不出账（硬规则语义保持）。
+// 检查 11 的生成器 `--check` 口径同样不复刻（调子进程，判据单源在生成器内）。
+//
+// 测试：node templates/_agents/scripts/check-hygiene.test.mjs（fixture root 注入，不触真实 workflow/）
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { gateSeg, finishSegs, makeCollector, appendSegs } from './gate-seg.mjs';
+
+// 门禁 ROI 插桩（2026-10-08 gate-roi-metrics）：本模块承载的检查 2/9/11/12/13 同样需要计入门禁成本
+// 统计——尤其检查 11（调两个生成器 --check 的 spawn 子进程）与检查 13（调 sh rule-budget.sh）是耗时大户，
+// 不插桩就等于把最贵的两段排除在度量之外。collector 由 check-loop 传入（它持有全局 warnings/blockers），
+// 未传时跳过插桩（纯函数直测场景零副作用）。判据单源见 gate-seg.mjs。
+
+export function runCheckHygiene(ctx) {
+  const { root: ROOT, WF, DOC_DIRS, docFiles, linesOf, fmGet, isTracked, readdirOrNull, kitPolicy } = ctx;
+  const warnings = [];
+  // ⚠️ 插桩记在**本模块的局部数组**上，不是 ctx.gateStats 的全局数组——本模块产出的是局部 warnings，
+  // 由 check-loop 在返回后才 spread 进全局；执行期间全局长度不动，直接共用游标会导致确定的错账
+  // （本模块 5 段恒记 0 命中，全部增量被误记到模块之后的第一个段即检查 3 头上；实测已抓到该症状）。
+  // 末尾用 appendSegs 把结算好的段按序并入全局收集器——它会先结算模块前的那一段（如检查 1）再清游标。
+  const localStats = makeCollector(warnings, []); // 本模块只产 warnings，不产 blockers
+  const markGate = (id, label) => { if (ctx.gateStats) gateSeg(localStats, id, label); };
+
+  // --- 2. 模板字段占位符残留 [warning]（排除运行时文件名格式与协议样板，口径沿 sh 版）---
+  markGate('2', '模板字段占位符残留');
+  {
+    const phRe = /YYYY-MM-DD|<主题>|<日期 主题>|L0 \/ L1 \/ L2 \/ L3|draft \/ approved \/ done|open \/ fixed \/ closed/;
+    const boilerRe = /\.\.\/specs\/[A-Za-z0-9-]*\.md|写明如何满足|防复发验证|_YYYY-MM-DD\.|format\('YYYY-MM-DD'\)|value-format="YYYY-MM-DD"|确认结果：approved（YYYY-MM-DD 用户对话内确认）；done（YYYY-MM-DD 关单，随入口文档置终态）/;
+    // plan 确认节样板豁免（2026-10-03 plan-confirm-boiler）：plan 模板「确认与复核」节自带
+    // 「确认结果：approved（YYYY-MM-DD 用户对话内确认）；done（YYYY-MM-DD 关单，随入口文档置终态）」
+    // 样板句，未回填不等于漏填占位（确认由 confirm-doc 机器兜底）——精确豁免整句，真实占位（如
+    // `日期: YYYY-MM-DD`）照拦。
+    // 命名约定豁免：`<主题>` 与 `.md` 同行 = 在描述文件命名规则（如 `.agents/workflows/<主题>.md`、
+    //   「复制本模板为 YYYY-MM-DD-<主题>.md」），非未填占位符；真未填的占位（标题 `# INTENT — <主题>`、
+    //   `日期: YYYY-MM-DD`）不含 .md，仍照拦（2026-09-25-wf-runtime incident 记录的误报口径）
+    const isNamingConv = (line) => line.includes('<主题>') && /\.md/.test(line);
+    // 样例引用豁免（2026-10-02 caliber-convergence 假阳性消除，先例=检查 18 行尾归一）：命中位于行内代码
+    // （反引号包裹）或围栏代码块内 = 引用样例而非未填占位符，不报；正文裸占位符照报——真占位符均为
+    // 裸文本（模板正文无反引号包裹），检测面不缩。
+    // 日期显示格式豁免（2026-10-06 check2-datetime-literal-exempt）：`YYYY-MM-DD HH:mm(:ss)` 是功能
+    // 自实现的显示格式描述（文档叙述「匹配时间列显示为 YYYY-MM-DD HH:mm」属常态——cancel-export
+    // intent/plan 实证 2 条 advisory、2026-10-06 loop-audit intent 现场复现），非未填占位——行内剔除
+    // 后再判；真占位（`日期: YYYY-MM-DD`，无时间粒度后缀）不含该形态仍拦。只豁免实证形态，变体（斜杠日期
+    // /十二进制等）出现假阳性再扩。
+    const stripSamples = (lines) => {
+      let inFence = false;
+      return lines.map((line) => {
+        if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; return ''; }
+        if (inFence) return '';
+        return line.replace(/`[^`]*`/g, '').replace(/YYYY-MM-DD\s+HH:mm(:ss)?/g, '');
+      });
+    };
+    const groups = new Map(); // file -> [ "行号:内容" ]（首现序）
+    for (const sub of DOC_DIRS) {
+      for (const f of docFiles(sub)) {
+        const lines = linesOf(f) || [];
+        const hits = [];
+        stripSamples(lines).forEach((line, i) => {
+          if (phRe.test(line) && !boilerRe.test(line) && !isNamingConv(line)) hits.push(`${i + 1}:${lines[i]}`);
+        });
+        if (hits.length) groups.set(f, hits);
+      }
+    }
+    for (const [f, hits] of groups) {
+      warnings.push(`- [WARN 模板未填] ${path.relative(ROOT, f).split(path.sep).join('/')} 含模板占位符:\n${hits.join('\n')}`);
+    }
+  }
+
+  // --- 9. 文件名英文 kebab-case [warning] ---
+  markGate('9', '文件名 kebab-case');
+  for (const sub of DOC_DIRS) {
+    const dir = path.join(ROOT, WF, sub);
+    for (const f of readdirOrNull(dir) || []) {
+      if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
+      const abs = path.join(dir, f);
+      if (!isTracked(abs)) continue;
+      if (!/^[\x20-\x7e]*$/.test(f)) {
+        warnings.push(`- [WARN 文件名非英文] 文件名含非 ASCII 字符,应为英文 kebab-case:${WF}/${sub}/${f}`);
+      }
+    }
+  }
+
+  // --- 11. 生成物漂移 [warning]（调生成器 --check，口径单一不复刻渲染）---
+  markGate('11', '生成物漂移（INDEX+DASHBOARD）');
+  // ⚠️ 位置：本段须排在 12/13 之前——check-loop 输出按 warnings 插入序，行序是稳定输出契约
+  // （pre-push / pre-commit 消费者 + doctor 按 WARN 行计数）；原序为 2 → 9 → 11 → 12 → 13，勿调换。
+  // 两个生成物各自独立出账：漂移来源不同、修复命令不同，混成一条会让装户猜该跑哪个。
+  // 装户跳过语义（防常驻噪声，audit-gate-hardening P3 教训）：
+  //   ① 生成器脚本不存在（旧装副本）→ 跳过；
+  //   ② DASHBOARD.md 不存在（从未生成过）→ 跳过——**新装用户不得因未生成过看板而每次 push 吃 WARN**；
+  //      （INDEX.md 不设此前置：init 必落该文件，不存在本身即异常）
+  for (const [label, genName, docRel] of [
+    ['索引漂移', 'gen-workflow-index.mjs', 'workflow/INDEX.md'],
+    ['仪表盘漂移', 'gen-workflow-dashboard.mjs', 'workflow/DASHBOARD.md'],
+  ]) {
+    const gen = path.join(ROOT, '.agents', 'scripts', genName);
+    if (!fs.existsSync(gen)) continue;
+    if (label === '仪表盘漂移' && !fs.existsSync(path.join(ROOT, docRel))) continue;
+    const r = spawnSync(process.execPath, [gen, '--check'], { cwd: ROOT, encoding: 'utf8' });
+    if (r.status !== 0) {
+      const first = `${r.stdout || ''}${r.stderr || ''}`.split('\n')[0];
+      warnings.push(`- [WARN ${label}] ${docRel} 与当前事实不一致——跑 node .agents/scripts/${genName} 重新生成（${first}）`);
+    }
+  }
+
+  // --- 12. frontmatter「模块:」合法性 [warning]（词表单源；缺字段只对 2026-09-22 起新建提示）---
+  markGate('12', '模块枚举合法性');
+  {
+    const modsFile = path.join(ROOT, '.agents', 'workflow-modules.txt');
+    if (fs.existsSync(modsFile)) {
+      const mods = linesOf(modsFile).filter((l) => l.trim() && !l.startsWith('#')).map((l) => l.trim());
+      const vocab = new Set(mods);
+      for (const sub of ['intents', 'specs', 'plans', 'incidents']) {
+        for (const doc of docFiles(sub)) {
+          const base = path.basename(doc);
+          const mod = fmGet(doc, '模块');
+          let d = fmGet(doc, '日期') || fmGet(doc, '发现');
+          if (!d) d = /^\d{4}-\d{2}-\d{2}$/.test(base.slice(0, 10)) ? base.slice(0, 10) : '';
+          if (mod) {
+            if (!vocab.has(mod)) warnings.push(`- [WARN 模块元数据] ${base}「模块: ${mod}」不在词表(见 .agents/workflow-modules.txt)`);
+          } else if (/^\d{4}-\d{2}-\d{2}$/.test(d) && d >= kitPolicy.moduleSince) {
+            warnings.push(`- [WARN 模块元数据] ${base} 缺「模块:」字段(${kitPolicy.moduleSince} 起新建文档必填)`);
+          }
+        }
+      }
+    }
+  }
+
+  // --- 13. 常驻面体积预算 [warning]（判定单源 rule-budget.sh；无 sh 环境静默跳过——advisory，pre-commit 硬拦兜底）---
+  markGate('13', '常驻面体积预算');
+  {
+    const rb = path.join(ROOT, '.agents', 'scripts', 'rule-budget.sh');
+    const budgets = path.join(ROOT, '.agents', 'rule-budgets.txt');
+    if (fs.existsSync(rb) && fs.existsSync(budgets)) {
+      const r = spawnSync('sh', [rb, '--all'], { cwd: ROOT, encoding: 'utf8' });
+      if (!r.error && r.status !== 0) {
+        const head = `${r.stdout || ''}${r.stderr || ''}`.split('\n').slice(0, 5).map((l) => '    ' + l).join('\n');
+        warnings.push(`- [WARN 常驻面超限] 常驻面体积超预算(先删除或下沉被取代条目再增——一进一出):\n${head}`);
+      }
+    }
+  }
+
+  // 并入全局收集器（仅显式插桩时）：把本模块 5 段按序插到「模块前的那一段」之后，
+  // 游标由 appendSegs 清空 → check-loop 随后的 markGate('3', …) 从零起算，Δ 天然正确。
+  if (ctx.gateStats) appendSegs(ctx.gateStats, finishSegs(localStats));
+
+  return warnings;
+}

package/templates/_agents/scripts/check-hygiene.test.mjs

@@ -0,0 +1,182 @@
+// check-hygiene.test.mjs — 卫生类检查模块测试（2026-10-08 selfmeasure-and-modularize，L2）
+// 被测：templates/_agents/scripts/check-hygiene.mjs 的 runCheckHygiene（检查 2 / 9 / 11 / 12 / 13）。
+// 端到端行为回归网仍是 check-loop.test.mjs（219 断言，spawn 真 check-loop）——本套件补的是**模块层直测**：
+//   ctx 缺项降级、装户跳过分支、生成物双告警、以及「模块内顺序 = 原 2→9→11→12→13」这条输出契约。
+// fixture：mkdtemp 临时根（workflow/{intents,specs,plans,incidents} + .agents/），**不触真实仓库 workflow/**。
+// 用法：node templates/_agents/scripts/check-hygiene.test.mjs
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const { runCheckHygiene } = await import(pathToFileURL(path.join(SCRIPT_DIR, 'check-hygiene.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}` : ''}`); }
+};
+
+// ctx 组装：复刻 check-loop.mjs 的 helper 口径（tracked 恒真 = fixture 模式、frontmatter 受限子集），
+// 以免测试用自己的一套语义掩盖模块与主文件的漂移。
+function makeCtx(root, overrides = {}) {
+  const WF = 'workflow';
+  const DOC_DIRS = ['intents', 'specs', 'plans', 'incidents'];
+  const fileLinesCache = new Map();
+  const linesOf = (file) => {
+    if (!fileLinesCache.has(file)) {
+      let lines = null;
+      try { lines = fs.readFileSync(file, 'utf8').split(/\r?\n/); } catch { lines = null; }
+      fileLinesCache.set(file, lines);
+    }
+    return fileLinesCache.get(file);
+  };
+  const fmGet = (file, key) => {
+    const lines = linesOf(file);
+    if (!lines) return '';
+    const isDelim = (l) => /^---\s*$/.test(l);
+    if (!isDelim(lines[0] || '')) return '';
+    for (let i = 1; i < lines.length; i++) {
+      if (isDelim(lines[i])) return '';
+      if (lines[i].startsWith(key + ':')) return lines[i].slice(key.length + 1).trim();
+    }
+    return '';
+  };
+  const isTracked = () => true; // fixture 模式：check-loop 中 CHECK_LOOP_ROOT 注入时恒真
+  const docFiles = (sub) => {
+    const dir = path.join(root, WF, sub);
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.md') && /^\d/.test(f))
+      .map((f) => path.join(dir, f)).filter(isTracked).sort();
+  };
+  const readdirOrNull = (dir) => { try { return fs.readdirSync(dir); } catch { return null; } };
+  const kitPolicy = { moduleSince: '2026-09-22', ...(overrides.kitPolicy || {}) };
+  return { root, WF, DOC_DIRS, docFiles, linesOf, fmGet, isTracked, readdirOrNull, kitPolicy, ...overrides };
+}
+
+const W = (root, rel, content) => {
+  fs.mkdirSync(path.join(root, path.dirname(rel)), { recursive: true });
+  fs.writeFileSync(path.join(root, rel), content, 'utf8');
+};
+const DOC = (fm, body = '# T\n') => `---\n${fm}\n---\n${body}`;
+
+// ---- 检查 2：占位符残留 ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-hyg2-'));
+  W(root, 'workflow/intents/2026-10-01-ph.md', DOC('状态: done\n级别: L1\n日期: 2026-10-01\n模块: pipeline', '# I\n日期: YYYY-MM-DD\n'));
+  W(root, 'workflow/intents/2026-10-01-ok.md', DOC('状态: done\n级别: L1\n日期: 2026-10-01\n模块: pipeline', '# I\n没有占位符\n'));
+  W(root, 'workflow/intents/2026-10-01-fence.md', DOC('状态: done\n级别: L1\n日期: 2026-10-01\n模块: pipeline', '# I\n```\nYYYY-MM-DD\n```\n'));
+  const r = runCheckHygiene(makeCtx(root));
+  const ph = r.filter((w) => w.includes('[WARN 模板未填]'));
+  check('检查 2：裸占位符出账 + 围栏代码块内豁免（仅 1 件）',
+    ph.length === 1 && ph[0].includes('2026-10-01-ph.md'), JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 检查 9：文件名 kebab（检查 9 走 readdirOrNull，不走 docFiles 的 /^\d/ 过滤）----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-hyg9-'));
+  W(root, 'workflow/intents/2026-10-01-中文名.md', DOC('状态: done\n级别: L1\n日期: 2026-10-01\n模块: pipeline'));
+  const r = runCheckHygiene(makeCtx(root));
+  check('检查 9：非 ASCII 文件名出账', r.some((w) => w.includes('[WARN 文件名非英文]') && w.includes('中文名.md')), JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 检查 11：双生成物 + 装户跳过 ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-hyg11-'));
+  // 装户形态：无生成器脚本 → 检查 11 整体跳过（不报）
+  let r = runCheckHygiene(makeCtx(root));
+  check('检查 11：生成器脚本不存在（旧装副本）→ 跳过不报',
+    !r.some((w) => w.includes('漂移]')), JSON.stringify(r));
+  // 放一个恒红的假生成器（--check 必 exit 1），覆盖双告警
+  W(root, '.agents/scripts/gen-workflow-index.mjs', 'process.exit(1);\n');
+  W(root, '.agents/scripts/gen-workflow-dashboard.mjs', 'process.exit(1);\n');
+  W(root, 'workflow/INDEX.md', '# stale\n');
+  W(root, 'workflow/DASHBOARD.md', '# stale\n'); // 双告警场景须盘面在位——否则命中装户跳过分支
+  r = runCheckHygiene(makeCtx(root));
+  check('检查 11：INDEX + DASHBOARD 各自独立出账且指名修复命令',
+    r.some((w) => w.includes('[WARN 索引漂移]') && w.includes('gen-workflow-index.mjs'))
+    && r.some((w) => w.includes('[WARN 仪表盘漂移]') && w.includes('gen-workflow-dashboard.mjs')), JSON.stringify(r));
+  // DASHBOARD.md 不存在 → 只剩 INDEX 一条（装户未生成过看板不得常红）
+  fs.rmSync(path.join(root, 'workflow/DASHBOARD.md'), { force: true });
+  r = runCheckHygiene(makeCtx(root));
+  check('检查 11：DASHBOARD.md 缺失 → 跳过（装户未生成过看板不常红）',
+    !r.some((w) => w.includes('仪表盘漂移]')) && r.some((w) => w.includes('索引漂移]')), JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 检查 12：模块枚举 + 词表缺失降级 ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-hyg12-'));
+  W(root, '.agents/workflow-modules.txt', '# 词表\npipeline\nwiki\n');
+  W(root, 'workflow/intents/2026-10-01-bad.md', DOC('状态: done\n级别: L1\n日期: 2026-10-01\n模块: 不存在的模块'));
+  W(root, 'workflow/intents/2026-10-01-missing.md', DOC('状态: done\n级别: L1\n日期: 2026-10-01'));
+  W(root, 'workflow/intents/2026-09-01-old.md', DOC('状态: done\n级别: L1\n日期: 2026-09-01')); // 早于 moduleSince → 存量豁免
+  let r = runCheckHygiene(makeCtx(root));
+  check('检查 12：非法模块出账 + 新建缺字段出账 + 存量豁免',
+    r.some((w) => w.includes('不在词表')) && r.some((w) => w.includes('missing.md 缺「模块:」字段'))
+    && !r.some((w) => w.includes('old.md')), JSON.stringify(r));
+  fs.rmSync(path.join(root, '.agents/workflow-modules.txt'));
+  r = runCheckHygiene(makeCtx(root));
+  check('检查 12：词表文件缺失 → 静默跳过（装户无感）', !r.some((w) => w.includes('模块元数据')), JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 输出顺序契约：块内须保持 2 → 9 → 11 → 12 → 13 ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-hyg-order-'));
+  W(root, 'workflow/intents/2026-10-01-ph.md', DOC('状态: done\n级别: L1\n日期: 2026-10-01\n模块: 非法模块', '# I\nYYYY-MM-DD\n'));
+  W(root, 'workflow/intents/2026-10-01-中文名.md', DOC('状态: done\n级别: L1\n日期: 2026-10-01\n模块: pipeline'));
+  W(root, '.agents/scripts/gen-workflow-index.mjs', 'process.exit(1);\n');
+  W(root, '.agents/scripts/gen-workflow-dashboard.mjs', 'process.exit(1);\n');
+  W(root, '.agents/workflow-modules.txt', '# 词表\npipeline\n'); // 词表须在位，否则检查 12 整段跳过
+  W(root, 'workflow/INDEX.md', '# stale\n');
+  W(root, 'workflow/DASHBOARD.md', '# stale\n');
+  const r = runCheckHygiene(makeCtx(root));
+  const tags = r.map((w) => (w.includes('模板未填') ? '2' : w.includes('文件名非英文') ? '9'
+    : w.includes('索引漂移') ? '11a' : w.includes('仪表盘漂移') ? '11b' : w.includes('模块元数据') ? '12' : '13'));
+  check('输出顺序：块内 2 → 9 → 11 → 12 保持（行序属稳定输出契约）',
+    tags.join(',') === '2,9,11a,11b,12', tags.join(','));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 检查 20 覆盖：本模块须被 npm test 的 glob 发现 ----
+{
+  const found = fs.existsSync(path.join(SCRIPT_DIR, 'check-hygiene.test.mjs'));
+  check('检查 20：本套件与被测模块同名兄弟（否则检查 20 出账）', found);
+  const r = spawnSync(process.execPath, ['--check', path.join(SCRIPT_DIR, 'check-hygiene.mjs')], { encoding: 'utf8' });
+  check('被测模块语法有效', r.status === 0, r.stderr || '');
+}
+
+// ---- 门禁 ROI 段归属（2026-10-08 gate-roi-metrics，实仓抓到的错账根因）----
+// 症状：本模块的 warnings 是**局部数组**（check-loop 事后才 spread 进全局），若段增量记在全收集器上，
+//   本模块 5 段恒记 0 命中、且全部增量被误记到模块之后的第一个段（检查 3）。修复 = 局部收集器 + appendSegs。
+// 本组断言在**模块层**钉死归属：检查 2 与检查 9 各产 1 条，必须各归各的段，不得漂到别的段上。
+{
+  const { makeCollector, finishSegs } = await import(pathToFileURL(path.join(SCRIPT_DIR, 'gate-seg.mjs')).href);
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-hygroi-'));
+  W(root, 'workflow/intents/2026-10-01-ph.md', DOC('状态: done\n级别: L1\n日期: 2026-10-01\n模块: pipeline', '# I\n日期: YYYY-MM-DD\n'));
+  W(root, 'workflow/intents/2026-10-01-中文名.md', DOC('状态: done\n级别: L1\n日期: 2026-10-01\n模块: pipeline'));
+  // 全局收集器挂在**空数组**上：若模块错误地用全局数组做 Δ 源，两条警告一条都不会被算进去。
+  const globalStats = makeCollector([], []);
+  const r = runCheckHygiene(makeCtx(root, { gateStats: globalStats }));
+  const segs = globalStats.segs;
+  const byId = new Map(segs.map((s) => [s.id, s.warns]));
+  const hits = r.length;
+  check('段归属：本模块 5 段全部入账（2/9/11/12/13）',
+    segs.map((s) => s.id).join(',') === '2,9,11,12,13', JSON.stringify(segs.map((s) => s.id)));
+  check('段归属：各段增量之和 == 本模块实际产出条数（无漏记无重复记）',
+    segs.reduce((a, s) => a + s.warns, 0) === hits && hits === 2, `segs=${JSON.stringify(segs)} hits=${hits}`);
+  check('段归属：检查 2 / 检查 9 各归 1 条（**不都堆到末段**——本次实抓的错账形态）',
+    byId.get('2') === 1 && byId.get('9') === 1 && byId.get('11') === 0 && byId.get('12') === 0 && byId.get('13') === 0,
+    JSON.stringify(segs));
+  check('段归属：并入后全局游标清空（check-loop 随后的 markGate 从零起算）', globalStats.current === null);
+  check('段归属：finishSegs(全局) 幂等，不产生额外伪段', finishSegs(globalStats).length === segs.length);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);