agentic-flow-kit 1.3.0 → 1.5.0

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

@@ -30,7 +30,7 @@
 //      证据可写在 [x] 行的续行（仓库通写法「（证据：…）」另起一行；全/半角冒号皆认）
 //   9. 文件名英文 kebab-case(非 ASCII 文件名=warning,2026-09-11 规则)
 //  10. 级别 vs 迁移文件一致性(L1/L2 入口文档加入提交触及迁移 SQL/Migrations=疑似判低,warning)
-//  11. workflow/INDEX.md 漂移(活跃层索引与磁盘不一致=warning,2026-09-21 检索层;调生成器 --check,口径单一)
+//  11. 生成物漂移：workflow/INDEX.md(2026-09-21 检索层) + workflow/DASHBOARD.md(2026-10-08 扩覆盖面)=warning;
 //  12. frontmatter「模块:」合法性(枚举非法 / 2026-09-22 起新建缺字段=warning;词表单源 .agents/workflow-modules.txt)
 //  13. 常驻面体积预算(超限=warning;判定单源 rule-budget.sh——经 sh 调用,
 //      无 sh 环境静默跳过:advisory 级且 pre-commit 侧在 git 钩子 sh 环境照常硬拦)
@@ -109,8 +109,6 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
 import { loadEnums } from './workflow-enums.mjs';
 import { runCheck16 } from './check-metric-claims.mjs';
 import { auditEnabled, loadKitPolicy, hasFreshVerifyLine } from './policy.mjs';
@@ -118,25 +116,31 @@ import { laneOfEntry } from './stage-gates.mjs';
 // MARK_RE：incident 留痕形态的单源（第七轮复核 N3——此前 check-loop 内联复制一份同口径字面量，
 // 两处靠注释与人工同步；改为复用 stage-gates.mjs 的导出，从结构上消除漂移可能）
 import { MARK_RE, approvedTraceHit } from './stage-gates.mjs';
+// 卫生类检查已拆出（2026-10-08 selfmeasure-and-modularize）：检查 2/9/11/12/13 迁入 check-hygiene.mjs，
+// 本文件只组装 ctx 并消费返回的文案数组（先例 = check-metric-claims.mjs 承载检查 16）。
+// 调用点位置即输出顺序位：须留在检查 10 与 12 之间以保持 warnings 行序（稳定输出契约），见该模块内注释。
+import { runCheckHygiene } from './check-hygiene.mjs';
+import { gateSeg, finishSegs, makeCollector } from './gate-seg.mjs';
 
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 // CHECK_LOOP_GIT：测试注入钩子（指向不存在/不可执行路径可稳定触发 spawn 异常）；未设置时与原行为逐字节一致（2026-10-05-gitout-fail-open）
 const GIT = process.env.CHECK_LOOP_GIT || (process.platform === 'win32' ? 'git.exe' : 'git');
 
 function takeOpts() {
   const args = process.argv.slice(2);
-  const opts = { rev: null, hardening: false };
+  const opts = { rev: null, hardening: false, gateStats: false };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--rev') {
       opts.rev = args[++i] ?? '';
       if (!opts.rev) {
-        console.error('check-loop: 用法 node check-loop.mjs [--rev <sha>] [--hardening]');
+        console.error('check-loop: 用法 node check-loop.mjs [--rev <sha>] [--hardening] [--gate-stats]');
         process.exit(1);
       }
     } else if (args[i] === '--hardening') {
       opts.hardening = true; // 加固门（2026-09-30 hybrid-governance-explore-hardening）：pre-push 对 main 目标传入
+    } else if (args[i] === '--gate-stats') {
+      opts.gateStats = true; // 门禁 ROI 落盘（2026-10-08 gate-roi-metrics）：默认路径输出逐字节不变
     } else {
-      console.error('check-loop: 用法 node check-loop.mjs [--rev <sha>] [--hardening]');
+      console.error('check-loop: 用法 node check-loop.mjs [--rev <sha>] [--hardening] [--gate-stats]');
       process.exit(1);
     }
   }
@@ -148,6 +152,29 @@ function takeOpts() {
 // 优先于 CHECK_LOOP_ROOT env 优先于 git toplevel（CLI 缺省行为逐字节不变）；返回 { exitCode, blockers, warnings }，
 // 输出打印照旧在本函数内（稳定输出契约：banner 后空行、条目 `- ` 前缀、HARD-BLOCK/WARN 两段式——消费者 .githooks/pre-push）。
 // opts.rev 的 worktree 清理挂 process.on('exit')——进程内多次调用累计监听器（测试场景 ≤3 次，可接受）。
+// ---- 门禁 ROI 插桩件已抽至 gate-seg.mjs（2026-10-08 gate-roi-metrics）----
+// 抽因：check-loop.mjs 已 import check-hygiene.mjs，后者若再 import check-loop.mjs 即循环依赖——
+// 而两者都要插桩，判据单源必须只有一处。gateSeg / finishSegs / makeCollector 见该件；
+// 本文件在每段开头调 markGate(id,label)，统计由数组长度差推出，不动任何 push 调用点。
+
+// writeGateStats：门禁 ROI 落盘（2026-10-08 gate-roi-metrics）——append 一行到
+// <root>/.agents/cache/gate-stats.jsonl（该目录已 gitignore，属运行时数据、不入 git、不进 kit.json
+// managed 台账——刻意避开 papercuts 2026-10-05 探针临时件被 sync 收编的事故面）。
+// IO 失败只出账不阻断（沿 verify.mjs 凭证落账同款容错——度量失败不该让门禁变成红灯）。
+export function writeGateStats(root, segs) {
+  try {
+    const dir = path.join(root, '.agents', 'cache');
+    fs.mkdirSync(dir, { recursive: true });
+    const total = segs.reduce((a, s) => a + s.ms, 0);
+    fs.appendFileSync(path.join(dir, 'gate-stats.jsonl'),
+      `${JSON.stringify({ ts: new Date().toISOString(), root, segs, totalMs: total })}\n`);
+    const hits = segs.filter((s) => s.warns || s.blocks).length;
+    console.error(`[gate-stats] ${segs.length} 段已记账（命中 ${hits} 段）→ .agents/cache/gate-stats.jsonl`);
+  } catch (e) {
+    console.error(`[gate-stats] ⚠️ 落盘失败（${e.code || e.message}）——不阻断门禁`);
+  }
+}
+
 export function runCheckLoop(opts = {}) {
   const REV_ARG = opts.rev ?? null;
   const HARDENING = !!opts.hardening;
@@ -293,6 +320,10 @@ export function runCheckLoop(opts = {}) {
   const DOC_DIRS = ['intents', 'specs', 'plans', 'incidents'];
   const blockers = [];
   const warnings = [];
+  // 门禁 ROI 收集器（2026-10-08 gate-roi-metrics）：引用同一对数组 + 段游标，不复制任何数据。
+  // 默认路径不打印不写盘（见 gate-seg.mjs 注释的输出契约硬约束）。
+  const gateStats = makeCollector(warnings, blockers);
+  const markGate = (id, label) => gateSeg(gateStats, id, label); // 局部别名，避免遮蔽同名导出
   // audit:false（init 新装）只保留 blockers。缺省与 audit:true 保持全量警告。
   // 硬规则：配对 / 验收勾验的阻断 / 确认留痕 / 发版草稿。卫生项走 warnings。
   const kitPolicy = loadKitPolicy(ROOT);
@@ -318,6 +349,7 @@ export function runCheckLoop(opts = {}) {
   };
 
   // --- 1. intent/spec/plan 同名配对 + 状态确认 + L3 确认三件 + 风险泳道一致性 [hard-block] ---
+  markGate('1', '意图/spec/plan 配对');
   for (const intent of docFiles('intents')) {
     const base = path.basename(intent);
     const st = fmGet(intent, '状态');
@@ -383,51 +415,17 @@ export function runCheckLoop(opts = {}) {
     }
   }
 
-  // --- 2. 模板字段占位符残留 [warning]（排除运行时文件名格式与协议样板，口径沿 sh 版）---
-  {
-    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')}`);
-    }
-  }
-
+  // --- 卫生类检查 2 / 9 / 11 / 12 / 13（2026-10-08 selfmeasure-and-modularize 拆出）---
+  // ⚠️ 调用点位置即输出顺序位：原实现分处五处，逐条顺序 2 → 9 → 11 → 12 → 13，而 warnings 按插入序输出、
+  //    行序属稳定输出契约（pre-push / pre-commit 消费者 + doctor 按 WARN 行计数）。拆成一次调用后本块统一落在
+  //    原检查 2 的位置，**块内顺序由 check-hygiene.mjs 保证**（与其内注释互引）。新增检查请按原编号插入
+  //    到正确位置，勿一律追加末尾。
+  // ctx 只传既有 helper、模块内零复刻：docFiles 的 tracked 过滤、fmGet 的 frontmatter 受限子集、
+  // linesOf 的读异常响亮出账各自承载不可漂移语义，复刻即造口径分叉。audit:false 下 warnings.push 是
+  // no-op，卫生项因此不出账（硬规则语义保持）。
+  warnings.push(...runCheckHygiene({ root: ROOT, WF, DOC_DIRS, docFiles, linesOf, fmGet, isTracked, readdirOrNull, kitPolicy, gateStats }));
   // --- 3. incidents 复盘三件套 + 状态严格枚举 + 新 intent 回路（回路断档 = hard）---
+  markGate('3', 'incidents 复盘三件套');
   for (const inc of docFiles('incidents')) {
     const name = path.basename(inc);
     const lines = linesOf(inc) || [];
@@ -472,6 +470,7 @@ export function runCheckLoop(opts = {}) {
   }
 
   // --- 4. 引用有效性 [warning]（.agents/ 路径须存在；skills 特例允许用户级 ~/.agents/skills）---
+  markGate('4', '引用有效性');
   {
     // 引用可带 {a,b,c} 花括号展开（仓库通写法 `fill-{intent,spec,plan}.mjs`）或 `*` 通配（`fill-*.mjs`）——
     // 花括号展开逐路查存在，任一路存在即有效；`*` 按目录枚举 glob 匹配，命中即有效；全不中才算断档
@@ -535,6 +534,7 @@ export function runCheckLoop(opts = {}) {
   }
 
   // --- 5. 子智能体角色契约 + 宿主 Adapter 一致性 + 旧委派残留 + 钉死模型 [warning] ---
+  markGate('5', '角色契约与宿主 Adapter');
   {
     const cmdFiles = () => (readdirOrNull(path.join(ROOT, '.agents', 'commands')) || [])
       .filter((f) => f.endsWith('.md')).map((f) => `.agents/commands/${f}`);
@@ -593,6 +593,7 @@ export function runCheckLoop(opts = {}) {
   }
 
   // --- 6. 阶段索引同步 [warning] ---
+  markGate('6', '阶段索引同步');
   for (const cmd of ['plan', 'design', 'build', 'test', 'deploy', 'maintain', 'review']) {
     for (const doc of ['AGENTS.md', '.agents/commands/new-task.md']) {
       // existsSync 守卫（2026-10-06-check19-entry-enoent 同类）：两文件可合法缺失（下方 text 判空本就
@@ -714,7 +715,7 @@ export function runCheckLoop(opts = {}) {
       if (/^##\s+(改动面|任务拆解|改动方案)/.test(line)) { inDeclaredSec = true; continue; }
       if (inDeclaredSec && /^##\s+/.test(line)) { inDeclaredSec = false; continue; }
       if (inDeclaredSec) {
-        const fileMatch = line.match(/([a-zA-Z0-9._\/-]+\.[a-zA-Z0-9]+)/);
+        const fileMatch = line.match(/([a-zA-Z0-9._/-]+\.[a-zA-Z0-9]+)/);
         if (fileMatch) declaredFiles.push(fileMatch[1]);
       }
     }
@@ -744,6 +745,7 @@ export function runCheckLoop(opts = {}) {
   }
 
   // --- 8. intent 验收标准对账（done 须逐条勾验并补证据；新建 hard，存量聚合 warning）---
+  markGate('8', '验收标准对账');
   // 生效日锚 2026-09-28 改「git 首次加入日期」（此前取文件名前 10 字符——命名规范强制的字段、
   // 写早零成本，见 incidents/2026-09-28-check8-git-anchor）。非 git → 不可判定 → 走存量口径（不误报 hard）。
   {
@@ -752,15 +754,55 @@ export function runCheckLoop(opts = {}) {
     // 测试绿凭证状态（2026-10-07 verify-evidence）：台账读一次循环外缓存；policy 缺 verifySince
     //（v1-v4）→ ctxBase null → 对账整体跳过（向后兼容）
     const verifySinceOf = kitPolicy.verifySince;
-    const verifyFresh = (() => {
+    // 台账内容循环外读一次并缓存（doc 过滤是纯内存行匹配，不新增子进程——门禁成本零增加）。
+    const verifyLines = (() => {
       try {
         const vp = path.join(ROOT, '.agents', 'verifications.jsonl');
-        return fs.existsSync(vp) ? hasFreshVerifyLine(fs.readFileSync(vp, 'utf8').split(/\r?\n/)) : false;
-      } catch { return false; }
+        return fs.existsSync(vp) ? fs.readFileSync(vp, 'utf8').split(/\r?\n/) : null;
+      } catch { return null; }
     })();
+    // 全局绿行（v5 语义）：仅供 v1-v5 装户走原路径，本仓 v6+ 不再消费它。
+    const verifyFreshGlobal = verifyLines ? hasFreshVerifyLine(verifyLines) : false;
+    // 2026-10-08 verify-doc-binding：v6+（verifyDocSince）按本 doc 精确匹配；缺键维持全局布尔。
+    const verifyDocBound = typeof kitPolicy.verifyDocSince === 'string';
+    // 2026-10-09 verifydoc-anchor：v6 精确匹配的**追溯边界**——只对「确认门 done ts ≥ verifyDocSince」的单生效。
+    // 背景（用户 2026-10-09 拍板 D）：4 单（verify-evidence / workflow-dashboard / selfmeasure / gate-roi-metrics）
+    // 的 done ts 均 < v6 上线日（2026-10-08 17:37），它们关单时既无 --doc 机制、也无从补证——被精确匹配追责
+    // 会产 9 条不可消退 advisory（补跑=自证，回溯不了关单当时全绿，与门禁本意相悖）。退回全局布尔 = v5 语义
+    // （不误报、不伪造），与检查 15/18 生效日锚同构。done ts 台账读一次循环外缓存，零新增子进程。
+    const verifyDocSinceTs = verifyDocBound ? kitPolicy.verifyDocSince : null;
+    const doneTsOf = (() => {
+      const map = new Map();
+      try {
+        const lp = path.join(ROOT, '.agents', 'confirmations.jsonl');
+        if (fs.existsSync(lp)) {
+          for (const line of fs.readFileSync(lp, 'utf8').split(/\r?\n/)) {
+            if (!line.trim()) continue;
+            try {
+              const e = JSON.parse(line);
+              // append-only 取末次 done 跳转（同一 doc 多次 done 取最后一条 ts）
+              if (e && e.doc && ['done', 'closed'].includes(e.stage)) map.set(e.doc, e.ts || '');
+            } catch { /* 坏行跳过（同检查 15 口径） */ }
+          }
+        }
+      } catch { /* 台账不可读 → 无锚 → 全走全局布尔（fail-open，不误报 hard） */ }
+      return map;
+    })();
+    // 该 doc 的确认门 done 是否落在 v6 追溯窗口内；无台账行 / 台账不可读 → false（存量豁免，退回全局布尔）
+    // 2026-10-09 verifydoc-anchor：按 ISO 时刻比较（不再是日期粒度）——机制上线当日的更早时刻 done 的单
+    // 仍在窗口外（日期粒度会把同日的早时刻误纳入，见 policy.mjs verifyDocSince 注释）。
+    const verifyDocInWindow = (rel) => {
+      if (!verifyDocSinceTs) return false;
+      const ts = doneTsOf.get(rel);
+      return !!ts && ts >= verifyDocSinceTs;
+    };
+    const verifyFreshFor = (rel) => (verifyLines
+      ? hasFreshVerifyLine(verifyLines, Date.now(), verifyDocInWindow(rel) ? rel : null)
+      : false);
     for (const intent of docFiles('intents')) {
       if (fmGet(intent, '状态') !== 'done') continue;
       const base = path.basename(intent);
+      const rel = path.relative(ROOT, intent).split(path.sep).join('/'); // 与 verify.mjs --doc 落账口径同源
       const lines = linesOf(intent) || [];
       // 节扫描：hs=有验收节；insec 至下一个二级标题；uc=未勾项；ne=勾选缺证据；ex=存量豁免声明
       //   证据可写在 [x] 行的续行（仓库通写法「（证据：…）」另起一行）——pendX 记「待证据项」，
@@ -811,12 +853,14 @@ export function runCheckLoop(opts = {}) {
         // verify 对账 ctx：intent 首次加入 git ≥ verifySince（v5 锚）才参与；不可判定 → null 走 text 豁免
         const iadd = addedDateOf(intent);
         const vctx = typeof verifySinceOf === 'string' && iadd !== '' && iadd >= verifySinceOf
-          ? { verifyRelevant: true, hasFresh: verifyFresh } : null;
+          ? { verifyRelevant: true, hasFresh: verifyDocBound ? verifyFreshFor(rel) : verifyFreshGlobal } : null;
         const results = evidenceItems.map((ev) => ({ t: verifyEvidenceTruth(ev, planBase, ROOT, vctx) }));
         const hasImplEvidence = results.some((r) => r.t.ok && (r.t.type === 'sha' || r.t.type === 'process'));
         for (const r of results) {
           if (r.t.ok && r.t.type === 'verify-missing') {
-            warnings.push(`- [WARN 测试绿缺凭证] ${base} 验收证据声明「测试绿」但 24h 内无 verify 凭证（verifications.jsonl）——跑 node .agents/scripts/verify.mjs 后重跑（advisory，灰度第一档）`);
+            // ⚠️ 文案锚点硬约束（既有 check-loop.test.mjs:2743 锚定「测试绿缺凭证」四字连续，零改动前提）：
+            // doc 与修复命令只能追加在整句之后，不得插进这四个字中间。
+            warnings.push(`- [WARN 测试绿缺凭证] ${base} 验收证据声明「测试绿」但 24h 内无 verify 凭证（verifications.jsonl${verifyDocBound ? `；本单须带 --doc 落账` : ''}）——跑 node .agents/scripts/verify.mjs${verifyDocBound ? ` --doc ${rel}` : ''} 后重跑（advisory，灰度第一档）`);
             continue;
           }
           if (r.t.ok) continue;
@@ -851,20 +895,8 @@ export function runCheckLoop(opts = {}) {
     }
   }
 
-  // --- 9. 文件名英文 kebab-case [warning] ---
-  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}`);
-      }
-    }
-  }
-
   // --- 10. 级别 vs 迁移文件一致性 [warning]（启发式：入口文档加入提交触及迁移 SQL/Migrations → 疑似判低；非 git 跳过）---
+  markGate('10', '级别 vs 迁移文件');
   if (gitOut(['rev-parse', '--git-dir']) !== null) {
     const log = gitOut(['log', '--diff-filter=A', '--format=@%H', '--name-only']);
     if (log !== null) {
@@ -893,54 +925,8 @@ export function runCheckLoop(opts = {}) {
     }
   }
 
-  // --- 11. workflow/INDEX.md 漂移 [warning]（调生成器 --check，口径单一不复刻渲染）---
-  {
-    const gen = path.join(ROOT, '.agents', 'scripts', 'gen-workflow-index.mjs');
-    if (fs.existsSync(gen)) {
-      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 索引漂移] workflow/INDEX.md 与磁盘不一致——跑 node .agents/scripts/gen-workflow-index.mjs 重新生成（${first}）`);
-      }
-    }
-  }
-
-  // --- 12. frontmatter「模块:」合法性 [warning]（词表单源；缺字段只对 2026-09-22 起新建提示）---
-  {
-    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 硬拦兜底）---
-  {
-    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}`);
-      }
-    }
-  }
-
   // --- 14. 新 done 的 spec/plan 须有确认留痕：git 历史「状态: approved」 或 confirmations.jsonl 台账 approved 行 [warning]（恒 advisory；非 git 跳过）---
+  markGate('14', '确认留痕（approved 快照）');
   // 2026-10-08 papercuts-cleanup-batch 修 3：两跳确认同批提交时 git 历史不出现行首「状态: approved」曾误报，
   // 而台账已证明两跳均走（2026-09-28-adopter-derivers 实证）——判据改 OR 并集（git 判据保留不弱化，
   // 台账为第二通道；确认事件以台账为准）。台账伪造面由检查 15 指纹 hard 门把关，本修仅消 advisory 误报。
@@ -982,6 +968,7 @@ export function runCheckLoop(opts = {}) {
   // --- 15. 确认指纹对账 [hard-block]（2026-09-26 confirm-gate-machine；2026-09-27 confirm-gate-delegated 两形态；
   //     生效日锚 2026-09-28 改台账 ts——此前锚取自文档自报「日期/发现」，新档只要把日期写早即整段跳过判定，
   //     incident 2026-09-28-confirm-gate-effective-date-anchor 实证）---
+  markGate('15', '确认指纹对账');
   // 确认两形态（confirm-doc.mjs）：TTY 亲手键入「可以」/ --delegated 对话委托代录（用户对话内明确放行后
   // AI 代录，台账行如实记 source=chat-delegated + quote 原话，永不伪装 TTY）。intents/specs/plans 凡
   // approved/done 须有 confirm-doc 产生的 frontmatter 确认指纹 + 台账（.agents/confirmations.jsonl）
@@ -1099,6 +1086,7 @@ export function runCheckLoop(opts = {}) {
   }
 
   // --- 16. 量化断言指标签名对账 [warning]（2026-09-28 claim-exceeds-fix；登记表单源 .agents/metric-claims.txt）---
+  markGate('16', '量化断言签名对账');
   // 判据要点：活跃态文档（draft/approved/open）中的 `{{指标名}}`（小写点分）签名须替换为实时值，留签名=未回填=
   //   warning；只查显式签名、不全文扫数字（历史叙述假阳性恒 0）；未登记签名 / 取数器缺失 → fail-loud 出账；
   //   登记表缺失 → 静默跳过（未启用该检查的装户零噪声）；装户自有指标走 .agents/metric-derivers.cjs（CJS 契约，
@@ -1109,6 +1097,7 @@ export function runCheckLoop(opts = {}) {
   runCheck16({ ROOT, ENUMS, docFiles, fmGet, inSet, isTracked, linesOf, readdirOrNull, warnings });
 
   // --- 17. 发版提交树上仍未收口的 intent/spec/plan [hard-block] ---
+  markGate('17', '发版树未收口文档');
   // 最近一次 package.json version 发生变化的提交里，当时状态已是 draft 或 approved 的
   // intent/spec/plan，被扫描的树上仍是 draft 或 approved 则阻断。
   // 当时已是 draft：不看版本锚。当时已是 approved：只在发版版本大于
@@ -1148,6 +1137,7 @@ export function runCheckLoop(opts = {}) {
   }
 
   // --- 18. 委派台账对账 [warning] ---
+  markGate('18', '委派台账对账');
   // L2/L3 的 intent、spec、plan 状态为 done，或同级别 incident 状态为 fixed 或 closed 时，
   // 「委派结果」表与「自做任务结果」表均没有日期不早于文档日期、且含该文件名（带/不带 .md 均匹配）的一行，则警告。
   // 缺级别、缺日期、以及其他状态不警告。audit:false 时 warnings.push 已被换成空函数。
@@ -1177,6 +1167,7 @@ export function runCheckLoop(opts = {}) {
   }
 
   // --- 19. 逐阶段审计 [warning]（2026-09-30 stage-gate-machine；口径与 stage-gates.mjs / fill-* / confirm-doc 前置门互引） ---
+  markGate('19', '逐阶段审计');
   // 判据 A（在途扫描）：同名 spec/plan 为 draft 且其日期 ≥ stageGateSince 时——入口未确认（intent：状态非
   //   approved/done、或缺台账行且非存量；incident：「时间线」小节缺行首「用户确认」条目）→ warning；
   //   入口缺合法「级别」→ warning（与起草门 fail-closed 同口径，2026-09-30 复核 P2-7）；
@@ -1352,6 +1343,7 @@ export function runCheckLoop(opts = {}) {
   }
 
   // --- 20. 引擎脚本测试覆盖 [warning]（2026-10-01 gate-script-test-coverage；仅包源环境） ---
+  markGate('20', '引擎脚本测试覆盖');
   // 包源开发纪律：templates/_agents/scripts/ 下每个非 *.test.mjs 引擎脚本须有同名兄弟 .test.mjs，
   // 或在 .agents/scripts-test-exempt.txt 登记豁免（managed 下发）。装户（无 templates/）整体跳过。
   {
@@ -1375,6 +1367,9 @@ export function runCheckLoop(opts = {}) {
   }
 
   // --- 输出（banner 沿 sh 版字样与格式 = 稳定输出契约：banner 后空行、条目 '- ' 前缀）---
+  // 门禁 ROI 收口（2026-10-08 gate-roi-metrics）：末段结算（末段之后无下次 gateSeg 调用）+ 可选落盘。
+  // ⚠️ 结算在输出**之前**：否则检查 20 之后的段不计入。落盘只在 --gate-stats 时发生。
+  if (opts.gateStats) writeGateStats(ROOT, finishSegs(gateStats));
   if (blockers.length) {
     process.stderr.write(`闭环骨架断档（check-loop.sh）— HARD-BLOCK:\n\n${blockers.join('\n')}\n\n`);
     if (warnings.length) process.stderr.write(`WARN（advisory,不阻断）:\n\n${warnings.join('\n')}\n`);

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

@@ -12,7 +12,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { computeFingerprint } from './confirm-doc.mjs';
 import { POLICIES, loadKitPolicy } from './policy.mjs';
-import { entryConfirmed, MARK_RE, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
+import { entryConfirmed, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const CHECK_LOOP = path.join(SCRIPT_DIR, 'check-loop.mjs');
@@ -423,6 +423,37 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
   rmfix(T);
 }
 
+// ---- 场景 27b:DASHBOARD 漂移门（2026-10-08 selfmeasure-and-modularize 检查 11 扩覆盖面）----
+// 三态：陈旧盘面 → WARN；盘面缺失（装户从未生成过看板）→ 不报（防常驻噪声）；一致 → 不报。
+{
+  const mkDashFix = () => {
+    const T = mkfix();
+    fs.mkdirSync(path.join(T, '.agents', 'scripts'), { recursive: true });
+    for (const f of ['gen-workflow-index.mjs', 'gen-workflow-dashboard.mjs', 'agg-delegations.cjs', 'workflow-enums.mjs']) {
+      fs.copyFileSync(path.join(SCRIPT_DIR, f), path.join(T, '.agents', 'scripts', f));
+    }
+    fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'workflow-modules.txt'), path.join(T, '.agents', 'workflow-modules.txt'));
+    w(T, 'workflow/intents/2026-09-22-dash.md', INTENT('dash', '状态: approved\n级别: L1\n日期: 2026-09-22\n模块: pipeline'));
+    w(T, 'workflow/plans/2026-09-22-dash.md', PLAN('dash', '状态: approved\n级别: L1\n模块: pipeline'));
+    spawnSync(process.execPath, ['.agents/scripts/gen-workflow-index.mjs'], { cwd: T });
+    return T;
+  };
+  // ① DASHBOARD.md 从未生成（装户形态）→ 不得出 WARN
+  let T = mkDashFix();
+  let r = run(T);
+  check('观测面:装户未生成过 DASHBOARD.md → 不出仪表盘漂移 WARN（防常驻噪声）',
+    r.status === 0 && !outOf(r).includes('WARN 仪表盘漂移'), outOf(r));
+  rmfix(T);
+  // ② 生成后改事实 → 漂移 WARN，且 exit 0（advisory 不阻断）
+  T = mkDashFix();
+  spawnSync(process.execPath, ['.agents/scripts/gen-workflow-dashboard.mjs'], { cwd: T });
+  w(T, 'workflow/intents/2026-09-22-dash.md', INTENT('dash', '状态: done\n级别: L1\n日期: 2026-09-22\n模块: pipeline'));
+  r = run(T);
+  check('观测面:DASHBOARD 漂移 → WARN 仪表盘漂移 且 exit 0',
+    r.status === 0 && outOf(r).includes('WARN 仪表盘漂移') && outOf(r).includes('gen-workflow-dashboard.mjs'), outOf(r));
+  rmfix(T);
+}
+
 // ---- 场景 28/29:常驻面预算——合规无告警;AGENTS.md 超限 → WARN 含一进一出 ----
 {
   const T = mkfix();
@@ -2721,6 +2752,54 @@ w(T, 'workflow/intents/2026-09-12-deep.md', INTENT('deep', '状态: draft\n级
   rmfix(T2);
 }
 
+// ---- 检查 8 凭证按 doc 绑定（2026-10-08 verify-doc-binding）：v6 收紧 / v5 不变 ----
+// 漏洞本体：凭证行不带 doc 字段 + 判定只看「全仓任意一份 24h 内绿行」→ 跑一次 verify 就能给全仓
+// 任意一单的「测试绿」声明背书。本组三条：① v6 + 只有他单绿行 → 仍出 WARN（漏洞已堵）；
+// ② v6 + 本单绿行 → 豁免零 WARN；③ **v5 + 只有他单绿行 → 无 WARN**（兼容反例，收紧只对 v6+ 生效）。
+{
+  const mkVeDoc = (pv, docField) => {
+    const T = mkfix();
+    gitInit(T);
+    w(T, '.agents/kit.json', JSON.stringify({ policyVersion: pv }));
+    const green = { ts: new Date().toISOString(), exitCode: 0, suite: 'npm test' };
+    if (docField) green.doc = docField;
+    w(T, '.agents/verifications.jsonl', `${JSON.stringify(green)}\n`);
+    const iBody = '# INTENT — ve\n\n## 验收标准（可测试）\n- [x] 用例通过（证据:测试全绿）\n';
+    const pBody = '# PLAN — ve\n';
+    const fpI = computeFingerprint(`---\n状态: approved\n级别: L1\n日期: 2026-10-07\n---\n${iBody}`);
+    const fpP = computeFingerprint(`---\n状态: approved\n级别: L1\n---\n${pBody}`);
+    w(T, 'workflow/intents/2026-10-07-ve.md', `---\n状态: done\n级别: L1\n日期: 2026-10-07\n确认指纹: ${fpI.slice(0, 16)}\n---\n${iBody}`);
+    w(T, 'workflow/plans/2026-10-07-ve.md', `---\n状态: done\n级别: L1\n确认指纹: ${fpP.slice(0, 16)}\n---\n${pBody}`);
+    const now = new Date().toISOString();
+    writeLedger(T, [
+      { ts: now, doc: 'workflow/intents/2026-10-07-ve.md', stage: 'done', fingerprint: fpI, prev: 'approved' },
+      { ts: now, doc: 'workflow/plans/2026-10-07-ve.md', stage: 'done', fingerprint: fpP, prev: 'approved' },
+    ]);
+    gitCommitAll(T, 'feat: ve doc-binding fixture');
+    return T;
+  };
+  const MINE = 'workflow/intents/2026-10-07-ve.md';
+  const OTHER = 'workflow/intents/2026-10-07-someone-else.md';
+
+  const D1 = mkVeDoc(6, OTHER);
+  let r = run(D1);
+  check('检查8 凭证绑定:v6 + 只有**他单**绿行 → 仍出 WARN（跨单背书漏洞已堵）',
+    r.status === 0 && outOf(r).includes('测试绿缺凭证') && !outOf(r).includes('证据豁免 verify'), `exit=${r.status}\n${outOf(r)}`);
+  rmfix(D1);
+
+  const D2 = mkVeDoc(6, MINE);
+  r = run(D2);
+  check('检查8 凭证绑定:v6 + 本单绿行 → verify 豁免零 WARN（绑定成立）',
+    r.status === 0 && outOf(r).includes('证据豁免 verify') && !outOf(r).includes('测试绿缺凭证'), `exit=${r.status}\n${outOf(r)}`);
+  rmfix(D2);
+
+  const D3 = mkVeDoc(5, OTHER);
+  r = run(D3);
+  check('检查8 凭证绑定:v5 + 只有他单绿行 → **无 WARN**（兼容反例：收紧只对 v6+ 生效）',
+    r.status === 0 && !outOf(r).includes('测试绿缺凭证') && outOf(r).includes('证据豁免 verify'), `exit=${r.status}\n${outOf(r)}`);
+  rmfix(D3);
+}
+
 // ---- 检查 18 表头签名识别（2026-10-08 papercuts-cleanup-batch 修 2）：节标题漂移不再静默停解析 ----
 // 修前按 `## 委派结果|自做任务结果` 精确节标题切段，装户把标题写成「委派结果表」即静默停解析该表
 // → L2/L3 done 回流无告警；修后按表头签名（与 agg-delegations.cjs splitTables 同口径）识别。
@@ -2788,5 +2867,40 @@ w(T, 'workflow/intents/2026-09-12-deep.md', INTENT('deep', '状态: draft\n级
   rmfix(T);
 }
 
+// ---- 门禁 ROI 插桩（2026-10-08 gate-roi-metrics）----
+// 断言两件事：① 默认路径不落盘、stderr 无 gate-stats 行（输出契约零污染）；
+//           ② --gate-stats 落一行 jsonl 且段覆盖全部检查（判据不漏插）。
+// 既有 223 条断言零改动本身即最强钉子——任何 push 到 warnings 的插桩副作用都会把它们打红。
+{
+  const T = mkfix();
+  const statsRel = path.join('.agents', 'cache', 'gate-stats.jsonl');
+  const plain = run(T);
+  check('门禁ROI：默认路径不落 gate-stats.jsonl（统计默认静默）',
+    !fs.existsSync(path.join(T, statsRel)), outOf(plain));
+  check('门禁ROI：默认路径 stderr 无 [gate-stats] 摘要行（稳定输出契约零污染）',
+    !outOf(plain).includes('[gate-stats]'), outOf(plain));
+  const before = fs.existsSync(path.join(T, statsRel)) ? fs.readFileSync(path.join(T, statsRel), 'utf8') : '';
+
+  const st = run(T, { args: ['--gate-stats'] });
+  check('门禁ROI：--gate-stats → 落盘 + stderr 摘要行', fs.existsSync(path.join(T, statsRel)) && outOf(st).includes('[gate-stats]'), outOf(st));
+  const lines = fs.readFileSync(path.join(T, statsRel), 'utf8').split('\n').filter(Boolean);
+  check('门禁ROI：--gate-stats 只 append 一行（每跑一次门禁 = 一条记录）',
+    lines.length === 1 && !before, `lines=${lines.length} before=${before.length}`);
+  let row = null;
+  try { row = JSON.parse(lines[0]); } catch { /* 留给下一条断言报错 */ }
+  const ids = row && Array.isArray(row.segs) ? row.segs.map((s) => String(s.id)) : [];
+  const uniq = new Set(ids);
+  check('门禁ROI：段 id 唯一且覆盖 19 个插桩点（14 主流程 + 5 hygiene 模块），无重复插桩',
+    ids.length === 19 && uniq.size === 19, `ids=${ids.join(',')}`);
+  const expected = ['1','2','3','4','5','6','8','9','10','11','12','13','14','15','16','17','18','19','20'];
+  check('门禁ROI：段 id 集合 == 现有检查编号（不新增/不遗漏检查项编号）',
+    expected.every((e) => uniq.has(e)) && uniq.size === expected.length, `got=${[...uniq].sort().join(',')}`);
+  check('门禁ROI：每段都有 label + 非负 ms（成本度量的地基）',
+    row && row.segs.every((s) => s.label && Number(s.ms) >= 0 && Number.isInteger(Number(s.ms))), JSON.stringify(row && row.segs.slice(0, 3)));
+  check('门禁ROI：行顶层含 ts / root / totalMs（聚合器的窗口过滤依赖 ts）',
+    row && typeof row.ts === 'string' && typeof row.root === 'string' && Number(row.totalMs) >= 0, JSON.stringify({ ts: row && row.ts, totalMs: row && row.totalMs }));
+  rmfix(T);
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/commit-check-trigger.test.mjs

@@ -9,7 +9,6 @@ import { fileURLToPath } from 'node:url';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const HOOK = path.join(SCRIPT_DIR, '..', 'hooks', 'commit-check.cjs');
-const MARK = 'TRIGGER_TEST_BUILD_RAN';
 
 let pass = 0, fail = 0;
 const check = (desc, cond, detail = '') => {

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

@@ -38,22 +38,33 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { createHash, randomBytes } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
 import { confirmGateFor, doneGateFor, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
 import { loadKitPolicy, hasFreshVerifyLine } from './policy.mjs';
 
-// hasFreshVerify(root)：读 <root>/.agents/verifications.jsonl 判 24h 窗口绿行（判定单源
+// hasFreshVerify(root, doc)：读 <root>/.agents/verifications.jsonl 判 24h 窗口绿行（判定单源
 // policy.hasFreshVerifyLine）。只读，台账缺失/不可读一律 false（=无凭证，advisory 层 fail-open）。
-function hasFreshVerify(root) {
+// doc 绑定（2026-10-08 verify-doc-binding）：非空时只认 e.doc === doc 的绿行——不带 doc 的绿行
+// （CI 场景）与**别的单**的绿行都不给本单背证。调用方负责「仅 v6+ 才传 doc」，本函数不做版本判断。
+function hasFreshVerify(root, doc = null) {
   try {
     const p = path.join(root, '.agents', 'verifications.jsonl');
     if (!fs.existsSync(p)) return false;
-    return hasFreshVerifyLine(fs.readFileSync(p, 'utf8').split(/\r?\n/));
+    return hasFreshVerifyLine(fs.readFileSync(p, 'utf8').split(/\r?\n/), Date.now(), doc);
   } catch {
     return false;
   }
 }
 
+// docRelOf：把用户传入的 doc 路径归一成「相对仓库根的 posix 相对路径」——与 verify.mjs --doc 的落账口径
+// 必须逐字一致（一个转得动、另一个转不动 = 凭证永远匹配不上）。win32 反斜杠 / posix / 绝对路径三者同值。
+function docRelOf(root, doc) {
+  try {
+    return path.relative(root, path.resolve(root, doc)).split(path.sep).join('/');
+  } catch {
+    return doc;
+  }
+}
+
 // computeFingerprint(text)：CRLF 归一 → 剔指纹行 → sha256 hex（64 位）
 export function computeFingerprint(text) {
   const norm = String(text).replace(/\r\n/g, '\n').split('\n')
@@ -319,10 +330,19 @@ if (isMain) {
     // 测试绿凭证前置（2026-10-07 verify-evidence，advisory 不拦）：→done 且文档含「验收标准」节且
     // policy v5（verifySince）→ 24h 窗口内须有 verifications.jsonl 绿行。只读判定，任何读取异常降级
     // 静默（fail-open——advisory 层不因台账缺失/坏行阻断关单）；升 hard 走后续 policyVersion 演进。
+    // 2026-10-08 verify-doc-binding：v6+（verifyDocSince）时按本 doc 精确匹配绿行——他单的绿行不再
+    // 给本单背书；v1-v5 维持 v5 全局行为逐字不变。
+    // ⚠️ 文案锚点硬约束（既有 confirm-doc.test.mjs 断言锚定子串，零改动前提）：
+    // 「无测试绿凭证」六字须**连续**，doc 与命令只能追加在其后——不得写成「无本单（x）的测试绿凭证」。
     if (target === 'done' && typeof loadKitPolicy(root).verifySince === 'string'
-      && /^##\s*[^#]*验收标准/m.test(text) && !hasFreshVerify(root)) {
-      console.error(`⚠️ ${doc} 置 done：24h 内无测试绿凭证（verifications.jsonl）——关单勾验的「测试绿」声明缺机器事实`);
-      console.error('   跑 node .agents/scripts/verify.mjs（全绿自动落账）后重新关单；本次不拦截（advisory，灰度第一档）');
+      && /^##\s*[^#]*验收标准/m.test(text)) {
+      const pol = loadKitPolicy(root);
+      const rel = docRelOf(root, doc);
+      const bound = typeof pol.verifyDocSince === 'string' ? rel : null;
+      if (!hasFreshVerify(root, bound)) {
+        console.error(`⚠️ ${doc} 置 done：24h 内无测试绿凭证（${bound ? `本单 ${rel} 须带 --doc 落账` : '凭证未按单绑定'}）——关单勾验的「测试绿」声明缺机器事实`);
+        console.error(`   跑 node .agents/scripts/verify.mjs${bound ? ` --doc ${rel}` : ''} 后重新关单；本次不拦截（advisory，灰度第一档）`);
+      }
     }
     const fp = computeFingerprint(text);
     // AI 自治放行分支（2026-09-30 ai-autonomy-trust）：