agentic-flow-kit 1.2.2 → 1.4.0

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

@@ -17,7 +17,7 @@ import { entryConfirmed, MARK_RE, laneOfEntry, laneOfDoc } from './stage-gates.m
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const CHECK_LOOP = path.join(SCRIPT_DIR, 'check-loop.mjs');
 const GIT = process.platform === 'win32' ? 'git.exe' : 'git'; // Windows spawn 不补 .exe 扩展名（gitInit/gitCommitAll/场景 43/44/47 共用）
-// 注意：check-loop.mjs 无 isMain 主守卫，被 import 即全量执行门禁并 process.exit——本套件只能端到端 spawn，
+// 注意（2026-10-08 checkloop-importable 后）：check-loop.mjs 已有 isMain 主守卫，可 import（runCheckLoop/四纯零件，直测见 check-loop-unit.test.mjs）——本套件保持端到端 spawn 作为行为回归网，
 // 不可从其 import 函数直测（2026-10-04 review-fix-batch 实证；可 import 化记 papercuts 待 L2 重构）
 
 let pass = 0;
@@ -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();
@@ -743,6 +774,24 @@ const evidenceFixture = (slug, declared, createDeclared) => {
   check('git 基础设施异常:基础设施异常不冒充业务裁决（无证据无关误报）', !outOf(r).includes('证据无关'), outOf(r));
   rmfix(T);
 }
+{
+  // 纯数字短 sha × 通道坏死（2026-10-07 v1.3.0 Release CI ubuntu 实证）：fixture 短 sha 恰全数字
+  //（`--short` 7 位 ≈4%/run）时，rev-parse 实证分流在 CHECK_LOOP_GIT 整体坏死下不可能——
+  // 纯数字 text 豁免曾把 fail-closed 漏成 exit 0。守卫后：通道坏死（spawn 异常）→ forged 拦；
+  // 对照：通道健康时纯数字假 sha → rev-parse 正常回答不存在 → text 豁免语义保持（misfire 防线不回归）。
+  const T = mkfix();
+  gitInit(T);
+  w(T, 'workflow/plans/2026-09-26-pe7.md', PLAN('pe7', '状态: done\n级别: L1\n模块: material', '\n## 改动方案\n\n- src/app.mjs：实现功能\n'));
+  w(T, 'workflow/intents/2026-09-26-pe7.md', INTENT('pe7', '状态: done\n级别: L1\n日期: 2026-09-26', '\n## 验收标准（可测试）\n- [x] 演练穿越（证据:1234567）\n'));
+  gitCommitAll(T, 'docs(x): 纯数字证据通道坏死场景');
+  const rDead = run(T, { env: { CHECK_LOOP_GIT: 'definitely-not-git-xyz-2026' } });
+  check('git 基础设施异常:纯数字 sha × 通道坏死 → forged 拦不豁免（实证不可能即 fail-closed）',
+    rDead.status === 1 && outOf(rDead).includes('证据伪造'), `exit=${rDead.status}\n${outOf(rDead)}`);
+  const rAlive = run(T);
+  check('git 基础设施异常:纯数字假 sha × 通道健康 → text 豁免语义保持（misfire 防线不回归）',
+    rAlive.status === 0 && outOf(rAlive).includes('证据豁免 text'), `exit=${rAlive.status}\n${outOf(rAlive)}`);
+  rmfix(T);
+}
 {
   const T = mkfix();
   gitInit(T);
@@ -2703,5 +2752,155 @@ 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 同口径）识别。
+{
+  const T = mkfix();
+  const gap = '2026-09-12-drift.md';
+  w(T, `workflow/intents/${gap}`, INTENT('drift', '状态: done\n级别: L2\n日期: 2026-09-12', '\n## 验收标准（可测试）\n- [x] 用例通过（证据:fixture）\n'));
+  w(T, `workflow/specs/${gap}`, SPEC('drift', '状态: approved\n级别: L2\n日期: 2026-09-12'));
+  w(T, `workflow/plans/${gap}`, PLAN('drift', '状态: approved\n级别: L2\n日期: 2026-09-12'));
+  const ledgerWarn = (r) => outOf(r).split('\n').some((l) => l.includes('委派台账') && l.includes(`intents/${gap}`));
+  // 正例：节标题漂移（「委派结果表」≠精确节名）而表头不动 → 仍按表头签名解析，警告消失
+  w(T, 'workflow/delegations.md', '## 委派结果表\n\n| 日期 | 被委派方 | 任务一句话 | 结果 | 备注 |\n|------|----------|------------|------|------|\n| 2026-09-12 | x | y | 一次通过 | 2026-09-12-drift |\n');
+  let r = run(T);
+  check('检查18 节标题漂移而表头不动 → 仍按表头签名解析，警告消失（修 2 核心场景）',
+    r.status === 0 && !ledgerWarn(r), `exit=${r.status}\n${outOf(r)}`);
+  // 负例：表头也漂移（新格式无签名列）→ 数据行不收集 → 警告仍在（识别不过宽）
+  w(T, 'workflow/delegations.md', '## 委派结果表\n\n| 日期 | 承办 | 说明 |\n|------|------|------|\n| 2026-09-12 | x | 2026-09-12-drift |\n');
+  r = run(T);
+  check('检查18 表头也漂移（无签名列）→ 不收集 → 警告仍在（识别不过宽负例）',
+    r.status === 0 && ledgerWarn(r), `exit=${r.status}\n${outOf(r)}`);
+  rmfix(T);
+}
+
+// ---- 检查 14 台账 OR（2026-10-08 papercuts-cleanup-batch 修 3）：git 历史无 approved 行而台账有 → 不再误报 ----
+// 两跳确认同批提交时 git 历史不出现行首「状态: approved」（2026-09-28-adopter-derivers 实证）——
+// confirmations.jsonl 已证明两跳均走；判据改 OR 并集（git 判据保留，台账为第二通道）。
+{
+  const T = mkfix();
+  gitInit(T);
+  const base = '2026-09-23-confirm-ledger';
+  w(T, `workflow/incidents/${base}.md`, `---\n状态: closed\n级别: L1\n发现: 2026-09-23\n模块: material\n---\n# INCIDENT — confirm ledger\n\n${三件套(false)}`);
+  w(T, `workflow/plans/${base}.md`, PLAN('confirm ledger', '状态: done\n级别: L1\n模块: material'));
+  gitCommitAll(T, 'test'); // 两跳同批：git 历史无行首 approved（修前必 WARN）
+  w(T, '.agents/confirmations.jsonl', `${JSON.stringify({ ts: '2026-09-23T00:00:00Z', doc: `workflow/plans/${base}.md`, stage: 'approved', fingerprint: 'x', prev: 'draft', source: 'tty' })}\n`);
+  let r = run(T);
+  // exit 1 属检查 15 指纹 hard 同场（台账有该 doc 行即受管，fixture 无真实指纹必拦——预期）；
+  // 本场景只断言检查 14 的 WARN 确认态缺失不再出账（台账 OR 兜住）
+  check('检查14 git 历史无 approved 行而台账有 → 台账 OR 兜住不误报（修 3 核心场景）',
+    !outOf(r).includes('WARN 确认态缺失'), `exit=${r.status}\n${outOf(r)}`);
+  // 台账行 doc 不指向该文档 → 仍 WARN（OR 不弱化原判据）
+  w(T, '.agents/confirmations.jsonl', `${JSON.stringify({ ts: '2026-09-23T00:00:00Z', doc: 'workflow/plans/other.md', stage: 'approved', fingerprint: 'x', prev: 'draft', source: 'tty' })}\n`);
+  r = run(T);
+  check('检查14 台账无该文档 approved 行 → 仍 WARN（git 判据未被弱化）',
+    r.status === 0 && /WARN 确认态缺失.*2026-09-23-confirm-ledger\.md/.test(outOf(r)), outOf(r));
+  rmfix(T);
+}
+
+// ---- 检查 4 全角逗号（2026-10-08 papercuts-cleanup-batch 修 4）：路径引用后跟「，」不再吞入引用串 ----
+// 中文文档「`.agents/...`，以及…」写法曾把「，」并入引用 → 引用断档误报（p0-gate-noise-batch 实证 2 条）。
+{
+  const T = mkfix();
+  fs.mkdirSync(path.join(T, '.agents', 'commands'), { recursive: true });
+  w(T, '.agents/commands/plan.md', '# 小命令\n');
+  w(T, 'workflow/intents/2026-09-12-ref-comma.md', INTENT('ref comma', '状态: approved\n级别: L1\n日期: 2026-09-12\n模块: pipeline', '\n入口 `.agents/commands/plan.md`，以及后续步骤。\n'));
+  w(T, 'workflow/plans/2026-09-12-ref-comma.md', PLAN('ref comma', '状态: approved\n级别: L1\n模块: pipeline'));
+  let r = run(T);
+  check('检查4 路径后跟全角逗号 → 引用串不吞「，」，真实路径不误报断档',
+    r.status === 0 && !outOf(r).includes('引用断档'), `exit=${r.status}\n${outOf(r)}`);
+  w(T, 'workflow/intents/2026-09-12-ref-comma2.md', INTENT('ref comma2', '状态: approved\n级别: L1\n日期: 2026-09-12\n模块: pipeline', '\n入口 `.agents/commands/missing-broken.md`，后续。\n'));
+  w(T, 'workflow/plans/2026-09-12-ref-comma2.md', PLAN('ref comma2', '状态: approved\n级别: L1\n模块: pipeline'));
+  r = run(T);
+  // 负例用 ASCII 断档名：refRe 字符类本就只含 ASCII 路径字符（中文名路径不在扫描范围）
+  check('检查4 全角逗号后的真断档 → 仍拦（判据不放松）',
+    r.status === 0 && /引用断档.*missing-broken\.md/.test(outOf(r)), `exit=${r.status}\n${outOf(r)}`);
+  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/confirm-doc.mjs

@@ -42,18 +42,30 @@ 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 +331,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）：

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/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);