agentic-flow-kit 1.7.16 → 1.8.0

package/templates/_agents/scripts/gen-verify-evidence.test.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// gen-verify-evidence.test.mjs — 验证凭证摘要生成器 fixture 套件（2026-10-13 自 Shipyard.Material
+//   参考实现回灌时随件移植；台账口径改 kit 绿行形状 suite:'npm test' + 绑定单 doc 列）
+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, 'gen-verify-evidence.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 mkfix = (rows) => {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-evidence-test-'));
+  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
+  if (rows) fs.writeFileSync(path.join(d, '.agents', 'verifications.jsonl'), rows.map((r) => JSON.stringify(r)).join('\n') + '\n');
+  return d;
+};
+const run = (root, ...args) => {
+  const r = spawnSync(process.execPath, [SCRIPT, '--root', root, ...args], { encoding: 'utf8' });
+  return { code: r.status, out: `${r.stdout || ''}${r.stderr || ''}` };
+};
+// kit 绿行形状（verify.mjs 落账单源）：suite 'npm test'、passed/failed = 套件计数、doc = --doc 绑定单
+const GREEN = (headShort, ts, extra = {}) => ({ ts, exitCode: 0, suite: 'npm test', gates: 7, passed: 45, failed: 0, headShort, ...extra });
+
+// 场景 1：绿行渲染 + 同 SHA 去重取最新 + 失败行/无 SHA 行/坏行排除
+{
+  const d = mkfix([
+    GREEN('abc1234', '2026-10-09T08:34:08Z'),
+    GREEN('abc1234', '2026-10-09T09:14:44Z'), // 同 SHA 更新 ts → 只留此行
+    GREEN('def5678', '2026-10-09T10:00:00Z', { runId: 'PIPE-1', doc: 'workflow/intents/<日期>-<主题>.md' }),
+    { ts: '2026-10-09T11:00:00Z', exitCode: 1, suite: 'check-loop', note: 'exit 1' }, // 失败行
+    { ts: '2026-10-09T12:00:00Z', exitCode: 0, suite: 'npm test', gates: 7 }, // 无 headShort（非 git 环境/旧 schema）
+    '{broken json', // 坏行
+  ]);
+  const r = run(d);
+  const doc = fs.readFileSync(path.join(d, 'workflow', 'verify-evidence.md'), 'utf8');
+  check('场景 1：只渲染绿行且同 SHA 取最新（abc1234 只出现一次且为 09:14）',
+    r.code === 0 && (doc.match(/\| `abc1234`/g) || []).length === 1 && doc.includes('2026-10-09T09:14:44Z') && doc.includes('`def5678`') && doc.includes('PIPE-1') && !doc.includes('2026-10-09T11:00:00Z') && !doc.includes('broken'),
+    doc);
+  check('场景 1b：门数、套件计数与绑定单列渲染', doc.includes('| 7 | PASS 45 / FAIL 0 |') && doc.includes('workflow/intents/<日期>-<主题>.md'), doc);
+}
+// 场景 2：无台账 → 空表骨架（新 clone 首跑）
+{
+  const d = mkfix(null);
+  const r = run(d);
+  const doc = fs.readFileSync(path.join(d, 'workflow', 'verify-evidence.md'), 'utf8');
+  check('场景 2：无台账生成空表骨架', r.code === 0 && doc.includes('# 验证绿凭证摘要') && !doc.includes('`abc'), doc);
+}
+// 场景 3：--check 一致/漂移/再生成恢复
+{
+  const d = mkfix([GREEN('aaa1111', '2026-10-09T08:00:00Z')]);
+  run(d);
+  check('场景 3a：生成后 --check 一致', run(d, '--check').code === 0);
+  fs.writeFileSync(path.join(d, '.agents', 'verifications.jsonl'), JSON.stringify(GREEN('bbb2222', '2026-10-09T09:00:00Z')) + '\n');
+  const r2 = run(d, '--check');
+  check('场景 3b：台账新增绿行 → --check 漂移 exit 1', r2.code === 1 && r2.out.includes('关单时跑'), r2.out);
+  run(d);
+  check('场景 3c：再生成后恢复一致', run(d, '--check').code === 0);
+}
+
+// 场景 4：追加保全——本地台账缺某 SHA 时，仓内既有行不被抹掉（跨机/换 worktree 不失历史）
+{
+  const d = mkfix([GREEN('aaa1111', '2026-10-09T08:00:00Z'), GREEN('ccc3333', '2026-10-09T09:00:00Z')]);
+  run(d);
+  const before = fs.readFileSync(path.join(d, 'workflow', 'verify-evidence.md'), 'utf8');
+  // 换 worktree / 换机：本地台账被覆盖为只含 ddd4444
+  fs.writeFileSync(path.join(d, '.agents', 'verifications.jsonl'), JSON.stringify(GREEN('ddd4444', '2026-10-09T10:00:00Z')) + '\n');
+  const r = run(d);
+  const doc = fs.readFileSync(path.join(d, 'workflow', 'verify-evidence.md'), 'utf8');
+  check('场景 4：台账换机后仓内既有行保全（aaa1111/ccc3333 仍在，ddd4444 补入）',
+    r.code === 0 && doc.includes('`aaa1111`') && doc.includes('`ccc3333`') && doc.includes('`ddd4444`') && before.includes('`aaa1111`'),
+    doc);
+  check('场景 4b：保全后 --check 一致（幂等）', run(d, '--check').code === 0);
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

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

@@ -20,6 +20,9 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { readLedgerRows } from './ledger-loader.mjs';
+// 委派台账分片感知读（2026-10-13 ledger-shard-ledgers 回灌）：合并文本（主台账 ∪ delegations.d/*.md）
+// 由本件经 readLedgerText 取（读侧单源），经 opts.text 注入 agg.readLedger——.cjs 库模式无法自装载 .mjs。
+import { readLedgerText } from './ledger-shards.mjs';
 
 const require = createRequire(import.meta.url);
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -96,7 +99,9 @@ function collectDoneMap(root) {
 
 // qualityRows：月度质量行（判据全部复用 agg——本函数只做分组与格式化）
 export function qualityRows(root) {
-  const rows = agg.readLedger(root, { soft: true });
+  // 分片感知（2026-10-13 ledger-shard-ledgers）：text = 主台账 ∪ delegations.d/*.md；空文本（无台账
+  // 装户）→ rows []，soft 优雅降级语义不变。
+  const rows = agg.readLedger(root, { soft: true, text: readLedgerText(root, 'delegations') });
   const byMonth = {};
   for (const r of rows) (byMonth[r.date.slice(0, 7)] ||= []).push(r);
   const months = Object.keys(byMonth).sort();
@@ -130,9 +135,9 @@ export function qualityRows(root) {
 //   故本节恒为静态文案：**任何时候生成本文件，字节恒等**（测试 ⑤ 的两条 --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/check-loop.mjs --all --gate-stats`（--all 全段成本面——2026-10-13 分道后裸跑只记硬门段；数据落 `.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 调两个生成器 `--check`、检查 13 调 `rule-budget.mjs`）——门禁真实成本，不做剔除；样本 <5 次时只作线索，不作决策依据',
     '- 本节为何不铺数值：本文件被检查 11 漂移门覆盖，运行数据每跑一次门禁即变一次，铺进来会让每次采集都产一条漂移 WARN（不可消除噪声）',
   ];
 }

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

@@ -163,8 +163,9 @@ const INTENT = (fm) => `---\n${fm}\n---\n# INTENT — x\n`;
 
   // 无采集态（先于造 cache 生成）：节恒为静态文案，故与有无数据无关
   const rl = gateRoiLines();
+  // 采集命令随 2026-10-13 分道带 --all（全段成本面；裸 --gate-stats 只记硬门段）
   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'));
+    rl.join('\n').includes('check-loop.mjs --all --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();

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

@@ -4,10 +4,10 @@
 // 目的：把「语料膨胀 + 常驻面体积」变成可观测趋势——每月（或按需）跑一次，往 workflow/metrics.md 追加/更新一行。
 // 口径：文档 = 磁盘（对照 gen-workflow-index / 看板，排除 _TEMPLATE.md）；常驻面 = `.agents/rule-budgets.txt`
 //   各条实测（单源，含预算上限），括号内给「预算占用峰值项」。
-//   字节口径声明（p2-batch2）：本脚本用工作区 statSync 字节（CRLF 检出态会偏高），rule-budget.sh 用
+//   字节口径声明（p2-batch2）：本脚本用工作区 statSync 字节（CRLF 检出态会偏高），rule-budget.mjs 用
 //   索引 LF 归一字节——趋势观测可对比，但与门禁判定数值存在系统性差异，勿互相替用。
 // 不做 --check / 不挂门禁：快照是历史记录——任何文档改动都会让「当前值」漂移，拿它做漂移校验只会常红；
-//   规则面的机器约束由 pre-commit 的 rule-budget.sh 负责，本脚本只负责「看见趋势」。
+//   规则面的机器约束由 pre-commit 的 rule-budget.mjs 负责，本脚本只负责「看见趋势」。
 // 测试：node .agents/scripts/gen-workflow-metrics.test.mjs（fixture 回归，须全绿）
 import fs from 'node:fs';
 import path from 'node:path';
@@ -115,7 +115,7 @@ function scanSurface() {
       max = sum;
       label = `${pat}（合计）`;
     } else if (pat.includes('*')) {
-      // 词表约定 glob = 基名内单个 `*`（<前缀>*<后缀>），目录段不支持通配——与 rule-budget.sh 的 shell glob 同口径。
+      // 词表约定 glob = 基名内单个 `*`（<前缀>*<后缀>），目录段不支持通配——与 rule-budget.mjs 的 glob 展开同口径。
       // 多 `*` / 目录段含 `*` 出词表：警告跳过，不做「只按后缀 endsWith」的放宽式匹配（2026-09-24 收口：
       // 曾按首个 * 取后缀，`pl*.md` 会误吃目录内全部 .md、`a*b` 会误吃一切 b 结尾文件）
       const stars = pat.split('*').length - 1;

package/templates/_agents/scripts/git-core.mjs

@@ -0,0 +1,45 @@
+// git-core.mjs — 引擎 git 调用单源（2026-10-10 收敛系列 5：合并 check-loop-kit spawnGit/gitOut 与
+// stage-gates gitRun 的「同口径两份实现」（该债由 stage-gates 头注登记、本单偿清））。
+// 语义（取两侧并集，全部调用方共享）：
+//   - 参数数组直 spawn（不走 shell——Windows cmd 不认单引号）；git.exe 显式解析（Windows spawn 不补扩展名）
+//   - CHECK_LOOP_GIT 环境变量注入钩子（测试替身：指向不存在路径可稳定触发 spawn 异常）
+//   - 瞬时类错误（EAGAIN/EPERM/EMFILE/EINTR）单次重试；重试终败响亮出账（进程级去重恰一条）——
+//     「非 git 仓」（status≠0、无 error）仍是合法装户语义、静默降级
+//   - 只读查询记忆化：同参（含 cwd）复用结果；带 error 的基础设施失败不缓存（保留重试语义）
+//   - maxBuffer 32MB（pickaxe/name-only 大输出）
+import { spawnSync } from 'node:child_process';
+
+export const GIT = process.env.CHECK_LOOP_GIT || (process.platform === 'win32' ? 'git.exe' : 'git');
+
+const GIT_TRANSIENT = new Set(['EAGAIN', 'EPERM', 'EMFILE', 'EINTR']);
+const GIT_RESULT_CACHE = new Map(); // 键 = cwd + NUL + args.join(NUL)（多仓安全：confirm-doc 等 root 参数调用方）
+let infraWarned = false;
+function warnInfra(args, code) {
+  if (infraWarned) return;
+  infraWarned = true;
+  console.error(`git-core: git 探测异常 ${args[0]}（${code}）——按非 git 仓降级，检查面可能收窄`);
+}
+
+export function spawnGit(args, cwd) {
+  const cacheKey = cwd + '\u0000' + args.join('\u0000');
+  if (GIT_RESULT_CACHE.has(cacheKey)) return GIT_RESULT_CACHE.get(cacheKey);
+  const opts = { cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 };
+  let r = spawnSync(GIT, args, opts);
+  if (r.error) {
+    if (GIT_TRANSIENT.has(r.error.code)) r = spawnSync(GIT, args, opts);
+    if (r.error) warnInfra(args, r.error.code || r.error.message);
+  }
+  if (!r.error) GIT_RESULT_CACHE.set(cacheKey, r);
+  return r;
+}
+
+export function gitOut(args, cwd, { ok = () => true } = {}) {
+  const r = spawnGit(args, cwd);
+  if (r.error || r.status !== 0 || !ok(r)) return null;
+  return r.stdout || '';
+}
+
+// --rev 模式 ROOT 切到临时 worktree 后调：缓存键含 cwd，本不必整体作废；保留接口防御未来键形变化
+export function clearGitCache() {
+  GIT_RESULT_CACHE.clear();
+}

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