agentic-flow-kit 1.4.0 → 1.6.0

package/templates/_agents/scripts/check-stage-index.test.mjs

@@ -0,0 +1,77 @@
+// check-stage-index.test.mjs — 检查 7 模块直测（2026-10-09 engine-quality-round2 A1）
+// 四面：全绿 / AGENTS 侧缺索引 / new-task 文件缺失合法 / gate-seg 段归属（局部收集器并入）
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { runCheckStageIndex } from './check-stage-index.mjs';
+import { makeCollector, finishSegs } from './gate-seg.mjs';
+
+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}` : ''}`); }
+};
+
+// ctx 构造：linesOf 提供读异常→null 语义（与 check-loop 内部实现同语义；「判定零复刻」指模块不重写
+// 判据，测试 fixture 提供测试版 helper 是 check-hygiene.test 先例）
+function makeCtx(root, overrides = {}) {
+  const fileLinesCache = new Map();
+  const linesOf = (file) => {
+    if (!fileLinesCache.has(file)) {
+      let lines = null;
+      try { lines = fs.readFileSync(file, 'utf8').split(/\r?\n/); } catch { lines = null; }
+      fileLinesCache.set(file, lines);
+    }
+    return fileLinesCache.get(file);
+  };
+  return { root, linesOf, ...overrides };
+}
+const ROUTES = '.agents/commands/plan.md → .agents/commands/design.md → .agents/commands/build.md → .agents/commands/test.md → .agents/commands/deploy.md → .agents/commands/maintain.md';
+const mkRoot = (agentsBody, newTaskBody, { noAgents, noNewTask } = {}) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'csi-'));
+  fs.mkdirSync(path.join(root, '.agents', 'commands'), { recursive: true });
+  if (!noAgents) fs.writeFileSync(path.join(root, 'AGENTS.md'), agentsBody);
+  if (!noNewTask) fs.writeFileSync(path.join(root, '.agents', 'commands', 'new-task.md'), newTaskBody);
+  return root;
+};
+const FULL = `# AGENTS\n\n${ROUTES}\n\n**横切**：.agents/commands/review.md\n`;
+const FULL_NT = `# new-task\n\n| Plan | ${ROUTES} | Review(.agents/commands/review.md) |\n`;
+
+{
+  // ① 双面全索引 → 零告警
+  const root = mkRoot(FULL, FULL_NT);
+  const r = runCheckStageIndex(makeCtx(root));
+  check('① 双面全索引 → 零告警', r.length === 0, JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+{
+  // ② AGENTS 侧缺 plan → 仅 AGENTS.md 侧告警（new-task 索引齐全不误报）
+  const root = mkRoot(FULL.replace('.agents/commands/plan.md → ', ''), FULL_NT);
+  const r = runCheckStageIndex(makeCtx(root));
+  check('② AGENTS 侧缺 plan → WARN 点名 AGENTS.md',
+    r.some((w) => w.includes('AGENTS.md 缺 plan 指令索引')), JSON.stringify(r));
+  check('② new-task 侧不告警（其索引齐全）', !r.some((w) => w.includes('new-task.md 缺')), JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+{
+  // ③ new-task 文件不存在 = 合法缺失态（existsSync 守卫）→ 零告警
+  const root = mkRoot(FULL, FULL_NT, { noNewTask: true });
+  const r = runCheckStageIndex(makeCtx(root));
+  check('③ new-task 文件缺失 → 合法缺失零告警', r.length === 0, JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+{
+  // ④ gate-seg 段归属：ctx.gateStats 在场时段 '6' 入账、warns 与实际 WARN 数一致（selfmeasure 接线
+  //   教训：模块须用局部收集器 + appendSegs，直接共用全局游标会错账）
+  const root = mkRoot(FULL.replace('.agents/commands/plan.md → ', ''), FULL_NT);
+  const stats = makeCollector([], []);
+  const r = runCheckStageIndex(makeCtx(root, { gateStats: stats }));
+  const seg6 = finishSegs(stats).filter((s) => s.id === '6');
+  check('④ gate-seg：段 6 入账一次且 warns 与实际 WARN 数一致',
+    seg6.length === 1 && seg6[0].warns === r.length && r.length === 1,
+    JSON.stringify({ seg6, ret: r }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

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

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

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

@@ -38,9 +38,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { createHash, randomBytes } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
 import { confirmGateFor, doneGateFor, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
-import { loadKitPolicy, hasFreshVerifyLine } from './policy.mjs';
+import { loadKitPolicy, hasFreshVerifyLine, ledgerChainHash } from './policy.mjs';
 
 // hasFreshVerify(root, doc)：读 <root>/.agents/verifications.jsonl 判 24h 窗口绿行（判定单源
 // policy.hasFreshVerifyLine）。只读，台账缺失/不可读一律 false（=无凭证，advisory 层 fail-open）。
@@ -121,10 +120,25 @@ export function applyTransition(text, targetStage, fingerprint16) {
 }
 
 // appendLedger(root, entry)：追加一行 JSON（目录不存在自动建；只 append 不重写）
+// 哈希链（2026-10-09 engine-quality-round2 D）：每行追加 prevHash（末行 hash，末行无 hash/空文件 → ''）
+//   与 hash（ledgerChainHash 单源计算，check-loop 15 同函数验链）——「就地改/删中间行」必留断链痕迹；
+//   历史行零回填（无 hash 行后链重启），整文件重写不可机器防（边界声明见 policy.ledgerChainHash）。
 export function appendLedger(root, entry) {
   const p = path.join(root, '.agents', 'confirmations.jsonl');
   fs.mkdirSync(path.dirname(p), { recursive: true });
-  fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+  let prevHash = '';
+  try {
+    if (fs.existsSync(p)) {
+      const lines = fs.readFileSync(p, 'utf8').split(/\r?\n/).filter((l) => l.trim());
+      if (lines.length) {
+        const last = JSON.parse(lines[lines.length - 1]);
+        prevHash = last && typeof last.hash === 'string' ? last.hash : '';
+      }
+    }
+  } catch { /* 末行不可解析 → prevHash ''（链从本行重启；断裂由 check-loop 15 出账） */ }
+  const { hash: _h, prevHash: _p, ...rest } = entry;
+  const row = { ...rest, prevHash, hash: ledgerChainHash(rest, prevHash) };
+  fs.appendFileSync(p, JSON.stringify(row) + '\n');
   return p;
 }
 

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

@@ -104,6 +104,23 @@ const readLedgerOf = (root) => {
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- S8b 哈希链（2026-10-09 engine-quality-round2 D）：链字段写入 + 接续 + 重算自洽 ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-chain-'));
+  // 先写一行无 hash 的「存量」行（模拟 v1.5.0 前台账）——新行 prevHash 应为 ''（链重启）
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'confirmations.jsonl'), JSON.stringify({ ts: 'T0', doc: 'workflow/plans/old.md', stage: 'done', fingerprint: 'e'.repeat(64), prev: 'approved' }) + '\n');
+  appendLedger(root, { ts: 'T1', doc: 'workflow/plans/a.md', stage: 'approved', fingerprint: 'f'.repeat(64), prev: 'draft' });
+  appendLedger(root, { ts: 'T2', doc: 'workflow/plans/a.md', stage: 'done', fingerprint: 'g'.repeat(64), prev: 'approved' });
+  const rows = fs.readFileSync(path.join(root, '.agents', 'confirmations.jsonl'), 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+  check('S8b 存量行后首链行 prevHash 为空（链重启，历史零回填）', rows[0].hash === undefined && rows[1].prevHash === '');
+  check('S8b 第二链行 prevHash 接续第一链行 hash', rows[2].prevHash === rows[1].hash);
+  const { ledgerChainHash } = await import('./policy.mjs');
+  const recompute = (row) => { const { hash, prevHash, ...rest } = row; return ledgerChainHash(rest, prevHash) === hash; };
+  check('S8b 两链行 hash 重算自洽（CRLF/键序规范化单源）', recompute(rows[1]) && recompute(rows[2]));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 // ---- S9【核心】非 TTY spawn（AI 调用路径）必须被拒 ----
 {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-tty-'));

package/templates/_agents/scripts/edit-face-check.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// edit-face-check — 常驻面编辑时快检（2026-10-09 engine-quality-round2 B2）
+// 动机：常驻面（AGENTS.md 等）的机器约束此前只在 git 钩子层生效——check-loop 仓库模式只扫 HEAD，
+//   工作树编辑期零反馈（实测：常驻面重构砍掉阶段索引，到提交才被检查 7 报警）。本脚本把判定左移到编辑时。
+// 判定零复刻铁律：闭环判定**单源**复用 check-loop——以 CHECK_LOOP_ROOT=<root>（全扫模式，扫工作树
+//   非 HEAD）子进程消费其裁决，本脚本不实现任何门判定；唯一自算是常驻面字节预算 advisory（工作树
+//   LF 字节 vs rule-budgets.txt 上限——提交门口径走 git index/HEAD（rule-budget.sh），两者判据不同面，
+//   此处为编辑时 advisory，冲突时以提交门为准）。
+// exit 语义：check-loop hard（exit≠0）→ 2；预算 advisory 超限 → 1；其余 → 0。
+//   WARN **不进 exit**（打印明细供 AI/人对照）——绝对 WARN 计数会让带存量 advisory 的仓库恒非零
+//   （本仓即有用户拍板保留的存量 WARN），工具就不可用了；编辑破坏的表现（如阶段索引漂移 WARN）
+//   在输出里一眼可见，由编辑者处置。
+// 用法：node .agents/scripts/edit-face-check.mjs [--root <仓库根>]（缺省 cwd；测试注入 EDIT_FACE_CHECK_SPAWN）
+// 测试：node templates/_agents/scripts/edit-face-check.test.mjs
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+// LF 归一字节数（编辑时口径——工作区文件可能 CRLF，预算表口径注释声明「比较用 LF 归一」）
+export function lfBytes(text) {
+  return Buffer.byteLength(String(text).replace(/\r\n/g, '\n'), 'utf8');
+}
+
+// globToRe：rule-budgets.txt 行首路径 → 正则（支持 `*` 段内通配与结尾 `/` 目录前缀；其余字面）
+export function globToRe(pattern) {
+  const dir = pattern.endsWith('/');
+  let src = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*');
+  if (dir) src += '.*';
+  return new RegExp(`^${src}${dir ? '' : '$'}`);
+}
+
+// budgetAdvisory：常驻面预算 advisory（编辑时口径）。files: Map<rel, 工作树文本>；budgetsText: 表原文。
+// 返回超限行 [{ rel, limit, actual }]；表缺失/行非法 → 空数组（advisory 层 fail-open）。
+export function budgetAdvisory(files, budgetsText) {
+  const out = [];
+  if (!budgetsText) return out;
+  for (const line of budgetsText.split(/\r?\n/)) {
+    const t = line.replace(/\r$/, '').trim();
+    if (!t || t.startsWith('#')) continue;
+    const m = t.match(/^(\S+)\s+(\d+)$/);
+    if (!m) continue;
+    const [, pattern, limitStr] = m;
+    const limit = Number(limitStr);
+    const re = globToRe(pattern);
+    for (const [rel, text] of files) {
+      if (!re.test(rel)) continue;
+      const actual = lfBytes(text);
+      if (actual > limit) out.push({ rel, limit, actual });
+    }
+  }
+  return out;
+}
+
+// runCheck：工作树面 check-loop（CHECK_LOOP_ROOT 全扫）。返回 { code, output, ms }。
+function runCheck(root, scriptDir) {
+  const t0 = Date.now();
+  const r = spawnSync(process.execPath, [path.join(scriptDir, 'check-loop.mjs')], {
+    cwd: root, encoding: 'utf8', windowsHide: true,
+    env: { ...process.env, CHECK_LOOP_ROOT: root },
+  });
+  return { code: r.status ?? 1, output: `${r.stdout || ''}${r.stderr || ''}`, ms: Date.now() - t0 };
+}
+
+export function main(root = process.cwd(), scriptDir = path.dirname(fileURLToPath(import.meta.url))) {
+  // ① 闭环判定（单源 check-loop，工作树全扫）
+  const ck = runCheck(root, scriptDir);
+  const warnCount = (ck.output.match(/\[WARN /g) || []).length;
+  // ② 常驻面预算 advisory（AGENTS.md + 预算表内文件的工作树字节）
+  let over = [];
+  try {
+    const budgetsPath = path.join(root, '.agents', 'rule-budgets.txt');
+    const budgetsText = fs.existsSync(budgetsPath) ? fs.readFileSync(budgetsPath, 'utf8') : null;
+    const files = new Map();
+    const agentsPath = path.join(root, 'AGENTS.md');
+    if (fs.existsSync(agentsPath)) files.set('AGENTS.md', fs.readFileSync(agentsPath, 'utf8'));
+    over = budgetAdvisory(files, budgetsText);
+  } catch { /* advisory 层 fail-open：预算读不到不阻断编辑时反馈 */ }
+
+  console.log(`▶ edit-face-check → ${root}（工作树面）`);
+  console.log(`  check-loop：${ck.code === 0 ? '通过' : `exit ${ck.code}`}，WARN ${warnCount} 条（${ck.ms}ms）——与本仓存量 advisory 对照看新增`);
+  // WARN 明细透传（编辑破坏的判读面——如删阶段索引会在此点名「阶段索引漂移」）
+  for (const line of ck.output.split(/\r?\n/)) {
+    if (/\[WARN /.test(line)) console.log('  ' + line.trim().slice(0, 200));
+  }
+  for (const { rel, limit, actual } of over) {
+    console.log(`  ⚠️ 预算 advisory：${rel} 工作树 ${actual}B > 上限 ${limit}B（编辑时口径；提交门以 rule-budget.sh 为准）`);
+  }
+  if (ck.code !== 0) {
+    console.error('❌ 闭环判定 hard 未过——先修复再提交（判定单源 check-loop，详见上方输出）');
+    return 2;
+  }
+  if (over.length > 0) {
+    console.error('⚠️ 常驻面预算 advisory 超限——建议编辑期就瘦，别留到提交门');
+    return 1;
+  }
+  console.log('✅ 编辑时快检完成（hard/预算两道均过；WARN 明细请对照处置）');
+  return 0;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('edit-face-check.mjs');
+if (isMain) {
+  let root = process.cwd();
+  const i = process.argv.indexOf('--root');
+  if (i > 0 && process.argv[i + 1]) root = path.resolve(process.argv[i + 1]);
+  process.exit(main(root));
+}

package/templates/_agents/scripts/edit-face-check.test.mjs

@@ -0,0 +1,98 @@
+// edit-face-check.test.mjs — 编辑时快检（2026-10-09 engine-quality-round2 B2）
+// 三面：纯函数（lfBytes/globToRe/budgetAdvisory）+ 端到端全绿面 + 破坏面（删阶段索引→WARN→exit 1、
+// 预算超限→exit 1）。判定零复刻：端到端经 CHECK_LOOP_ROOT 消费真 check-loop，fixture 复制脚本集。
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SRC = path.dirname(fileURLToPath(import.meta.url));
+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 mod = await import(pathToFileURL(path.join(SRC, 'edit-face-check.mjs')).href);
+const { lfBytes, globToRe, budgetAdvisory } = mod;
+
+// ---- ① 纯函数 ----
+check('lfBytes：CRLF 归一计 UTF-8 字节', lfBytes('a\r\nb中文') === Buffer.byteLength('a\nb中文', 'utf8'));
+check('globToRe：精确路径', globToRe('AGENTS.md').test('AGENTS.md') && !globToRe('AGENTS.md').test('x/AGENTS.md'));
+check('globToRe：段内通配', globToRe('.agents/commands/*.md').test('.agents/commands/plan.md') && !globToRe('.agents/commands/*.md').test('.agents/commands/x/plan.md'));
+check('globToRe：目录前缀', globToRe('.agents/cache/').test('.agents/cache/a/b.json'));
+
+{
+  const files = new Map([
+    ['AGENTS.md', 'x'.repeat(120)],
+    ['.agents/commands/plan.md', 'y'.repeat(50)],
+  ]);
+  const budgets = '# 注释行\nAGENTS.md 100\n.agents/commands/*.md 200\n非法行\n';
+  const r = budgetAdvisory(files, budgets);
+  check('budgetAdvisory：超限单文件报、未超限不报、非法行跳过',
+    r.length === 1 && r[0].rel === 'AGENTS.md' && r[0].limit === 100 && r[0].actual === 120, JSON.stringify(r));
+  check('budgetAdvisory：表缺失 fail-open', budgetAdvisory(files, null).length === 0);
+}
+
+// ---- ② 端到端 fixture ----
+const SCRIPTS = ['check-loop.mjs', 'policy.mjs', 'stage-gates.mjs', 'check-metric-claims.mjs', 'check-hygiene.mjs', 'check-stage-index.mjs', 'gate-seg.mjs', 'workflow-enums.mjs', 'edit-face-check.mjs'];
+// 引用完整性哑文件（检查 4/6/7 的存在性判据——避免 fixture 结构性 WARN 淹没断言面）
+const REF_COMMANDS = ['new-task', 'plan', 'design', 'build', 'test', 'deploy', 'maintain', 'review'];
+const REF_ROLES = ['implementer', 'independent-reviewer', 'ui-verifier'];
+function mkFixture({ breakStageIndex, overBudget }) {
+  const fx = fs.mkdtempSync(path.join(os.tmpdir(), 'efc-'));
+  fs.mkdirSync(path.join(fx, '.agents', 'scripts'), { recursive: true });
+  for (const f of SCRIPTS) fs.copyFileSync(path.join(SRC, f), path.join(fx, '.agents', 'scripts', f));
+  for (const f of ['kit.json', 'workflow-modules.txt', 'workflow-enums.txt'])
+    if (fs.existsSync(path.join(SRC, '..', f))) fs.copyFileSync(path.join(SRC, '..', f), path.join(fx, '.agents', f));
+  fs.mkdirSync(path.join(fx, 'workflow', 'intents'), { recursive: true });
+  for (const d of ['specs', 'plans', 'incidents']) fs.mkdirSync(path.join(fx, 'workflow', d), { recursive: true });
+  for (const c of REF_COMMANDS) { fs.mkdirSync(path.join(fx, '.agents', 'commands'), { recursive: true }); fs.writeFileSync(path.join(fx, '.agents', 'commands', `${c}.md`), `# ${c}\n`); }
+  for (const rname of REF_ROLES) { fs.mkdirSync(path.join(fx, '.agents', 'roles'), { recursive: true }); fs.writeFileSync(path.join(fx, '.agents', 'roles', `${rname}.md`), `# ${rname}\n`); }
+  // 常驻面 AGENTS.md：阶段索引齐全（含 review）/ 破坏面删索引（破坏只在 AGENTS.md 侧——new-task
+  //   哑文件写全索引，钉检查 7 的双向语义差异）
+  const routes = '.agents/commands/plan.md → .agents/commands/design.md → .agents/commands/build.md → .agents/commands/test.md → .agents/commands/deploy.md → .agents/commands/maintain.md';
+  const reviewLine = breakStageIndex ? '' : '\n**横切**：.agents/commands/review.md\n';
+  const body = `# AGENTS\n\n## 阶段路由\n\n**入口**：.agents/commands/new-task.md\n**指令**：${breakStageIndex ? '（已删）' : routes}${reviewLine}\n`;
+  fs.writeFileSync(path.join(fx, 'AGENTS.md'), overBudget ? body + 'x'.repeat(200) : body);
+  fs.writeFileSync(path.join(fx, '.agents', 'commands', 'new-task.md'),
+    `# new-task\n\n| Plan | ${routes} | Review |\n`);
+  fs.writeFileSync(path.join(fx, '.agents', 'rule-budgets.txt'), `AGENTS.md ${overBudget ? 100 : 100000}\n`);
+  return fx;
+}
+
+{
+  // 全绿面：空 workflow + 引用齐全 + 预算内 → hard/预算两道过（exit 0）。
+  //   注：不要求零 WARN——check-loop 全扫对极简 fixture 有结构性 advisory（引用/角色形态），明细
+  //   承载给编辑者对照；exit 语义只钉 hard 与预算两道（绝对 WARN 计数会让存量仓库恒非零）。
+  const fx = mkFixture({});
+  const driver = path.join(fx, 'driver.mjs');
+  fs.writeFileSync(driver, `import { main } from ${JSON.stringify('file:///' + path.join(fx, '.agents', 'scripts', 'edit-face-check.mjs').replace(/\\/g, '/'))};\nprocess.exit(main(${JSON.stringify(fx)}, ${JSON.stringify(path.join(fx, '.agents', 'scripts'))}));\n`);
+  const r = spawnSync(process.execPath, [driver], { encoding: 'utf8' });
+  check('E2E 全绿面：exit 0（hard/预算两道过）且 AGENTS.md 侧无索引漂移', r.status === 0 && !/AGENTS\.md 缺 .* 指令索引/.test(r.stdout || ''), `status=${r.status}\n${(r.stdout || '') + (r.stderr || '')}`.slice(0, 600));
+}
+
+{
+  // 破坏面：删阶段索引 → 检查 7 WARN 点名（明细承载编辑破坏——破坏面 vs 全绿面的差异就在输出；
+  //   hard 不误触：阶段索引是 warning 级，exit≠2）
+  const fx = mkFixture({ breakStageIndex: true });
+  const driver = path.join(fx, 'driver.mjs');
+  fs.writeFileSync(driver, `import { main } from ${JSON.stringify('file:///' + path.join(fx, '.agents', 'scripts', 'edit-face-check.mjs').replace(/\\/g, '/'))};\nprocess.exit(main(${JSON.stringify(fx)}, ${JSON.stringify(path.join(fx, '.agents', 'scripts'))}));\n`);
+  const r = spawnSync(process.execPath, [driver], { encoding: 'utf8' });
+  const out = (r.stdout || '') + (r.stderr || '');
+  check('E2E 破坏面（删阶段索引）：WARN 点名 AGENTS.md 侧索引漂移且 hard 不误触', r.status !== 2 && /AGENTS\.md 缺 plan 指令索引/.test(out), `status=${r.status}\n${out.slice(0, 600)}`);
+}
+
+{
+  // 预算超限面：AGENTS.md 超上限 → exit 1（advisory 面单独可达——workflow 全绿）
+  const fx = mkFixture({ overBudget: true });
+  const driver = path.join(fx, 'driver.mjs');
+  fs.writeFileSync(driver, `import { main } from ${JSON.stringify('file:///' + path.join(fx, '.agents', 'scripts', 'edit-face-check.mjs').replace(/\\/g, '/'))};\nprocess.exit(main(${JSON.stringify(fx)}, ${JSON.stringify(path.join(fx, '.agents', 'scripts'))}));\n`);
+  const r = spawnSync(process.execPath, [driver], { encoding: 'utf8' });
+  const out = (r.stdout || '') + (r.stderr || '');
+  check('E2E 预算超限面：exit 1 且 advisory 点名', r.status === 1 && /预算 advisory/.test(out), `status=${r.status}\n${out.slice(0, 500)}`);
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/ensure-board.mjs

@@ -105,7 +105,7 @@ function openBrowser(url) {
   try {
     if (process.platform === 'win32') spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
     else spawn(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
-  } catch { }
+  } catch { /* 浏览器拉起失败不阻断看板流程 */ }
 }
 
 // ---- 主流程（返回退出码，自然排水退出——不用 process.exit：强退在 Windows 上会触发 libuv 断言）----
@@ -123,7 +123,7 @@ async function main() {
       board = b;
       const stale = staleCode(b.startedAt);
       if (stale === true) {
-        try { process.kill(b.pid); } catch { } // 进程可能已自行退出，忽略
+        try { process.kill(b.pid); } catch { /* 进程可能已自行退出 */ }
         await sleep(500);
         action = 'restarted (stale code detected)';
       } else if (stale === null) {

package/templates/_agents/scripts/fill-intent.mjs

@@ -5,6 +5,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ENUMS } from './workflow-enums.mjs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
 const TODAY = new Date().toISOString().slice(0, 10);
 const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/workflow-enums.txt）
@@ -31,17 +33,29 @@ const SECTIONS = [
   { title: '目标', hint: '- <可验证的目标>' },
   { title: '非目标（L1 微改动无实质内容可删本节，不硬填）', hint: '- <明确不做的，防止范围蔓延>' },
   { title: '约束（L1 微改动无实质内容可删本节，不硬填）', hint: '- <复用什么、不许动什么>' },
-  { title: '影响面', hint: '- 模块：<词表之一，见 .agents/workflow-modules.txt>\n- 数据库：无 / <表名>（涉及 schema 变更 $\rightarrow$ L3；无 schema 的运行时 / 管线结构面亦为 L3，判据见 .agents/commands/new-task.md §级别判断）\n- 前端页面：<路由或组件，无则删本行>' },
-  { title: '触达红线（对照 AGENTS.md，勾选仅标记触及范围；具体如何满足在同名 spec 或 Quick-Plan 中说明）', hint: '- [ ] <按本项目 AGENTS.md 红线逐行补；无则删本行>\n- [ ] 规则 / 契约变更（编码权威 / 共享契约 / 接口签名 / 既有参数语义 / 全局口径）$\rightarrow$ 级别至少 L2\n- [ ] schema / 迁移 SQL / DI 链 / 认证与中间件管线 $\rightarrow$ 级别 L3\n\n> 触及任一红线即为 L2 / L3，必须立 ../specs/YYYY-MM-DD-<主题>.md 写明如何满足，方可起草 plan。' },
+  { title: '影响面', hint: '- 模块：<词表之一，见 .agents/workflow-modules.txt>\n- 数据库：无 / <表名>（涉及 schema 变更 → L3；无 schema 的运行时 / 管线结构面亦为 L3，判据见 .agents/commands/new-task.md §级别判断）\n- 前端页面：<路由或组件，无则删本行>' },
+  { title: '触达红线（对照 AGENTS.md，勾选仅标记触及范围；具体如何满足在同名 spec 或 Quick-Plan 中说明）', hint: '- [ ] <按本项目 AGENTS.md 红线逐行补；无则删本行>\n- [ ] 规则 / 契约变更（编码权威 / 共享契约 / 接口签名 / 既有参数语义 / 全局口径）→ 级别至少 L2\n- [ ] schema / 迁移 SQL / DI 链 / 认证与中间件管线 → 级别 L3\n\n> 触及任一红线即为 L2 / L3，必须立 ../specs/YYYY-MM-DD-<主题>.md 写明如何满足，方可起草 plan。' },
   { title: '验收标准（可测试）', hint: '- [ ] <逐条可测试；写不出可测试判据 = 还没想清楚>\n\n> **闭环对账**：关单在 test 阶段（不依赖 deploy）。intent 置 done 前逐条勾验，每条补证据——`- [x] <判据>（证据：<commit SHA / 测试用例名 / 冒烟脚本输出>）`。\n> done 状态仍有未勾项会被 check-loop 拦截（2026-09-12 起新建 intent 为 hard-block，存量 intent 仅 warning 提示）；勾选但缺「证据：」为 hard-block。' },
 ];
 
-export function renderIntent({ topic, module, level, notes, date = TODAY }) {
+// renderIntent：骨架渲染（纯函数）。kbHits（2026-10-09 engine-quality-round3 W2）：kb-search 命中行
+// 数组（📄 行原文）——非空时替换「历史教训/防复发」节的检索占位行为实际命中列表（历史坑强制注入，
+// 手动路由与 pipeline-run 工单同权）；空/缺省保留占位（fail-open 口径）。子进程调用在 main，本函数保持无 IO。
+export function renderIntent({ topic, module, level, notes, date = TODAY, kbHits = [], kbFailNote = '' }) {
   if (!LEVELS.includes(level)) throw new Error('level 不在枚举 ' + LEVELS.join('|') + '：' + level);
   const fm = '---\n状态: draft\n级别: ' + level + '\nrisk_level: ' + level + '\n日期: ' + date + '\n模块: ' + module + '\n备注: ' + (notes || '<可选：附注自由文本，check-loop 不解析>') + '\n---\n';
   let body = '# INTENT — ' + topic + '\n\n<!-- 复制本模板为 YYYY-MM-DD-<主题>.md 后填写；plans/ 下同名文件与本文件配对 -->\n<!-- frontmatter 受限子集（2026-09-13）：每行 键: 值；状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L0/L1/L2/L3；risk_level=级别（混合治理风险泳道选道：L0/L1 协作道异步审计 / L2/L3 防御道同步确认）；check-loop 只扫 frontmatter 取机器字段，正文不再写状态/级别行 -->\n\n';
   for (const { title, hint } of SECTIONS) {
-    body += '## ' + title + '\n\n' + hint + '\n\n';
+    let section = hint;
+    if (title === '历史教训/防复发') {
+      const placeholder = '- 检索结果：`node .agents/scripts/kb-search.mjs "<关键词>" --type incidents` 命中结果';
+      if (kbHits.length) {
+      const injected = '- 检索结果（自动注入 ' + kbHits.length + ' 条，同域历史——起草前先读其根因与防复发）：\n' + kbHits.map((h) => '  - ' + h).join('\n');
+      if (section.includes(placeholder)) section = section.replace(placeholder, injected);
+      }
+      else if (kbFailNote) section = section.replace('- 检索结果：', '- 检索结果' + kbFailNote + '\n- 检索结果：'); // 复核 P2-2：不可用时留手工命令注释行
+    }
+    body += '## ' + title + '\n\n' + section + '\n\n';
   }
   body += '## 确认与复核\n\n- 确认日期：\n- 确认人：用户（对话内明确放行即确认）\n- 确认范围：\n- 复核：L1 不要求独立复核\n';
   return { frontmatter: fm, body: fm + body, sections: SECTIONS.map((s) => s.title) };
@@ -52,7 +66,22 @@ if (isMain) {
   const a = parseArgs(process.argv.slice(2));
   if (!a.topic || !a.module || !a.output) fail('必填：--topic / --module / --output；选填：--level（默认 L1）/ --notes');
   if (!LEVELS.includes(a.level)) fail('level 必须在 ' + LEVELS.join('|') + '：' + a.level);
-  const { body } = renderIntent(a);
+  // 历史坑强制注入（2026-10-09 engine-quality-round3 W2）：同目录 kb-search 子进程检索同域历史
+  // （关键词 = topic ascii 段 + 模块名；--type incidents,plans——修复先例与计划同查）。fail-open：
+  // 非零/零命中/3s 超时 → kbHits 空 → 保留占位（与手动路由「AI 自觉检索」不同，此处机器保证尝试）。
+  let kbFailNote = '';
+  let kbHits = [];
+  try {
+    const words = (String(a.topic).toLowerCase().match(/[a-z0-9]{2,}/g) || []).slice(0, 2);
+    const kw = [...new Set([...words, String(a.module || '')].filter(Boolean))]; // 复核 P1-1：模块名入关键词（spec S2 口径）
+    const r = spawnSync(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), 'kb-search.mjs'),
+      ...kw, '--scope', 'workflow', '--type', 'incidents,plans', '-n', '4'], { encoding: 'utf8', timeout: 3000, windowsHide: true });
+    if (r.status === 0 && r.stdout) {
+      kbHits = r.stdout.split(/\r?\n/).filter((l) => l.startsWith('📄')).slice(0, 4);
+    if (!kbHits.length) kbFailNote = '（自动检索不可用或零命中，手工跑：node .agents/scripts/kb-search.mjs "<关键词>" --type incidents）';
+    }
+  } catch { /* fail-open：检索不可用保留占位 */ }
+  const { body } = renderIntent({ ...a, kbHits, kbFailNote });
   fs.mkdirSync(path.dirname(a.output), { recursive: true });
   fs.writeFileSync(a.output, body);
   console.log('✅ 已生成 intent 草稿：' + a.output + '（状态 draft / 级别 ' + a.level + ' / 模块 ' + a.module + '）');

package/templates/_agents/scripts/fill-intent.test.mjs

@@ -78,5 +78,18 @@ function check(name, cond, detail = '') {
   }
 }
 
+
+// ---- 历史坑注入 kbHits（2026-10-09 engine-quality-round3 W2）----
+{
+  const hits = ["📄 workflow/incidents/2026-10-01-aaa.md — closed · L2 · pipeline · 3 处命中 / 1KB"];
+  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L2', kbHits: hits });
+  check('kb 注入：命中行替换占位（含自动注入计数与 📄 原文）',
+    body.includes('检索结果（自动注入 1 条') && body.includes("📄 workflow/incidents/2026-10-01-aaa.md — closed · L2 · pipeline · 3 处命中 / 1KB") && !body.includes("- 检索结果：`node .agents/scripts/kb-search.mjs \"<关键词>\" --type incidents` 命中结果"), body.slice(0, 200));
+}
+{
+  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L2', kbHits: [] });
+  check('kb 零命中：保留占位（fail-open 口径）', body.includes("- 检索结果：`node .agents/scripts/kb-search.mjs \"<关键词>\" --type incidents` 命中结果"), body.slice(0, 200));
+}
+
 console.log('\n合计: PASS ' + pass + ' / FAIL ' + failCount);
 process.exit(failCount ? 1 : 0);

package/templates/_agents/scripts/fill-plan.mjs

@@ -9,7 +9,6 @@ import path from 'node:path';
 import { ENUMS } from './workflow-enums.mjs';
 import { draftGateFor, resolveWorkspace } from './stage-gates.mjs';
 
-const TODAY = new Date().toISOString().slice(0, 10);
 const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/workflow-enums.txt）
 
 function parseArgs(argv) {
@@ -40,7 +39,7 @@ const FULL_SECTIONS = [
   L1_SECTIONS[2],
 ];
 
-export function renderPlan({ topic, level = 'L1', date = TODAY }) {
+export function renderPlan({ topic, level = 'L1' }) {
   if (!LEVELS.includes(level)) throw new Error('level 不在枚举 ' + LEVELS.join('|') + '：' + level);
   const sections = level === 'L1' ? L1_SECTIONS : FULL_SECTIONS;
   const fm = '---\n状态: draft\n级别: ' + level + '\n模块: pipeline\n---\n';

package/templates/_agents/scripts/gen-wiki-board.mjs

@@ -141,7 +141,7 @@ let out = indexText;
 {
   const lines = out.split(/\r?\n/);
   const headIdx = lines.findIndex((l) => /^\| 主题 \|/.test(l));
-  if (headIdx < 0 || !/^[\|:\-\s]+$/.test(lines[headIdx + 1] || '')) {
+  if (headIdx < 0 || !/^[|:\-\s]+$/.test(lines[headIdx + 1] || '')) {
     console.error('❌ INDEX 速览表表头未找到，未写盘');
     process.exit(1);
   }

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

@@ -12,8 +12,6 @@ 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'));

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

@@ -124,7 +124,7 @@ const run = (root, args = []) => spawnSync(process.execPath, [GEN, ...args], { c
     '状态: draft\n级别: L1\n日期: 2026-09-22\n模块: pipeline',
     'workflow-doc-retrieval',
   ), 'utf8');
-  const r = run(root);
+  run(root);
   const idx = fs.readFileSync(path.join(root, 'workflow', 'INDEX.md'), 'utf8');
   check('场景 5：kebab-case H1 完整保留（未被截成末段）', idx.includes('| workflow-doc-retrieval |') && !idx.includes('| retrieval |'), idx.split('\n').filter((l) => l.includes('retrieval')).join('\n'));
   check('场景 5：em-dash 前缀仍正常剥离', idx.includes('| 在跑的需求甲 |'), '');

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

@@ -48,7 +48,7 @@ const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
 // **不能用固定上溯级数**（2026-09-28 修正）：本脚本在两处运行、深度不同——
 //   包源 `templates/_agents/scripts/` → 上溯 3 级到仓库根
 //   装户 `.agents/scripts/`          → 上溯 2 级到安装根
-// 首版硬编码 3 级，故**在每个装户安装里都解析不到枚举文件**（报错路径 `<install>/..​/.agents/…`）。
+// 首版硬编码 3 级，故**在每个装户安装里都解析不到枚举文件**（报错路径 `<install>/../.agents/…`）。
 // 实测暴露路径：CI 新增「shipped 套件」步骤后，`.agents/scripts/gen-workflow-metrics.test.mjs`
 // 场景 1 即 exit 1（workflow-enums 单源文件不可读），而包源侧同字节跑出全绿。
 // 改为**逐级上溯探测**：找到含 `.agents/workflow-enums.txt` 的那一级即用，找不到则回退标准位置让
@@ -280,5 +280,56 @@ if (existing.includes(BEGIN) && existing.includes(END)) {
 } else {
   out = (existing ? existing.replace(/\s*$/, '') + '\n\n' : HEADER) + inner + '\n';
 }
-fs.writeFileSync(METRICS_P, out, 'utf8');
+
+// ---- 趋势序列 + 确认负担（2026-10-09 engine-quality-round3 W4）----
+// ① 确认负担：本月 confirmations.jsonl 行数（stage=void 除外）与上月比（口径：每次 confirm-doc 调用
+//    落一行——「确认门调用次数」即确认负担的机器事实；void 为作废标记不计）。
+// ② 趋势序列：.agents/cache/metrics-history.jsonl 每日一行幂等（同日重跑覆盖）——metrics.md「趋势」
+//    行对比昨日 docsTotal/confirmCalls；history 损坏重建（fail-open）。
+const HISTORY_P = path.join('.agents', 'cache', 'metrics-history.jsonl');
+const voidExcluded = ledgerRows.filter((e) => e.stage !== 'void');
+const monthOf = (e) => (typeof e.ts === 'string' ? e.ts.slice(0, 7) : '');
+const thisMonth = month.slice(0, 7); // month 变量 = 生成锚月（YYYY-MM）
+const prevMonthDate = new Date(thisMonth + '-01T00:00:00Z');
+prevMonthDate.setUTCMonth(prevMonthDate.getUTCMonth() - 1);
+const prevMonth = prevMonthDate.toISOString().slice(0, 7);
+const confirmThis = voidExcluded.filter((e) => monthOf(e) === thisMonth).length;
+const confirmPrev = voidExcluded.filter((e) => monthOf(e) === prevMonth).length;
+const confirmDelta = confirmPrev > 0 ? Math.round(((confirmThis - confirmPrev) / confirmPrev) * 100) : null;
+
+// docsTotal：metrics 主表本月行的文档数列（第一数值列）——从 row 提取，避免重复统计逻辑
+const docsTotal = docs.files; // 直取作用域变量（正则提取曾因「287（活跃…）」复合列失配——round3 实测修正）
+
+// history 读写（fail-open：损坏重建）
+let history = [];
+try {
+  if (fs.existsSync(HISTORY_P)) {
+    history = fs.readFileSync(HISTORY_P, 'utf8').split(/\r?\n/).filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  }
+} catch { history = []; }
+const today = new Date().toISOString().slice(0, 10);
+history = history.filter((h) => h && h.date !== today); // 同日幂等：覆盖当日行
+history.push({ date: today, docsTotal, passRate: funnel.closed ? Math.round((funnel.once / funnel.closed) * 100) + '%' : '', confirmCalls: confirmThis, savedAt: new Date().toISOString() });
+try {
+  fs.mkdirSync(path.dirname(HISTORY_P), { recursive: true });
+  const tmpH = HISTORY_P + '.tmp';
+  fs.writeFileSync(tmpH, history.map((h) => JSON.stringify(h)).join('\n') + '\n');
+  fs.renameSync(tmpH, HISTORY_P);
+} catch { /* history 写失败不影响 metrics.md 主产物 */ }
+
+// 趋势行（对比昨日快照）
+const yesterday = history.filter((h) => h.date !== today).slice(-1)[0];
+const trendParts = [];
+if (yesterday) {
+  trendParts.push('docs ' + docsTotal + '（昨日 ' + (yesterday.docsTotal ?? '?') + '）');
+  trendParts.push('确认调用 ' + confirmThis + '（昨日 ' + (yesterday.confirmCalls ?? '?') + '）');
+} else {
+  trendParts.push('无前值（history 首日）');
+}
+const trendLine = '> 趋势（环比昨日）：' + trendParts.join('；') + '；确认调用本月 ' + confirmThis + ' 次（上月 ' + confirmPrev + ' 次' + (confirmDelta === null ? '' : '，' + (confirmDelta >= 0 ? '+' : '') + confirmDelta + '%') + '；void 不计）';
+
+// 注入「闭环漏斗」节尾（inner 的 FUNNEL 段之后、END 之前）
+
+fs.writeFileSync(METRICS_P, out.replace(END, trendLine + '\n\n' + END), 'utf8');
 console.log(`✅ 已更新 workflow/metrics.md（${month} 行；共 ${rows.length} 个月）`);

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

@@ -39,7 +39,6 @@ const USAGE = `用法: node .agents/scripts/kb-search.mjs [选项] <词1> [词2
 
 const args = process.argv.slice(2);
 let scope = '';
-let scopeExplicit = false;
 let typeFilter = null;
 let moduleFilter = '';
 let statusFilter = 'all';
@@ -53,7 +52,7 @@ let rebuild = false;
 const words = [];
 for (let i = 0; i < args.length; i++) {
   const a = args[i];
-  if (a === '--scope') { scope = args[++i] || ''; scopeExplicit = true; }
+  if (a === '--scope') { scope = args[++i] || ''; }
   else if (a === '--type') typeFilter = (args[++i] || '').split(',').map((s) => s.trim()).filter(Boolean);
   else if (a === '--module') moduleFilter = args[++i] || '';
   else if (a === '--status') statusFilter = args[++i] || '';

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

@@ -109,7 +109,7 @@ const files = (out) => (out.match(/^📄 (workflow\/\S+)/gm) || []).map((l) => l
 // ---- 场景 5：增量失效——warm 后改 1 个源文件，仅该文件重解析且输出与纯扫一致 ----
 {
   const root = mkfix();
-  const base = run(root, ['编码模板']);
+  run(root, ['编码模板']);
   const planP = path.join(root, 'workflow', 'plans', '2026-09-20-ccc.md');
   fs.appendFileSync(planP, '\n## 影响面\n- 新标记NEWWORD：编码模板修订\n', 'utf8');
   const after = run(root, ['编码模板', 'NEWWORD']);