agentic-flow-kit 1.7.15 → 1.8.0

package/templates/_agents/scripts/judgment-ledger.mjs

@@ -0,0 +1,65 @@
+// judgment-ledger.mjs — check-loop 判定流水落账（2026-10-11 judgment-ledger，灰度消费端数据底座）
+// 背景：机制月度对账原为「人工 grep check-loop 输出」；advisory→hard 升格与退役判定
+// 均缺 per-rule 判定流水（时间戳+结论）。本模块把每次 check-loop 真实运行追加为一行 per-rule 计数
+// 到 .agents/judgments.jsonl（本地，gitignore——「本机机器事实不跨机共享」口径，同 verifications.jsonl）。
+// 消费：node .agents/scripts/agg-judgments.mjs（月度×规则计数）；mechanism-registry 月度对账直接查账
+// （机制登记表模板 .agents/mechanism-registry.md）。
+// 诚实边界：非签名链（同 verify-evidence）——本地追加可被改，事后对质靠 git 历史与确认台账。
+// fail-open：落账失败只打 stderr，不改变门禁裁决（观测面不得挡住裁决面）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const LEDGER_REL = path.join('.agents', 'judgments.jsonl');
+
+// tallyJudgments(entries)：'- [WARN 标签] …' → {rule,level:'WARN'}；'- [标签] …' → {rule,level:'BLOCK'}；
+// 无括号标签行 → {rule:'未标注', level:按来源}。输出按 rule 字典序的 {rule,level,count} 数组（确定性，测试可断言）。
+export function tallyJudgments(blockers = [], warnings = []) {
+  const tally = new Map();
+  const add = (raw, fallbackLevel) => {
+    const m = String(raw).match(/^\s*-\s*\[([^\]]+)\]/);
+    let rule = '未标注';
+    let level = fallbackLevel;
+    if (m) {
+      const tag = m[1].trim();
+      if (/^WARN\b/.test(tag)) { level = 'WARN'; rule = tag.replace(/^WARN\s*/, ''); }
+      else { rule = tag; }
+    }
+    const key = `${level}\u0000${rule}`;
+    const cur = tally.get(key) || { rule, level, count: 0 };
+    cur.count++;
+    tally.set(key, cur);
+  };
+  for (const b of blockers || []) add(b, 'BLOCK');
+  for (const w of warnings || []) add(w, 'WARN');
+  return [...tally.values()].sort((a, b) => (a.level + a.rule).localeCompare(b.level + b.rule));
+}
+
+const shortRev = (root) => {
+  try {
+    const r = spawnSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' });
+    return r.status === 0 ? String(r.stdout).trim() || null : null;
+  } catch {
+    return null;
+  }
+};
+
+// recordRun({ root, mode, blockers, warnings, now })：追加一行运行判定；守卫 fixture（CHECK_LOOP_ROOT）
+// 与显式关闭（CHECK_LOOP_NO_LEDGER）；任何失败 fail-open（stderr 一行，不 throw、不改 exit code）。
+export function recordRun({ root, mode, blockers, warnings, now = new Date() }) {
+  try {
+    if (process.env.CHECK_LOOP_ROOT || process.env.CHECK_LOOP_NO_LEDGER) return;
+    const row = {
+      ts: now.toISOString(),
+      mode: mode || 'hard',
+      rev: shortRev(root),
+      blockers: (blockers || []).length,
+      warnings: (warnings || []).length,
+      rules: tallyJudgments(blockers, warnings),
+    };
+    fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+    fs.appendFileSync(path.join(root, LEDGER_REL), `${JSON.stringify(row)}\n`);
+  } catch (err) {
+    console.error(`judgment-ledger: 落账失败（不阻断门禁）——${err.code || err.message}`);
+  }
+}

package/templates/_agents/scripts/judgment-ledger.test.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// judgment-ledger.test.mjs — 判定流水落账套件（2026-10-11 judgment-ledger）
+// 纯函数 tallyJudgments 进程内断言 + recordRun 落账行为（临时根目录 + 环境守卫）。
+// 守卫口径：CHECK_LOOP_ROOT（fixture 模式）/ CHECK_LOOP_NO_LEDGER 任一在即不落账——
+// 进程内切换环境变量须保存/恢复，防污染同进程后续用例。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { tallyJudgments, recordRun, LEDGER_REL } from './judgment-ledger.mjs';
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? '\n      ' + detail : ''}`); }
+};
+
+// ---- S1 tallyJudgments：标签解析 / 级别分流 / 计数 / 确定性排序 ----
+{
+  const out = tallyJudgments(
+    ['- [配对断裂] incident 缺 plan:x.md', '- [配对断裂] incident 缺 plan:y.md', '- [回路断档] 选「是」未指明 intent'],
+    ['- [WARN 三件套不全] x.md 缺之 2', '- [WARN 归因缺字段] x.md 缺「来源:」', '- [WARN 三件套不全] y.md 缺之 3', '无标签散行'],
+  );
+  check('S1 BLOCK/WARN 分流计数', out.some((r) => r.rule === '配对断裂' && r.level === 'BLOCK' && r.count === 2)
+    && out.some((r) => r.rule === '回路断档' && r.level === 'BLOCK' && r.count === 1)
+    && out.some((r) => r.rule === '三件套不全' && r.level === 'WARN' && r.count === 2)
+    && out.some((r) => r.rule === '归因缺字段' && r.level === 'WARN' && r.count === 1), JSON.stringify(out));
+  check('S1 无标签行归「未标注」WARN', out.some((r) => r.rule === '未标注' && r.level === 'WARN' && r.count === 1), JSON.stringify(out));
+  const keys = out.map((r) => r.level + r.rule);
+  // 与实现同款 localeCompare 排序比对——被测不变量是「确定性」而非特定 collation（中文 locale 与码位排序不同）
+  const sorted = [...keys].sort((a, b) => a.localeCompare(b));
+  check('S1 输出按 level+rule 排序（确定性）', JSON.stringify(keys) === JSON.stringify(sorted), JSON.stringify(keys));
+  check('S1 空入参 → 空数组', tallyJudgments([], []).length === 0);
+}
+
+// ---- S2 recordRun：真落账（临时根，rev 为 null 因非 git 目录）----
+{
+  const saved = { loopRoot: process.env.CHECK_LOOP_ROOT, noLedger: process.env.CHECK_LOOP_NO_LEDGER };
+  delete process.env.CHECK_LOOP_ROOT;
+  delete process.env.CHECK_LOOP_NO_LEDGER;
+  try {
+    const T = fs.mkdtempSync(path.join(os.tmpdir(), 'jledger-'));
+    const now = new Date('2026-10-11T01:02:03.000Z');
+    recordRun({ root: T, mode: 'hygiene', blockers: ['- [配对断裂] a'], warnings: ['- [WARN 归因缺字段] b'], now });
+    const p = path.join(T, LEDGER_REL);
+    const rows = fs.existsSync(p) ? fs.readFileSync(p, 'utf8').split(/\r?\n/).filter(Boolean).map((l) => JSON.parse(l)) : [];
+    check('S2 追加一行且字段齐（ts/mode/rev/计数/rules）',
+      rows.length === 1 && rows[0].ts === '2026-10-11T01:02:03.000Z' && rows[0].mode === 'hygiene'
+      && rows[0].blockers === 1 && rows[0].warnings === 1
+      && Array.isArray(rows[0].rules) && rows[0].rules.length === 2, JSON.stringify(rows));
+    recordRun({ root: T, mode: 'hard', blockers: [], warnings: [], now });
+    const lines = fs.readFileSync(p, 'utf8').split(/\r?\n/).filter(Boolean);
+    check('S2 二次调用追加不覆盖（append-only）', lines.length === 2, String(lines.length));
+  } finally {
+    if (saved.loopRoot !== undefined) process.env.CHECK_LOOP_ROOT = saved.loopRoot;
+    if (saved.noLedger !== undefined) process.env.CHECK_LOOP_NO_LEDGER = saved.noLedger;
+  }
+}
+
+// ---- S3 双守卫：CHECK_LOOP_ROOT / CHECK_LOOP_NO_LEDGER 任一在 → 不落账 ----
+{
+  const saved = { loopRoot: process.env.CHECK_LOOP_ROOT, noLedger: process.env.CHECK_LOOP_NO_LEDGER };
+  try {
+    for (const guard of ['CHECK_LOOP_ROOT', 'CHECK_LOOP_NO_LEDGER']) {
+      delete process.env.CHECK_LOOP_ROOT;
+      delete process.env.CHECK_LOOP_NO_LEDGER;
+      process.env[guard] = '1';
+      const T = fs.mkdtempSync(path.join(os.tmpdir(), 'jledger-guard-'));
+      recordRun({ root: T, mode: 'hard', blockers: [], warnings: [] });
+      check(`S3 ${guard} 在 → 不落账`, !fs.existsSync(path.join(T, LEDGER_REL)));
+    }
+  } finally {
+    if (saved.loopRoot !== undefined) process.env.CHECK_LOOP_ROOT = saved.loopRoot; else delete process.env.CHECK_LOOP_ROOT;
+    if (saved.noLedger !== undefined) process.env.CHECK_LOOP_NO_LEDGER = saved.noLedger; else delete process.env.CHECK_LOOP_NO_LEDGER;
+  }
+}
+
+// ---- S4 落账失败 fail-open（root 指向文件而非目录 → append 必败，只 stderr 不 throw）----
+{
+  const saved = { loopRoot: process.env.CHECK_LOOP_ROOT, noLedger: process.env.CHECK_LOOP_NO_LEDGER };
+  delete process.env.CHECK_LOOP_ROOT;
+  delete process.env.CHECK_LOOP_NO_LEDGER;
+  try {
+    const T = fs.mkdtempSync(path.join(os.tmpdir(), 'jledger-bad-'));
+    const filePath = path.join(T, '.agents'); // 占住 .agents 为普通文件 → mkdirSync 必败
+    fs.writeFileSync(filePath, 'not a dir');
+    let threw = false;
+    try {
+      recordRun({ root: T, mode: 'hard', blockers: [], warnings: [] });
+    } catch {
+      threw = true;
+    }
+    check('S4 落账失败不 throw（fail-open）', threw === false);
+  } finally {
+    if (saved.loopRoot !== undefined) process.env.CHECK_LOOP_ROOT = saved.loopRoot; else delete process.env.CHECK_LOOP_ROOT;
+    if (saved.noLedger !== undefined) process.env.CHECK_LOOP_NO_LEDGER = saved.noLedger; else delete process.env.CHECK_LOOP_NO_LEDGER;
+  }
+}
+
+// ---- S5 端到端：真实 check-loop.mjs fixture 运行不落账（CHECK_LOOP_ROOT 守卫在 spawn 态同样生效）----
+{
+  const T = fs.mkdtempSync(path.join(os.tmpdir(), 'jledger-e2e-'));
+  for (const s of ['intents', 'specs', 'plans', 'incidents']) fs.mkdirSync(path.join(T, 'workflow', s), { recursive: true });
+  fs.mkdirSync(path.join(T, '.agents'), { recursive: true });
+  // 枚举单源随夹具内联（kit 契约：.agents/workflow-enums.txt，缺文件 fail-loud）——键集沿 verify.test.mjs mkfix 同款
+  fs.writeFileSync(path.join(T, '.agents', 'workflow-enums.txt'), [
+    'doc.status.all=draft approved done superseded cancelled',
+    'doc.status.confirmed=approved done superseded cancelled',
+    'doc.status.active=draft approved',
+    'doc.status.terminal=done superseded cancelled',
+    'doc.status.abandoned=superseded cancelled',
+    'incident.status.all=open fixed closed',
+    'incident.status.active=open',
+    'level.all=L1 L2 L3',
+    '',
+  ].join('\n'), 'utf8');
+  const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+  // 裸跑=默认硬门（2026-10-13 分道，kit 与源仓同构 hard/hygiene/all 三面）——落账守卫断言与运行面无关，裸跑即可
+  const r = spawnSync(process.execPath, [path.join(SCRIPT_DIR, 'check-loop.mjs')],
+    { env: { ...process.env, CHECK_LOOP_ROOT: T }, cwd: T, encoding: 'utf8' });
+  check('S5 fixture 态 spawn 运行不落账（守卫在子进程同样生效）',
+    !fs.existsSync(path.join(T, LEDGER_REL)), `exit=${r.status} ${r.stderr || ''}`);
+  fs.rmSync(T, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

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

@@ -5,6 +5,7 @@
 // 语料与口径
 //   workflow（流程留痕）：只搜 frontmatter + H1 + 指定节（背景 / 目标 / 根因 / 复盘三件套 / 验收标准 / 影响面），
 //     默认全状态可命中、活跃（draft/approved/open）排序 ×1.3 优先；输出带「节名 + 行号」便于节级读取。
+//     语料面含归档批次 workflow/archive/<批次>/<type>/（B10a 自源仓随动回灌）——归档件仍可检索（防复发不丢历史）。
 //   wiki（领域知识）：沿用 2026-09-21 降噪口径——默认跳过 .json/.csv、*.visual-check.* 与 >180KB bulk 文件。
 //   两侧排序均为 命中数/√文件KB（防大文件靠体量霸榜）；`-n` 为每语料展示上限。
 // 结构缓存（2026-09-23 intent kb-search-structure-cache）：可检索子集预提取进 .agents/cache/kb-index.json，
@@ -231,9 +232,22 @@ function saveCache() {
 function searchWorkflow(words) {
   const results = [];
   for (const type of (typeFilter || DOC_TYPES)) {
-    const dir = path.join('workflow', type);
-    if (!fs.existsSync(dir)) continue;
-    for (const f of fs.readdirSync(dir)) {
+    // 活跃目录 + 归档批次（workflow/archive/<批次>/<type>/，2026-10-09；B10a 自源仓随动回灌）——
+    // 归档件仍可检索（防复发不丢历史），标签用相对 workflow/ 的路径，活跃目录标签与旧口径逐字一致。
+    // 缓存键/失效语义随动：归档件按自身路径独立入缓存键，git mv 后旧活跃路径键由 saveCache
+    // 的 stat 清扫回收（[mtimeMs,size] 逐文件失效不变）；可检索子集提取函数未变 → 口径指纹不变。
+    const dirs = [path.join('workflow', type)];
+    const arcRoot = path.join('workflow', 'archive');
+    if (fs.existsSync(arcRoot)) {
+      for (const batch of fs.readdirSync(arcRoot)) {
+        const d = path.join(arcRoot, batch, type);
+        if (fs.existsSync(d)) dirs.push(d);
+      }
+    }
+    for (const dir of dirs) {
+      if (!fs.existsSync(dir)) continue;
+      const rel = path.relative('workflow', dir).split(path.sep).join('/');
+      for (const f of fs.readdirSync(dir)) {
       if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
       const p = path.join(dir, f);
       const e = cachedEntry(p, 'wf', () => {
@@ -252,10 +266,11 @@ function searchWorkflow(words) {
       const kb = e.st[1] / 1024;
       const active = ACTIVE_STATUS.includes(status);
       results.push({
-        file: `${type}/${f}`, title: e.title || '', status, level: meta['级别'] || '—', module,
+        file: `${rel}/${f}`, title: e.title || '', status, level: meta['级别'] || '—', module,
         total: hits.total, shown: hits.shown, kb,
         score: (hits.total / Math.sqrt(Math.max(kb, 0.1))) * (active ? 1.3 : 1),
       });
+      }
     }
   }
   return results.sort((a, b) => b.score - a.score);

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

@@ -258,6 +258,39 @@ const files = (out) => (out.match(/^📄 (workflow\/\S+)/gm) || []).map((l) => l
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 13：归档扩面（B10a 自源仓随动回灌）——workflow/archive/<批次>/<type>/ 参与检索 ----
+//    归档件命中带归档路径标签；无归档语料时行为与旧口径逐字一致；缓存键随动（归档件独立入键）
+{
+  const root = mkfix();
+  // 造归档批次：与活跃件同词命中（含终态件 frontmatter，可命中）
+  fs.mkdirSync(path.join(root, 'workflow', 'archive', '2026-09', 'plans'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'workflow', 'archive', '2026-09', 'plans', '2026-09-01-arch.md'),
+    doc('状态: done\n级别: L1\n模块: purchase', 'PLAN — 归档件', [['目标', '- 归档批次里的编码模板历史档']]), 'utf8');
+  const r = run(root, ['--scope', 'workflow', '编码模板']);
+  check('场景 13a 归档件参与检索且带归档路径标签',
+    r.status === 0 && files(r.stdout).some((f) => f === 'workflow/archive/2026-09/plans/2026-09-01-arch.md'), r.stdout);
+  check('场景 13b 活跃目录标签与旧口径逐字一致（不带 archive 段）',
+    files(r.stdout).some((f) => f === 'workflow/plans/2026-09-20-ccc.md'), files(r.stdout).join('\n'));
+  // 归档件状态 done → --status active 时被状态过滤排除（过滤口径对归档件照常生效）
+  const a = run(root, ['--scope', 'workflow', '--status', 'active', '编码模板']);
+  check('场景 13c --status active 排除终态归档件',
+    !a.stdout.includes('2026-09-01-arch.md') && a.stdout.includes('2026-09-21-bbb.md'), a.stdout);
+  // 缓存随动：warm 复跑与冷扫逐字节一致（归档件已入缓存键）
+  const warm = run(root, ['--scope', 'workflow', '编码模板']);
+  check('场景 13d 归档件入缓存后 warm ≡ 前次输出（逐字节）', warm.status === 0 && warm.stdout === r.stdout,
+    `warm:\n${warm.stdout}\nfirst:\n${r.stdout}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 14：无归档语料 → 行为不变（对照锚——扩面不得扰动既有输出）----
+{
+  const root = mkfix(); // mkfix 不建 workflow/archive/
+  const before = run(root, ['--scope', 'workflow', '编码模板']);
+  check('场景 14 无 archive 目录时输出照旧（3 篇活跃件命中）',
+    before.status === 0 && files(before.stdout).length === 3 && !before.stdout.includes('archive/'), before.stdout);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log(`\n${USAGE}`);

package/templates/_agents/scripts/lane-surface-audit.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// lane-surface-audit.mjs — L2 触达面闭集防漂移审计（advisory 工具，恒 exit 0；2026-10-13 自
+//   Shipyard.Material 参考实现回灌，源仓沿革留痕在包源仓 git 历史与 CHANGELOG——装户径不引实例路径）
+// 问题：lane-surfaces.txt 的 ERE 闭集靠人工维护——新共享契约面若未登记，判低拦截对新面静默失效。
+//   本审计反着问：**近窗口内 L2/L3 任务实际反复触及、却无任何文件被面清单命中的目录** = 候选漏登面，
+//   供人工评估补登（不建议自动写清单——高频触及 ≠ 契约面，机器不猜语义）。
+// 归因代理：提交触及某入口/事故文档的提交 = 该任务的落地提交（三件套随代码同一提交纪律），
+//   取这些提交里的代码文件（剔 workflow/、.agents/、.githooks/、wiki/、根 AGENTS.md）作「任务触及面」。
+//   已知粗度：任务中途未触文档的纯代码提交会被漏计（审计低招，不是执法——宁可漏报不误报）。
+// 判据：目录签名（dirname 前 3 段）被 ≥ --min（默认 3）个**不同** L2/L3 文档触及，且该签名下
+//   观测到的文件无一命中 ERE → 候选。被命中的文件所在目录不进候选（已覆盖）。
+// 用法：node .agents/scripts/lane-surface-audit.mjs [--since <YYYY-MM-DD>] [--min <N>] [--root <dir>]
+//   --since 缺省 = 今天−30 天。输出候选清单；无候选打印一行「无漂移信号」。
+// 时机：月度手跑（登记位 = .agents/lane-surfaces.txt 文件头）；改共享契约频繁期可随时手跑。
+// 测试：node .agents/scripts/lane-surface-audit.test.mjs（git fixture 注入）
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const argv = process.argv.slice(2);
+const argOf = (k) => {
+  const i = argv.indexOf(k);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : '';
+};
+const ROOT = argOf('--root') || (() => {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: process.cwd(), encoding: 'utf8' });
+  return r.status === 0 ? String(r.stdout).trim() : '';
+})() || process.cwd();
+const SINCE = argOf('--since') || new Date(Date.now() - 30 * 86400_000).toISOString().slice(0, 10);
+const MIN = Number(argOf('--min')) || 3;
+
+const gitOut = (args) => {
+  const r = spawnSync('git', ['-c', 'core.quotepath=off', ...args], { cwd: ROOT, encoding: 'utf8' });
+  return r.status === 0 ? String(r.stdout || '') : '';
+};
+
+// 面清单（解析同 check-lane-surface.mjs：逐行 ERE，# 注释与空行忽略——段标题行同为注释，不参与命中）
+const loadPatterns = () => {
+  const file = path.join(ROOT, '.agents', 'lane-surfaces.txt');
+  if (!fs.existsSync(file)) return [];
+  return fs.readFileSync(file, 'utf8')
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'))
+    .map((l) => { try { return new RegExp(l); } catch { return null; } })
+    .filter(Boolean);
+};
+const patterns = loadPatterns();
+const isCovered = (p) => patterns.some((re) => re.test(p));
+
+// frontmatter 读取（CRLF 容忍，同 check-lane-surface.fmOf）
+const fmOf = (file) => {
+  const fm = {};
+  let lines;
+  try { lines = fs.readFileSync(file, 'utf8').split(/\r?\n/); } catch { return fm; }
+  if (!/^---\s*$/.test(lines[0] || '')) return fm;
+  for (let i = 1; i < lines.length; i++) {
+    if (/^---\s*$/.test(lines[i])) break;
+    const m = lines[i].match(/^([^:]+):\s*(.*)$/);
+    if (m) fm[m[1].trim()] = m[2].trim();
+  }
+  return fm;
+};
+
+// 1) 窗口内 L2/L3 文档（任何状态——审计覆盖已关单历史；日期键 intent=日期 / incident=发现）
+const docs = [];
+for (const [dir, dateKey] of [['intents', '日期'], ['incidents', '发现']]) {
+  const dirPath = path.join(ROOT, 'workflow', dir);
+  if (!fs.existsSync(dirPath)) continue;
+  for (const f of fs.readdirSync(dirPath).sort()) {
+    if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
+    const fm = fmOf(path.join(dirPath, f));
+    if ((fm['级别'] || '') !== 'L2' && (fm['级别'] || '') !== 'L3') continue;
+    if ((fm[dateKey] || '') < SINCE) continue;
+    docs.push(`workflow/${dir}/${f}`);
+  }
+}
+if (!docs.length) {
+  console.log(`[lane-audit] 窗口（${SINCE} 起）内无 L2/L3 文档——无审计面。`);
+  process.exit(0);
+}
+
+// 2) 一遍 git log 取 (commit → files) 与文档↔提交关联（--name-only 块解析；doc 路径含非 ASCII 须 quotepath=off）
+const log = gitOut(['log', '--name-only', '--format=%H', '--', ...docs]);
+if (!log) {
+  console.error('[lane-audit] git log 不可用（非 git 环境或无历史）——跳过审计。');
+  process.exit(0);
+}
+const filesByDoc = new Map(); // doc → Set(代码文件)
+let commit = '';
+const commitsForDoc = new Map(); // doc → Set(commit)
+for (const line of log.split(/\r?\n/)) {
+  if (!line.trim()) continue;
+  if (/^[0-9a-f]{40}$/.test(line)) { commit = line; continue; }
+  const p = line.replace(/"/g, ''); // quotepath=off 已关转义，防御性去引号
+  if (docs.includes(p)) {
+    if (!commitsForDoc.has(p)) commitsForDoc.set(p, new Set());
+    commitsForDoc.get(p).add(commit);
+  }
+}
+for (const [doc, commits] of commitsForDoc) {
+  const set = new Set();
+  for (const c of commits) {
+    for (const f of gitOut(['show', '--name-only', '--format=', c]).split(/\r?\n/).filter(Boolean)) {
+      const fp = f.replace(/"/g, '');
+      if (/^(workflow|\.agents|\.githooks|wiki)\//.test(fp) || /\.md$/.test(fp) || fp === 'AGENTS.md') continue;
+      set.add(fp);
+    }
+  }
+  filesByDoc.set(doc, set);
+}
+
+// 3) 目录签名聚合（dirname 前 3 段）；仅聚合「未被 ERE 命中」的文件；按不同文档数计
+const sigOf = (fp) => {
+  const parts = path.posix.dirname(fp.replace(/\\/g, '/')).split('/');
+  return parts.slice(0, 3).join('/');
+};
+const docsBySig = new Map(); // sig → Set(doc)
+const samplesBySig = new Map(); // sig → Set(file)
+for (const [doc, files] of filesByDoc) {
+  for (const fp of files) {
+    if (isCovered(fp)) continue;
+    const sig = sigOf(fp);
+    if (!docsBySig.has(sig)) { docsBySig.set(sig, new Set()); samplesBySig.set(sig, new Set()); }
+    docsBySig.get(sig).add(doc);
+    samplesBySig.get(sig).add(fp);
+  }
+}
+const candidates = [...docsBySig.entries()]
+  .filter(([, ds]) => ds.size >= MIN)
+  .sort((a, b) => b[1].size - a[1].size);
+
+if (!candidates.length) {
+  console.log(`[lane-audit] ✅ 无漂移信号——窗口（${SINCE} 起）${docs.length} 份 L2/L3 文档的反复触及目录均被面清单覆盖（或未达阈值 ${MIN}）。`);
+  process.exit(0);
+}
+console.log(`[lane-audit] ⚠️ 候选漏登面 ${candidates.length} 个（窗口 ${SINCE} 起 / 阈值 ≥${MIN} 个不同 L2/L3 任务 / ERE 均未命中）——人工评估是否补登 .agents/lane-surfaces.txt：`);
+for (const [sig, ds] of candidates) {
+  const samples = [...samplesBySig.get(sig)].slice(0, 3).join(' ');
+  console.log(`  - ${sig}（${ds.size} 个任务；示例 ${samples}）`);
+}
+console.log('  判据提醒：仅「一处定义、多处消费」的契约/规则面才应登记（判据单源 .agents/scripts/level-criteria.mjs 的 L2_SURFACES）——高频触及 ≠ 契约面。');
+process.exit(0);

package/templates/_agents/scripts/lane-surface-audit.test.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// lane-surface-audit.test.mjs — 闭集审计 fixture 套件（2026-10-13 自 Shipyard.Material 参考实现回灌）
+// 方法：临时 git 仓构造「L2 文档 + 同笔代码提交」历史，断言候选目录判定（阈值/ERE 覆盖排除/无候选静默）。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SCRIPT = path.join(SCRIPT_DIR, 'lane-surface-audit.mjs');
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? '\n      ' + detail : ''}`); }
+};
+
+const mkrepo = () => {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'lane-audit-test-'));
+  const g = (a) => spawnSync('git', ['-c', 'core.quotepath=off', ...a], { cwd: d, encoding: 'utf8' });
+  g(['init', '-q', '-b', 'main']); g(['config', 'user.email', 't@t']); g(['config', 'user.name', 't']);
+  for (const s of ['intents', 'incidents']) fs.mkdirSync(path.join(d, 'workflow', s), { recursive: true });
+  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
+  w(d, '.agents/lane-surfaces.txt', '## product\n^backend/shared/\n');
+  const commit = (msg) => { g(['add', '-A']); g(['commit', '-q', '-m', msg]); };
+  return { d, g, commit };
+};
+const w = (root, rel, content) => { fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true }); fs.writeFileSync(path.join(root, rel), content); };
+const intent = (name, level, date) => `---\n状态: done\n级别: ${level}\n日期: ${date}\n模块: pipeline\n---\n# INTENT — ${name}\n`;
+const run = (root, ...args) => {
+  const r = spawnSync(process.execPath, [SCRIPT, '--root', root, ...args], { encoding: 'utf8' });
+  return { code: r.status, out: `${r.stdout || ''}${r.stderr || ''}` };
+};
+
+// 场景 1：3 个不同 L2 任务反复触及未覆盖目录 → 候选；已覆盖目录（backend/shared）不进候选
+{
+  const { d, commit } = mkrepo();
+  for (let i = 1; i <= 3; i++) {
+    w(d, `workflow/intents/2026-10-0${i}-t${i}.md`, intent(`t${i}`, 'L2', `2026-10-0${i}`));
+    w(d, `backend/material/Shipyard.Material.Application/Services/S${i}.cs`, `// ${i}\n`);
+    w(d, 'backend/shared/Covered.cs', `// c${i}\n`); // 同任务也触已覆盖面
+    commit(`task ${i}`);
+  }
+  const r = run(d, '--since', '2026-10-01');
+  check('场景 1：未覆盖目录 3 任务 → 候选列出且提示人工评估；已覆盖目录不出现',
+    r.code === 0 && r.out.includes('候选漏登面 1 个') && r.out.includes('backend/material/Shipyard.Material.Application') && r.out.includes('lane-surfaces.txt') && !r.out.includes('backend/shared/'), r.out);
+}
+// 场景 2：阈值未达（2 个任务）→ 无候选静默
+{
+  const { d, commit } = mkrepo();
+  for (let i = 1; i <= 2; i++) {
+    w(d, `workflow/intents/2026-10-0${i}-t${i}.md`, intent(`t${i}`, 'L2', `2026-10-0${i}`));
+    w(d, `backend/material/Shipyard.Material.Application/Services/S${i}.cs`, `// ${i}\n`);
+    commit(`task ${i}`);
+  }
+  const r = run(d, '--since', '2026-10-01');
+  check('场景 2：2 任务未达阈值 3 → 无漂移信号', r.code === 0 && r.out.includes('无漂移信号'), r.out);
+}
+// 场景 3：L1 文档不计数（级别过滤）+ --min 覆盖（2 任务 + min 2 → 候选）
+{
+  const { d, commit } = mkrepo();
+  for (let i = 1; i <= 2; i++) {
+    w(d, `workflow/intents/2026-10-0${i}-l${i}.md`, intent(`l${i}`, 'L1', `2026-10-0${i}`));
+    w(d, 'frontend/src/views/Some/V.vue', `// ${i}\n`);
+    commit(`l ${i}`);
+  }
+  const r1 = run(d, '--since', '2026-10-01');
+  check('场景 3a：纯 L1 不入审计面（无 L2/L3 文档）', r1.code === 0 && r1.out.includes('无 L2/L3 文档'), r1.out);
+  const { d: d2, commit: c2 } = mkrepo();
+  for (let i = 1; i <= 2; i++) {
+    w(d2, `workflow/intents/2026-10-0${i}-t${i}.md`, intent(`t${i}`, 'L2', `2026-10-0${i}`));
+    w(d2, 'frontend/src/views/Some/V.vue', `// ${i}\n`);
+    c2(`t ${i}`);
+  }
+  const r2 = run(d2, '--since', '2026-10-01', '--min', '2');
+  check('场景 3b：--min 2 时 2 任务 → 候选', r2.code === 0 && r2.out.includes('frontend/src/views'), r2.out);
+}
+// 场景 4：incident 等价（发现日期键）入审计面
+{
+  const { d, commit } = mkrepo();
+  for (let i = 1; i <= 3; i++) {
+    w(d, `workflow/incidents/2026-10-0${i}-inc${i}.md`, `---\n状态: closed\n级别: L3\n发现: 2026-10-0${i}\n模块: pipeline\n---\n# INCIDENT\n`);
+    w(d, `db/procs/P${i}.sql`, `-- ${i}\n`);
+    commit(`inc ${i}`);
+  }
+  const r = run(d, '--since', '2026-10-01');
+  check('场景 4：incident（发现键）×3 → db/procs 候选', r.code === 0 && r.out.includes('db/procs'), r.out);
+}
+
+console.log(`\n${fail ? `❌ ${fail} failed` : '✅ all passed'}（${pass} passed）`);
+process.exit(fail ? 1 : 0);