agentic-flow-kit 1.2.2 → 1.4.0

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

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+// gen-workflow-dashboard.mjs — workflow 仪表盘（2026-10-08，intent workflow-dashboard，L1）
+// 一键生成 workflow/DASHBOARD.md：头部红绿灯（质量门 + 关单时长带）+ 时长分布 + 质量月度行。
+// 观测面非门禁：红灯是「看」的不是「拦」的（gen-workflow-metrics 同教训——快照拿去做漂移校验只会常红）；
+// 想看就跑一行命令，与 INDEX.md「状态变更后重跑」同模式，不挂钩子（post-commit 自动重生成有脏工作区问题）。
+// 时长口径：done 态 intents 的立项日（frontmatter 日期）→ confirmations.jsonl 该 doc **最早** done 行 ts
+// （多次 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 / 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';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = process.env.CHECK_LOOP_ROOT || path.resolve(SCRIPT_DIR, '..', '..');
+const agg = require('./agg-delegations.cjs');
+
+// 关单时长控制带（默认带，数据说话后调）：P50 ≤ 1 天 且 P90 ≤ 10 天为绿——本仓实测 P50=0/P90=7 在带内，
+// 留 7 天 P90 余量覆盖跨周单；不带配置文件（YAGNI，真需要项目级调带时再外置）。
+export const DURATION_BAND = { p50Max: 1, p90Max: 10 };
+
+// closeDurations：done intents 关单天数（纯函数供测试）——doneMap: Map<rel, 最早 done 行 ISO ts>
+export function closeDurations(intents, doneMap) {
+  const days = [];
+  let skipped = 0;
+  for (const it of intents) {
+    const ts = doneMap.get(it.rel);
+    const t = ts === undefined ? NaN : Date.parse(ts);
+    const d0 = Date.parse(`${it.date}T00:00:00Z`);
+    if (!Number.isFinite(t) || !Number.isFinite(d0)) { skipped++; continue; }
+    days.push({ rel: it.rel, days: Math.max(0, Math.floor((t - d0) / 86400000)) }); // floor=日历天差：同日关门 0.625 天仍记 0（round 会记 1）
+  }
+  days.sort((a, b) => a.days - b.days || a.rel.localeCompare(b.rel));
+  return { days, skipped };
+}
+
+// pickPct：百分位（升序数组；与 repo 内实测探针同口径 floor(len*p) 截断）
+export function pickPct(sortedNums, p) {
+  if (!sortedNums.length) return null;
+  return sortedNums[Math.min(sortedNums.length - 1, Math.floor(sortedNums.length * p))];
+}
+
+// durationVerdict：时长带判定（三态：无样本 null / 带内 / 超带）
+export function durationVerdict(p50, p90) {
+  if (p50 === null) return { ok: null, text: '⚪ 暂无关单样本（无带台账 done 行的 done intent）' };
+  const ok = p50 <= DURATION_BAND.p50Max && p90 <= DURATION_BAND.p90Max;
+  return { ok, text: ok ? '✅ 带内' : '❌ 超带' };
+}
+
+// fmField：frontmatter 单行「键: 值」最小提取（check-loop fmGet 无 isMain 守卫不可 import——本件够用）
+function fmField(text, key) {
+  const m = String(text).match(new RegExp(`^${key}: (.*)$`, 'm'));
+  return m ? m[1].trim() : '';
+}
+
+// collectDoneIntents：done 态 intents（排除 _TEMPLATE）→ [{rel, date}]
+function collectDoneIntents(root) {
+  const dir = path.join(root, 'workflow', 'intents');
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith('.md') || f.startsWith('_TEMPLATE')) continue;
+    const text = fs.readFileSync(path.join(dir, f), 'utf8');
+    if (fmField(text, '状态') !== 'done') continue;
+    const date = fmField(text, '日期');
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) continue;
+    out.push({ rel: `workflow/intents/${f}`, date });
+  }
+  return out;
+}
+
+// collectDoneMap：台账 earliest done 行（坏行容忍，doc 正斜杠根相对——沿检查 14/15 口径）
+function collectDoneMap(root) {
+  const doneMap = new Map();
+  const ledgerPath = path.join(root, '.agents', 'confirmations.jsonl');
+  if (!fs.existsSync(ledgerPath)) return doneMap;
+  for (const line of fs.readFileSync(ledgerPath, 'utf8').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && e.stage === 'done' && typeof e.doc === 'string' && e.doc.startsWith('workflow/intents/')) {
+        const prev = doneMap.get(e.doc);
+        if (prev === undefined || e.ts < prev) doneMap.set(e.doc, e.ts);
+      }
+    } catch { /* 坏行容忍跳过 */ }
+  }
+  return doneMap;
+}
+
+// qualityRows：月度质量行（判据全部复用 agg——本函数只做分组与格式化）
+export function qualityRows(root) {
+  const rows = agg.readLedger(root, { soft: true });
+  const byMonth = {};
+  for (const r of rows) (byMonth[r.date.slice(0, 7)] ||= []).push(r);
+  const months = Object.keys(byMonth).sort();
+  const verdictMap = new Map();
+  const monthOkMap = new Map();
+  const out = [];
+  for (const ym of months) {
+    const m = agg.metrics(byMonth[ym]);
+    const { items, monthOk } = agg.gateMonth(m);
+    monthOkMap.set(ym, monthOk);
+    const [y, mo] = ym.split('-').map(Number);
+    const pd = new Date(Date.UTC(y, mo - 2, 1));
+    const prev = `${pd.getUTCFullYear()}-${String(pd.getUTCMonth() + 1).padStart(2, '0')}`;
+    const verdict = agg.expansionVerdict(monthOk, monthOkMap.get(prev), !months.includes(prev), items);
+    verdictMap.set(ym, verdict);
+    const pct = (x) => (Number.isFinite(x) ? `${Math.round(x * 100)}%` : '—');
+    const avg = Number.isFinite(m.avgRework) ? m.avgRework.toFixed(2) : '—';
+    // 门禁噪声返工单列（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 };
+}
+
+// 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 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);
+  const nums = days.map((d) => d.days);
+  const p50 = pickPct(nums, 0.5);
+  const p90 = pickPct(nums, 0.9);
+  const mx = nums.length ? nums[nums.length - 1] : null;
+  const dv = durationVerdict(p50, p90);
+  const q = qualityRows(ROOT);
+  const curYm = q.months[q.months.length - 1];
+  const qVerdict = curYm ? q.verdictMap.get(curYm) : '⚪ 台账暂无数据（delegations.md 无结果表行）';
+
+  const slowest = days.slice(-3).reverse().map((d) => `${d.rel.split('/').pop()}=${d.days}天`).join('、') || '—';
+  const stat = (x) => (x === null ? '—' : `${x} 天`);
+  const lines = [
+    '# workflow 仪表盘（生成物，勿手改）',
+    '',
+    `> 生成器 \`node .agents/scripts/gen-workflow-dashboard.mjs\`；生成于 ${new Date().toISOString()}`,
+    '> 观测面非门禁：红灯提示看，不拦提交；想看就跑一行命令（与 INDEX.md「状态变更后重跑」同模式）。',
+    '',
+    '## 红绿灯',
+    '',
+    `- ${qVerdict}｜质量门（门槛权威 = workflow/delegations.md §并发扩容门槛：一次通过率 ≥90%、月度返工 0、无主兜底、样本 ≥5）${curYm ? `——当月 ${curYm}` : ''}`,
+    `- ${dv.text}｜关单时长带（P50 ≤ ${DURATION_BAND.p50Max} 天 且 P90 ≤ ${DURATION_BAND.p90Max} 天）：P50=${stat(p50)} / P90=${stat(p90)} / max=${stat(mx)}（样本 ${nums.length}，无台账行跳过 ${skipped}）`,
+    '',
+    '## 关单时长（done intents：立项日 → 台账最早 done 行）',
+    '',
+    '| 指标 | 值 |',
+    '|------|----|',
+    `| P50 | ${stat(p50)} |`,
+    `| P90 | ${stat(p90)} |`,
+    `| max | ${stat(mx)} |`,
+    `| 样本数 | ${nums.length} |`,
+    `| 无台账行跳过（存量单） | ${skipped} |`,
+    '',
+    `最慢 3 单：${slowest}`,
+    '',
+    '## 质量 / 返工（月度，判据复用 agg-delegations）',
+    '',
+    '| 月份 | 有效任务 | 一次通过率 | 设计返工 | 门禁噪声返工 | 平均返工 | 主兜底占比 | 扩容门判定 |',
+    '|------|----------|------------|---------|-------------|--------|------------|------------|',
+    ...(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;
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, out, 'utf8');
+  console.log(`✅ 已生成 ${path.relative(ROOT, target) || 'workflow/DASHBOARD.md'}`);
+  console.log(`   红绿灯：${qVerdict.split('｜')[0].trim()} 质量门 ｜ ${dv.text} 关单时长带（P50=${stat(p50)} / P90=${stat(p90)}，样本 ${nums.length}）`);
+}
+
+const isMain = process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('gen-workflow-dashboard.mjs');
+if (isMain) main();

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

@@ -0,0 +1,189 @@
+// gen-workflow-dashboard.test.mjs — workflow 仪表盘测试（2026-10-08 workflow-dashboard，L1）
+// 两层：①纯函数直测（closeDurations 四例 / pickPct / durationVerdict 三态 / qualityRows 复用 agg 同值对账）；
+//       ②端到端 spawn 一例（CHECK_LOOP_ROOT 注入 fixture，断言 DASHBOARD.md 红绿灯行与结构）。
+// fixture：临时 root（intents + confirmations.jsonl + delegations.md 两表）。
+// 用法：node templates/_agents/scripts/gen-workflow-dashboard.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 { 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'));
+
+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}` : ''}`); }
+};
+const W = (root, rel, content) => { fs.mkdirSync(path.join(root, path.dirname(rel)), { recursive: true }); fs.writeFileSync(path.join(root, rel), content); };
+const INTENT = (fm) => `---\n${fm}\n---\n# INTENT — x\n`;
+
+// ---- ① closeDurations 四例 ----
+{
+  const intents = [
+    { rel: 'workflow/intents/2026-10-01-same.md', date: '2026-10-01' },   // 同日 → 0
+    { rel: 'workflow/intents/2026-09-20-cross.md', date: '2026-09-20' },  // 跨 7 天
+    { rel: 'workflow/intents/2026-09-01-multi.md', date: '2026-09-01' },  // 多次 done → 取最早（=14 天，非 3 天）
+    { rel: 'workflow/intents/2026-09-05-noledger.md', date: '2026-09-05' }, // 无台账行 → 跳过
+    { rel: 'workflow/intents/2026-09-10-baddate.md', date: 'not-a-date' },  // 坏日期 → 跳过
+  ];
+  const doneMap = new Map([
+    ['workflow/intents/2026-10-01-same.md', '2026-10-01T15:00:00.000Z'],
+    ['workflow/intents/2026-09-20-cross.md', '2026-09-27T12:00:00.000Z'],
+    ['workflow/intents/2026-09-01-multi.md', '2026-09-04T00:00:00.000Z'], // 后发生的 done 行
+  ]);
+  // 最早 done 行由 collectDoneMap 保证——此处直测取值；「取最早」在 ② 端到端断言
+  doneMap.set('workflow/intents/2026-09-01-multi.md', '2026-09-04T00:00:00.000Z');
+  const { days, skipped } = closeDurations(intents, doneMap);
+  const byRel = new Map(days.map((d) => [d.rel, d.days]));
+  check('时长：同日关单 = 0 天', byRel.get('workflow/intents/2026-10-01-same.md') === 0, JSON.stringify(days));
+  check('时长：跨 7 天 = 7', byRel.get('workflow/intents/2026-09-20-cross.md') === 7);
+  check('时长：doneMap 值即最早行 → 3 天（最早判定在 collectDoneMap，端到端覆盖）', byRel.get('workflow/intents/2026-09-01-multi.md') === 3);
+  check('时长：无台账行 + 坏日期 → skipped=2 不虚构', skipped === 2 && !byRel.has('workflow/intents/2026-09-05-noledger.md'), `skipped=${skipped}`);
+}
+
+// ---- ② pickPct / durationVerdict 三态 ----
+{
+  check('pickPct：43 样本 P50=0 / P90=7（真实分布回归基准）',
+    pickPct([...Array(26).fill(0), ...Array(9).fill(1), 7, 8, 8, 8, 8], 0.5) === 0
+    && pickPct([...Array(26).fill(0), ...Array(9).fill(1), 7, 8, 8, 8, 8], 0.9) === 8,
+    `p50=${pickPct([0, 0, 1], 0.5)}`);
+  check('pickPct：空 → null', pickPct([], 0.5) === null);
+  check('时长带：P50=0/P90=7 → 带内；P50=2 → 超带；null → 无样本',
+    durationVerdict(0, 7).ok === true && durationVerdict(2, 5).ok === false && durationVerdict(null, null).ok === null,
+    JSON.stringify([durationVerdict(0, 7), durationVerdict(2, 5), durationVerdict(null, null)]));
+  check('时长带常量：P50≤1 且 P90≤10（默认带声明）', DURATION_BAND.p50Max === 1 && DURATION_BAND.p90Max === 10);
+}
+
+// ---- ③ qualityRows 复用 agg 同值对账 + 端到端 spawn ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-dash-'));
+  // delegations.md：2026-09 二十单全「一次通过」（委派 ≥ 样本护栏 minSample=20）→ 口径项全过
+  const head = '## 委派结果\n\n| 日期 | 被委派方 | 任务一句话 | 结果 | 备注 |\n|------|----------|------------|------|------|\n';
+  const rows9 = [...Array(20)].map((_, i) => `| 2026-09-${String(i + 1).padStart(2, '0')} | x | y${i} | 一次通过 | 2026-09-a${i} |\n`).join('');
+  W(root, 'workflow/delegations.md', `${head}${rows9}`);
+  // intents + 台账：same=0 / multi 两行 done 取最早（09-01 → 09-03=2 天，第二行 09-10 不采纳）
+  W(root, 'workflow/intents/2026-09-01-multi.md', INTENT('状态: done\n级别: L1\n日期: 2026-09-01\n模块: pipeline'));
+  W(root, 'workflow/intents/2026-10-01-same.md', INTENT('状态: done\n级别: L1\n日期: 2026-10-01\n模块: pipeline'));
+  W(root, 'workflow/intents/2026-09-05-noledger.md', INTENT('状态: done\n级别: L1\n日期: 2026-09-05\n模块: pipeline'));
+  W(root, 'workflow/intents/2026-09-06-open.md', INTENT('状态: approved\n级别: L1\n日期: 2026-09-06\n模块: pipeline')); // 非 done 不计
+  W(root, '.agents/confirmations.jsonl', [
+    JSON.stringify({ ts: '2026-09-02T00:00:00.000Z', doc: 'workflow/intents/2026-09-01-multi.md', stage: 'done' }),
+    JSON.stringify({ ts: '2026-09-10T00:00:00.000Z', doc: 'workflow/intents/2026-09-01-multi.md', stage: 'done' }),
+    JSON.stringify({ ts: '2026-10-01T20:00:00.000Z', doc: 'workflow/intents/2026-10-01-same.md', stage: 'done' }),
+    JSON.stringify({ ts: '2026-09-02T00:00:00.000Z', doc: 'workflow/intents/2026-09-01-multi.md', stage: 'approved' }), // 非 done 行不混
+    'not-json-bad-line',
+  ].join('\n') + '\n');
+
+  // 纯函数层：qualityRows 与 agg 直算同值
+  const q = qualityRows(root);
+  check('qualityRows：月份行数与台账月份一致（2026-09 一行）', q.rows.length === 1 && q.rows[0].startsWith('| 2026-09 |'), JSON.stringify(q.rows));
+  const m = aggCjs.metrics(aggCjs.readLedger(root, { soft: true }));
+  check('qualityRows：复用 agg 同值（total=20）', m.total === 20, `total=${m.total}`);
+  check('qualityRows：单月门全过 → 判定「本月达标」（首月连续性 1/2 属 expansionVerdict 语义）',
+    q.verdictMap.get('2026-09').includes('达标'), q.verdictMap.get('2026-09'));
+
+  // 端到端：spawn 真脚本（CHECK_LOOP_ROOT 注入）→ DASHBOARD.md 结构断言
+  const r = spawnSync(process.execPath, [path.join(SCRIPT_DIR, 'gen-workflow-dashboard.mjs')], {
+    cwd: root, encoding: 'utf8',
+    env: { ...process.env, CHECK_LOOP_ROOT: root },
+  });
+  const dash = fs.readFileSync(path.join(root, 'workflow', 'DASHBOARD.md'), 'utf8');
+  check('端到端：exit 0 + 生成 DASHBOARD.md', r.status === 0 && fs.existsSync(path.join(root, 'workflow', 'DASHBOARD.md')), `status=${r.status} ${(r.stdout || '') + (r.stderr || '')}`);
+  check('端到端：红绿灯行质量门「达标」+ 时长带 ✅', /达标[^]*质量门/.test(dash) && /✅[^]*关单时长带/.test(dash), dash.slice(0, 500));
+  check('端到端：时长取最早 done 行且 floor 日历天（multi=1 天；第二行 9 天不采纳；同日 0 天）',
+    dash.includes('| P50 | 1 天 |') && dash.includes('| max | 1 天 |') && /最慢 3 单：2026-09-01-multi\.md=1天、2026-10-01-same\.md=0天/.test(dash), dash);
+  check('端到端：无台账行跳过计数（noledger=1）+ 生成于戳 + 勿手改头', dash.includes('无台账行跳过（存量单） | 1 |') && dash.includes('生成于') && dash.includes('勿手改'), dash);
+  check('端到端：非 done intent 不入时长样本（open 不出现）', !dash.includes('2026-09-06-open'), dash);
+  // 幂等：重跑字节不变
+  const before = fs.readFileSync(path.join(root, 'workflow', 'DASHBOARD.md'), 'utf8');
+  spawnSync(process.execPath, [path.join(SCRIPT_DIR, 'gen-workflow-dashboard.mjs')], { cwd: root, encoding: 'utf8', env: { ...process.env, CHECK_LOOP_ROOT: root } });
+  check('端到端：重跑幂等（生成于戳同 ms 内可能变——除戳行外字节一致）',
+    before.split('\n').filter((l) => !l.includes('生成于')).join('\n') === dash.split('\n').filter((l) => !l.includes('生成于')).join('\n'));
+
+  // 空台账装户：无 delegations.md / 无 confirmations.jsonl → 优雅降级不炸
+  const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-dash-empty-'));
+  W(empty, 'workflow/intents/2026-10-01-x.md', INTENT('状态: done\n级别: L1\n日期: 2026-10-01\n模块: pipeline'));
+  const r2 = spawnSync(process.execPath, [path.join(SCRIPT_DIR, 'gen-workflow-dashboard.mjs')], {
+    cwd: empty, encoding: 'utf8', env: { ...process.env, CHECK_LOOP_ROOT: empty },
+  });
+  const dash2 = fs.readFileSync(path.join(empty, 'workflow', 'DASHBOARD.md'), 'utf8');
+  check('端到端：空台账装户 → exit 0 + ⚪ 降级（质量门无数据 / 时长无样本 / 跳过 1）',
+    r2.status === 0 && dash2.includes('⚪') && dash2.includes('暂无关单样本') && dash2.includes('跳过（存量单） | 1 |'), `status=${r2.status} ${dash2.slice(0, 300)}`);
+  fs.rmSync(root, { recursive: true, force: true });
+  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/policy.mjs

@@ -69,6 +69,25 @@ export const POLICIES = {
     riskLevelSince: '2026-10-01',
     verifySince: '2026-10-07', // 测试绿机器凭证生效日（2026-10-07 verify-evidence）；v1-v4 无此键 → 前置与对账整体跳过
   },
+  // 版本 6 = 版本 5 的全部键 + verifyDocSince（测试绿凭证与被证明对象的绑定日，2026-10-08 verify-doc-binding）。
+  // 背景（2026-10-08 verify-doc-binding）：v5 的凭证行只记 {ts, exitCode, suite, passed, failed}，
+  // **没有字段能承载「它是为哪一单落的」**，而两个消费方（confirm-doc 置 done 前置 / 检查 8 对账）
+  // 都只问「全仓任意一份 24h 内绿行」→ 跑一次 verify 就能给全仓任意一单的「测试绿」声明背书，
+  // 这是自证式验证的教科书形态（证据与被证明对象零绑定）。
+  // 本版本只加一个开关键：**缺键（v1-v5）时两个消费方维持 v5 的全局行为逐字不变**（存量装户与存量
+  // fixture 零变化、零新增告警）；本仓升 v6 后才按 doc 精确匹配。抄全键仍是铁律（见 v2 注释）。
+  6: {
+    moduleSince: '2026-09-22',
+    check14Since: '2026-09-26',
+    confirmDocsEffective: '2026-09-27',
+    confirmIncidentsEffective: '2026-09-28',
+    bindingTs: '2026-09-28',
+    check17UnclosedAfter: '0.8.0',
+    stageGateSince: '2026-09-29',
+    riskLevelSince: '2026-10-01',
+    verifySince: '2026-10-07',
+    verifyDocSince: '2026-10-08', // 凭证按 doc 绑定生效日；v1-v5 无此键 → 两个消费方维持 v5 全局行为
+  },
 };
 
 export function loadKitPolicy(root) {
@@ -90,17 +109,26 @@ export function auditEnabled(policy) {
   return policy.audit !== false;
 }
 
-// ---- 测试绿凭证判定（2026-10-07 verify-evidence）----
+// ---- 测试绿凭证判定（2026-10-07 verify-evidence；2026-10-08 verify-doc-binding 增 doc 绑定）----
 // 单源（confirm-doc done 前置与 check-loop 检查 8 对账共用——防两处窗口字面量漂移，N3 教训）：
-// hasFreshVerifyLine(lines, now)：verifications.jsonl 的行数组里是否存在「ts 距 now ≤ 24h 且
+// hasFreshVerifyLine(lines, now, doc)：verifications.jsonl 的行数组里是否存在「ts 距 now ≤ 24h 且
 // exitCode === 0」的绿行。坏行（非 JSON / 缺 ts）跳过不抛；窗口 24h = 覆盖「跑 verify → 跨会话/
 // 隔夜 → 次日关单」节奏（spec 2026-10-07-verify-evidence 论证）。
-export function hasFreshVerifyLine(lines, now = Date.now()) {
+//
+// doc 绑定（2026-10-08 verify-doc-binding，第三参）：
+//   doc 为空/缺省 → 逻辑与 2026-10-07 版**逐字相同**（全量行扫描）——v1-v5 装户走这条，零变化；
+//   doc 非空     → 额外要求该行 `e.doc === doc`（**精确等值**，不做前缀/子串/形态匹配——
+//                  沿 check8-digit-sha-misfire「文本启发式须可被实证兜底，禁以形态抢先分类」纪律）。
+//   为什么必须精确：放宽成「包含即认」等于给跨单背书开后门，那正是本单要消灭的漏洞。
+//   不带 doc 落账的行（CI 场景）**不给任何单背书**——doc 为 null 时 e.doc === doc 恒假。
+export function hasFreshVerifyLine(lines, now = Date.now(), doc = null) {
+  const byDoc = typeof doc === 'string' && doc !== '';
   for (const line of lines || []) {
     if (!line || !line.trim()) continue;
     try {
       const e = JSON.parse(line);
       if (e && e.exitCode === 0 && typeof e.ts === 'string') {
+        if (byDoc && e.doc !== doc) continue;
         const t = Date.parse(e.ts);
         if (Number.isFinite(t) && now - t <= 24 * 60 * 60 * 1000) return true;
       }

package/templates/_agents/scripts/verify.mjs

@@ -14,7 +14,13 @@
 // 且**不落测试绿凭证**（凭证语义 = 测试真跑绿，跳过即无凭证，防假绿），并提示用
 // --test-cmd "<项目测试命令>" 指定；显式 --test-cmd 不受此判定影响（2026-10-07 papercut）。
 // 测试：node templates/_agents/scripts/verify.test.mjs（--test-cmd 注入假命令 + CHECK_LOOP_ROOT 注入夹具，不触真实 npm test 与 workflow）
-// 用法：node .agents/scripts/verify.mjs [--test-cmd "<shell 命令>"]（--test-cmd 用于测试注入，或在无根 package.json 的装户仓指定项目测试命令）
+// --doc 凭证绑定（2026-10-08 verify-doc-binding）：落账行增 `doc` 字段，写入**相对仓库根的 posix 形态**
+//   （win32 反斜杠 / posix 斜杠 / 绝对路径三种写法经 resolve+relative+分隔符归一后落同一值），使凭证
+//   与被证明的那一单绑定。不带 --doc 时仍落行但**不写该键**——CI（kit-ci.yml）无单次上下文，照常记录
+//   事实；这样的行不给任何单背书（消费方按 doc 精确匹配时 e.doc 为 undefined 恒不命中）。
+// 用法：node .agents/scripts/verify.mjs [--test-cmd "<shell 命令>"] [--doc <本单 workflow 路径>]
+//   （--test-cmd 用于测试注入，或在无根 package.json 的装户仓指定项目测试命令；
+//     --doc 把凭证绑到本单，如 --doc workflow/intents/2026-10-08-x.md）
 import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
@@ -27,6 +33,22 @@ const testCmd = explicitTestCmd ?? 'npm test';
 const checkLoop = path.join(SCRIPT_DIR, 'check-loop.mjs');
 const ROOT = process.env.CHECK_LOOP_ROOT || path.resolve(SCRIPT_DIR, '..', '..');
 
+// --doc 解析（沿 --test-cmd 同款取下一 argv 的写法；缺值报用法错误 exit 1 与 --test-cmd 对称）。
+// 归一基准 = **ROOT**（不是 cwd）——消费方两处都以仓库根为基准（check-loop 检查 8 用
+// path.relative(ROOT, intent)；confirm-doc 的 docRelOf 用 path.resolve(root, doc)）。若这里按 cwd
+// 解析而进程不在仓库根（CI / 钩子 / CHECK_LOOP_ROOT 注入夹具），落下的 doc 会是跨目录长路径，
+// 凭证永远匹配不上——**基准必须三处同源**。
+// 不校验目标文件是否存在：凭证记录的是「跑了什么」而非「被证明对象是否有效」，存在性校验属裁决，
+// 越界（沿本件「只编排不裁决」语义）。
+if (args.includes('--doc') && !args[args.indexOf('--doc') + 1]) {
+  console.error('verify: --doc 缺值——用法 node .agents/scripts/verify.mjs [--test-cmd "<shell 命令>"] [--doc <本单 workflow 路径>]');
+  process.exit(1);
+}
+const docArg = args.includes('--doc') ? args[args.indexOf('--doc') + 1] : null;
+const docRel = docArg
+  ? path.relative(ROOT, path.resolve(ROOT, docArg)).split(path.sep).join('/')
+  : null;
+
 // 装户仓判定：默认命令只在**当前目录**有 package.json 时才跑（npm test 亦在该目录执行）。
 // 跳过时后续不落测试绿凭证（见文末落账段）。
 const hasRootPackageJson = fs.existsSync(path.join(process.cwd(), 'package.json'));
@@ -66,9 +88,12 @@ try {
     const entry = { ts: new Date().toISOString(), exitCode: 0, suite: 'npm test' };
     if (m) { entry.passed = Number(m[1]); entry.failed = Number(m[2]); }
     if (process.env.PIPELINE_RUN_ID) entry.runId = process.env.PIPELINE_RUN_ID;
+    // doc 键：未传 --doc 时**不写该键**（不是写 null）——消费方按 doc 精确匹配，undefined 与 null 都恒不命中，
+    // 但缺键让「本行没有绑定对象」这件事在台账盘面上直接可读。
+    if (docRel) entry.doc = docRel;
     fs.mkdirSync(path.join(ROOT, '.agents'), { recursive: true });
     fs.appendFileSync(path.join(ROOT, '.agents', 'verifications.jsonl'), `${JSON.stringify(entry)}\n`);
-    console.log(`[verify] 🧾 测试绿凭证已落账 verifications.jsonl${entry.passed !== undefined ? `（PASS ${entry.passed} / FAIL ${entry.failed}）` : ''}`);
+    console.log(`[verify] 🧾 测试绿凭证已落账 verifications.jsonl${entry.passed !== undefined ? `（PASS ${entry.passed} / FAIL ${entry.failed}）` : ''}${docRel ? ` 绑定本单 ${docRel}` : '（未带 --doc：不给任何单背书）'}`);
   }
 } catch (e) {
   console.error(`[verify] ⚠️ 凭证落账失败（${e.code || e.message}）——不阻断，关单门前置将按无凭证告警`);

package/templates/_agents/scripts/verify.test.mjs

@@ -132,6 +132,59 @@ const run = (argv, opts = {}) => spawnSync(process.execPath, [VERIFY, ...argv],
  fs.rmSync(bare, { recursive: true, force: true });
 }
 
+// ---- 场景 8：--doc 凭证绑定（2026-10-08 verify-doc-binding）----
+// ① 带 --doc → 末行含 doc 且为规范化 posix 相对路径；② 不带 → 末行**无 doc 键**（不是 null）；
+// ③ win32 反斜杠 / posix / 绝对路径三种写法落同一值（归一是本单的地基，错一处=凭证永远匹配不上）；
+// ④ 缺值 → exit 1 用法错误；⑤ 跳过步骤 1 时即便带 --doc 仍不落账（防假绿语义不得被 --doc 破坏）。
+{
+  const readLast = (root) => {
+    const p = path.join(root, '.agents', 'verifications.jsonl');
+    if (!fs.existsSync(p)) return null;
+    const lines = fs.readFileSync(p, 'utf8').trim().split('\n').filter(Boolean);
+    return lines.length ? JSON.parse(lines[lines.length - 1]) : null;
+  };
+
+  const rootA = mkfix();
+  const rel = 'workflow/intents/2026-10-08-demo.md';
+  const rA = run(['--test-cmd', `node ${mkCmd(0, '合计: PASS 3 / FAIL 0\n')}`, '--doc', rel],
+    { env: { ...process.env, CHECK_LOOP_ROOT: rootA } });
+  const eA = readLast(rootA);
+  check('场景 8①：带 --doc → 末行含 doc 且为 posix 相对路径',
+    rA.status === 0 && eA && eA.doc === rel && rA.stdout.includes('绑定本单'), `exit=${rA.status} entry=${JSON.stringify(eA)}`);
+
+  const rootB = mkfix();
+  run(['--test-cmd', `node ${mkCmd(0)}`], { env: { ...process.env, CHECK_LOOP_ROOT: rootB } });
+  const eB = readLast(rootB);
+  check('场景 8②：不带 --doc → 仍落行但**无 doc 键**（CI 路径不退化；此行不给任何单背书）',
+    eB && eB.exitCode === 0 && !('doc' in eB) && eB.suite === 'npm test', JSON.stringify(eB));
+
+  // 归一：cwd 设为仓库根时，win32 反斜杠 / posix / 绝对路径三种写法须落同一值
+  const rootC = mkfix();
+  const abs = path.join(rootC, rel);
+  const winStyle = rel.split('/').join(path.sep);
+  const rC1 = run(['--test-cmd', `node ${mkCmd(0)}`, '--doc', winStyle], { cwd: rootC, env: { ...process.env, CHECK_LOOP_ROOT: rootC } });
+  const eC1 = readLast(rootC);
+  const rC2 = run(['--test-cmd', `node ${mkCmd(0)}`, '--doc', abs], { cwd: rootC, env: { ...process.env, CHECK_LOOP_ROOT: rootC } });
+  const eC2 = readLast(rootC);
+  check('场景 8③：反斜杠 / posix / 绝对路径三种写法落同一 doc 值（归一是地基）',
+    eC1 && eC1.doc === rel && eC2 && eC2.doc === rel, `win=${JSON.stringify(eC1 && eC1.doc)} abs=${JSON.stringify(eC2 && eC2.doc)}`);
+
+  const rootD = mkfix();
+  const rD = run(['--test-cmd', `node ${mkCmd(0)}`, '--doc'], { env: { ...process.env, CHECK_LOOP_ROOT: rootD } });
+  check('场景 8④：--doc 缺值 → exit 1 + 用法提示',
+    rD.status === 1 && /--doc 缺值/.test(rD.stderr), `exit=${rD.status} ${rD.stderr}`);
+
+  const rootE = mkfix();
+  const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-bare-doc-'));
+  const rE = run(['--doc', rel], { cwd: bare, env: { ...process.env, CHECK_LOOP_ROOT: rootE } });
+  check('场景 8⑤：步骤 1 跳过时即便带 --doc 仍不落账（防假绿语义不被 --doc 破坏）',
+    rE.status === 0 && !fs.existsSync(path.join(rootE, '.agents', 'verifications.jsonl')) && rE.stdout.includes('不落测试绿凭证'),
+    `exit=${rE.status} ${rE.stdout}`);
+
+  for (const r of [rootA, rootB, rootC, rootD, rootE]) fs.rmSync(r, { recursive: true, force: true });
+  fs.rmSync(bare, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log('\n用法：node templates/_agents/scripts/verify.test.mjs');

package/templates/_github/workflows/kit-ci.yml

@@ -0,0 +1,28 @@
+# kit-ci —— agentic-flow-kit 装户远端门（GitHub Actions 薄模板，2026-10-07 adopter-ci-github）
+# 语义：本地 git hooks 可被 --no-verify / 未配 hooksPath 的克隆绕过——本工作流在 GitHub runner 上复跑
+# 统一入口 node .agents/scripts/verify.mjs（测试【有根 package.json 才跑】+ check-loop），任一非零即红；
+# 不在 YAML 里复制门禁逻辑（本地/远端单源，防口径漂移）。
+# 本文件归装户自持（owned）：触发分支 / node 版本 / 测试命令可自改，flow-kit sync 永不覆盖。
+# 装户仓工程在子目录（根无 package.json）时 verify 会跳过测试——改用
+#   node .agents/scripts/verify.mjs --test-cmd "<项目测试命令>"
+# 非 GitHub 托管（TFS / Azure DevOps / Jenkins…）可删除本文件：等价远端门 = 同入口命令 + 服务端分支策略。
+# ⚠️ 真正的「门」在服务端：Settings → Branches → branch protection 勾「要求 PR + 状态检查绿才可合并」
+# ——该配置带不进仓库文件，一次性人工动作，机器不校验。
+name: kit-ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22   # 按项目 engines 调整（kit 引擎要求 >=18）
+      - name: 安装依赖（有根 package.json 才跑；私有源在此加 registry 配置）
+        if: hashFiles('package.json') != ''
+        run: npm ci || npm install
+      - name: 远端门（测试 + 闭环校验）
+        run: node .agents/scripts/verify.mjs