agentic-flow-kit 1.8.2 → 2.0.0

package/templates/engine/.agents/tests/tools/gen-synthetic-plan.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// gen-synthetic-plan.mjs — 开发全景图规模压测合成器（零依赖；引擎面工具，非 node:test 用例）
+// 用法：
+//   node .agents/tests/tools/gen-synthetic-plan.mjs <N>       # 生成 N 步合成 plan → .agents/cache/tour-perf/synthetic-<N>.md
+//   node .agents/tests/tools/gen-synthetic-plan.mjs --bench   # N=10/30/60 三档：注入 git 面（300 修改文件，走
+//                                                             # buildTour opts.git 缝合，不往真仓库造任何状态）跑
+//                                                             # buildTour 计时 + gen-dev-tour 生成静态 HTML 记录体积
+// 产物只落 .agents/cache/tour-perf/（.gitignore 已忽略 .agents/cache/）；实测数字登记 dev-tour SKILL「适用规模」节。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, '../../..');
+const OUT_DIR = path.join(ROOT, '.agents', 'cache', 'tour-perf');
+const BENCH_N = [10, 30, 60];
+const PAYLOAD_FILES = 300;
+const FILES_PER_STEP = [3, 4, 5, 4, 3]; // 每步 3~5 个文件循环
+
+function planText(n) {
+  const lines = [];
+  lines.push('---', '标题: 合成压测计划', '状态: 起草中', '级别: L2', '模块: 物资', '日期: 2099-12-31', '---');
+  lines.push('', `# PLAN — 合成压测：${n} 步 × 文件`, '');
+  lines.push('## 任务拆解');
+  for (let i = 1; i <= n; i++) {
+    lines.push(`- [ ] ${i}. T${i} 合成步骤${i}：性能压测用合成说明`);
+    lines.push('  - 判据：合成判据通过');
+  }
+  lines.push('', '## 改动方案');
+  const files = [];
+  for (let i = 1; i <= n; i++) {
+    lines.push(`- **T${i}**：文件组${i}`);
+    const cnt = FILES_PER_STEP[(i - 1) % FILES_PER_STEP.length];
+    for (let k = 0; k < cnt; k++) {
+      const p = i % 3 === 1 ? `backend/perf/Mod${i}/PerfService${i}_${k}.cs`
+        : i % 3 === 2 ? `frontend/src/views/perf/Page${i}${k}.vue`
+        : `frontend/src/api/perf/api${i}_${k}.ts`;
+      files.push(p);
+      lines.push(`  - \`${p}\`：合成改动说明`);
+    }
+  }
+  lines.push('', '## 执行顺序');
+  const clauses = [];
+  for (let i = 2; i <= n; i++) clauses.push(`${i} 依赖 ${i - 1}`);
+  lines.push(`依赖：${clauses.join('；')}`);
+  lines.push('', '## 验证计划');
+  lines.push('- `tests/perf/PerfSmokeTests.cs` 全绿');
+  lines.push('- 手工：合成冒烟');
+  return { text: lines.join('\n') + '\n', files };
+}
+
+// 300 个修改文件：优先取文档登记路径（练习计划面合并），不足补文档外 filler（练习「文档外实际改动」归集）
+function gitPayload(docFiles, total) {
+  const files = {};
+  for (const p of docFiles.slice(0, total)) files[p] = { status: 'modified', actual: true, additions: 10, deletions: 2 };
+  let i = 0;
+  while (Object.keys(files).length < total) {
+    files[`scripts/perf-filler/fill${i}.ps1`] = { status: 'modified', actual: true, additions: 3, deletions: 1 };
+    i++;
+  }
+  return files;
+}
+
+function writePlan(n) {
+  const { text } = planText(n);
+  fs.mkdirSync(OUT_DIR, { recursive: true });
+  const doc = path.join(OUT_DIR, `synthetic-${n}.md`);
+  fs.writeFileSync(doc, text, 'utf8');
+  return doc;
+}
+
+if (process.argv[2] === '--bench') {
+  const modelUrl = pathToFileURL(path.join(ROOT, '.agents', 'scripts', 'dev-tour-model.mjs'));
+  const { buildTour } = await import(modelUrl.href);
+  const rows = [];
+  for (const n of BENCH_N) {
+    const doc = writePlan(n);
+    const { files } = planText(n);
+    const payload = { available: true, base: 'HEAD', baseSha: 'perf00000000', note: '', basePaths: [], files: gitPayload(files, PAYLOAD_FILES) };
+    let ms = 0;
+    let model = null;
+    for (let round = 0; round < 3; round++) {
+      const t0 = performance.now();
+      model = buildTour({ root: ROOT, docPath: doc, base: 'HEAD', git: payload });
+      ms = Math.max(ms, performance.now() - t0); // 3 轮取最大（悲观界）
+    }
+    const html = path.join(OUT_DIR, `synthetic-${n}.html`);
+    const r = spawnSync(process.execPath, [path.join(ROOT, '.agents', 'scripts', 'gen-dev-tour.mjs'), doc, '--no-diff', '--out', html], { cwd: ROOT, encoding: 'utf8' });
+    if (r.status !== 0) {
+      console.error(`gen-dev-tour 失败（N=${n}）：${String(r.stderr).slice(0, 300)}`);
+      process.exit(1);
+    }
+    const size = fs.statSync(html).size;
+    rows.push({ n, steps: model.steps.length, files: model.files.length, ms: Math.round(ms), size });
+    console.log(`N=${n} · ${model.steps.length} 步 × 300 文件 → build ${Math.round(ms)} ms`);
+    console.log(`      HTML：.agents/cache/tour-perf/synthetic-${n}.html · ${(size / 1024).toFixed(0)} KB · 模型文件 ${model.files.length}`);
+  }
+  console.log('拐点判断：以上为实测范围（' + BENCH_N.join('/') + ' 档）；超出范围未验证。');
+  process.exit(0);
+}
+
+const n = Number(process.argv[2]);
+if (!Number.isInteger(n) || n < 1) {
+  console.error('用法：node gen-synthetic-plan.mjs <N> | --bench');
+  process.exit(1);
+}
+console.log(writePlan(n));

package/templates/git/.gitattributes

@@ -0,0 +1,22 @@
+# 合并保护：appsettings.json 数据库连接不参与分支合并，始终保留当前分支版本。
+# 需本地配置 merge.ours.driver true 才生效。
+**/appsettings.json merge=ours
+
+# 台账追加合并驱动——多人并发或单人多 worktree 并行时，.agents/*.jsonl
+# 尾部并发追加自动并集去重合并，避免文本冲突。需本地配置 merge.jsonl-union.driver 生效。
+.agents/*.jsonl merge=jsonl-union
+.agents/confirmations.d/*.jsonl merge=jsonl-union
+workflow/gate-metrics.d/*.jsonl merge=jsonl-union
+
+# 工作流台账合并策略：三个生成物保留本侧，合并后跑 regen-ledgers 重生成；
+# delegations.md 手工行纯追加 → 行级并集。
+workflow/INDEX.md merge=ours
+workflow/metrics.md merge=ours
+workflow/verify-evidence.md merge=ours
+workflow/delegations.md merge=jsonl-union
+
+# check-delete-guard.mjs 用 diff 逐字节比对本文件与 LF 扫描输出，强制 LF。
+.agents/hooks/delete-guard-allowlist.txt text eol=lf
+
+# ZCode dwf 工作流文件：加载器按 \n 切分元数据块且不剥 \r，强制 LF。
+*.dwf.ts text eol=lf

package/templates/git/.githooks/commit-msg

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Git commit-msg hook：提交类型枚举校验（自 pre-commit 迁入，papercut 升级修复；
+// 全 node 化。CommonJS——无扩展名文件 node 缺省按 CJS 解析，不依赖 ESM 语法探测）
+// AGENTS.md「git提交」：Conventional Commits 中文，feat/fix/docs/style/refactor/perf/chore
+// 豁免仅限真实 merge/revert/squash 形态：git 默认消息（Merge …/Revert …/Squashed commit of the following:）
+// 与自定义小写 merge:/revert: 前缀（2026-11-06 P2-B2 补 squash 模板——该行由 git 生成，非作者笔误）。
+// 收紧：不再匹配任意 merge/revert 开头（如 "merged xxx"），空首行不再豁免（fail-closed）。
+// process.argv[2] 为 git 传入的本次消息文件（真实待提交内容）
+// 枚举/正则单源：.agents/config/commit-msg-rules.json（2026-11-05 抽出，CI 检出 ci-commit-hygiene.mjs
+// 同源消费；JSON 兼容本文件 CJS 与 CI 脚本 ESM 两读法）。规则读不到 = fail-closed 拒提交。
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const RULES = path.join(__dirname, '..', '.agents', 'config', 'commit-msg-rules.json');
+let types = [];
+let exemptRe = null;
+let typeRe = null;
+try {
+  const rules = JSON.parse(fs.readFileSync(RULES, 'utf8'));
+  types = rules.types;
+  exemptRe = new RegExp(rules.exemptPrefix);
+  typeRe = new RegExp('^(' + rules.types.join('|') + ')' + rules.typeSuffix);
+} catch (e) {
+  console.error(`commit-msg: 规则单源 ${RULES} 读取失败（${e.message}），fail-closed 拒绝提交`);
+  process.exit(1);
+}
+
+const msgFile = process.argv[2];
+let first = '';
+try { first = fs.readFileSync(msgFile, 'utf8').split(/\r?\n/)[0] || ''; } catch { /* 读不到 = 空首行 fail-closed */ }
+const exempt = exemptRe.test(first);
+if (!exempt && !typeRe.test(first)) {
+  console.error(`commit-msg: 提交类型须为 ${types.join('/')}（AGENTS.md「git提交」），当前首行：${first}`);
+  process.exit(1);
+}
+
+// 先确认后改代码（2026-11-08 档 2-D 自 pre-commit 位移）：pre-commit 时点读不到提交消息，
+// 豁免 A（L0 trailer）与豁免 B（同批 done plan，L1 单笔提交）都要在消息可见的时点执法。
+// 暂存产品路径才启动（廉价前缀过滤与原 pre-commit 同口径）；精确判据单源
+// check-confirm-order.mjs。合并自动提交在 commit-msg 时点 MERGE_HEAD / SQUASH_MSG 已落盘，
+// 由脚本内状态文件探测跳过；缺失 fail-closed（与其余门同口径）。
+const GATE = path.join(__dirname, '..', '.agents', 'hooks', 'check-confirm-order.mjs');
+if (!fs.existsSync(GATE)) {
+  console.error('commit-msg: 门脚本缺失 .agents/hooks/check-confirm-order.mjs——提交已阻止（脚本随仓走；git checkout -- .agents/hooks/check-confirm-order.mjs 恢复后重试）');
+  process.exit(1);
+}
+const staged = spawnSync('git', ['-c', 'core.quotepath=off', 'diff', '--cached', '--name-only'], { encoding: 'utf8' });
+const touchesProduct = String(staged.stdout || '').split(/\r?\n/).some((f) => {
+  const rel = f.trim().replace(/\\/g, '/');
+  return rel.startsWith('backend/') || rel.startsWith('frontend/src/') || rel.startsWith('tests/')
+    || rel.startsWith('wiki/数据维护/');
+});
+if (touchesProduct) {
+  const gate = spawnSync(process.execPath, [GATE, msgFile], { stdio: 'inherit' });
+  if (gate.status !== 0) {
+    console.error('commit-msg: 先确认后改代码未通过，提交已阻止');
+    process.exit(gate.status === null ? 1 : gate.status);
+  }
+}
+
+// 任务短名校验（2026-11-09 建，advisory 先行）：覆盖 plan 恰好一份时提交消息须含其短名，
+// git log 可按任务检索。脚本内部 exit 恒 0（观察期不阻断），缺失 fail-closed（与其余门同口径）。
+const PLAN_REF = path.join(__dirname, '..', '.agents', 'hooks', 'check-commit-plan-ref.mjs');
+if (!fs.existsSync(PLAN_REF)) {
+  console.error('commit-msg: 门脚本缺失 .agents/hooks/check-commit-plan-ref.mjs——提交已阻止（脚本随仓走；git checkout -- .agents/hooks/check-commit-plan-ref.mjs 恢复后重试）');
+  process.exit(1);
+}
+if (touchesProduct) {
+  spawnSync(process.execPath, [PLAN_REF, msgFile], { stdio: 'inherit' });
+}
+process.exit(0);

package/templates/git/.githooks/post-commit

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Git 原生 post-commit hook（经 core.hooksPath 挂载，git commit 后触发；全 node 化。
+// CommonJS——无扩展名文件 node 缺省按 CJS 解析，不依赖 ESM 语法探测）
+// 非阻断缓存维护：把本次提交触及的 workflow/、wiki/ 文件从 kb-search 结构缓存
+//   （.agents/cache/kb-index.json）摘除，收敛 [mtimeMs,size] 两元组的
+//   「同刻同尺寸」失效盲区至提交时点。
+// 判据与设计：workflow/intents/2026-09-23-kb-cache-post-commit-evict.md
+// 另有推送积压提醒（eli5 卡片 5）：ahead ≥ 10 且每满 5 一提——本地 @{upstream}
+//   引用口径（不 fetch，滞后只致少报），advisory 一行，永不阻断。
+// 失败绝不影响提交结果：post-commit 本身非阻断 + evict 脚本坏输入静默 exit 0 + 此处 try 双重兜底。
+const { spawnSync } = require('node:child_process');
+
+try {
+  // 2026-11-06 修（P1-4）：原参数 `diff-tree --no-commit-id --name-only -r HEAD` 有三重缺陷，
+  // 使缓存摘除在若干形态下静默不发生：
+  //   ① 缺 `-c core.quotepath=off`——git 默认 quotepath=true 会把非 ASCII 路径转义为
+  //      `"wiki/\345\217\246..."`，而 kb-cache-evict.mjs 以 startsWith('wiki/') 过滤，
+  //      转义行首是 `"` 一条都不匹配 → 本仓 783 个中文路径 wiki/workflow 文件永不摘除
+  //      （本机全局 .gitconfig 恰为 quotepath=false 才未暴露，换机/CI 复现）。
+  //   ② 缺 `-m`——合并提交默认输出为空（实测），合并带入的文档变更不摘缓存。
+  //   ③ 缺 `--root`——首个提交默认输出为空（实测）。
+  // 非合并提交下 `-m`/`--root` 无副作用（单父即默认行为，实测零差异）。
+  // 同源口径：pre-commit/pre-push/check-ledger-* 的 git diff 均显式带 core.quotepath=off。
+  const files = spawnSync('git', ['-c', 'core.quotepath=off', 'diff-tree', '--no-commit-id', '--name-only', '-r', '-m', '--root', 'HEAD'], { encoding: 'utf8' });
+  if (files.status === 0) {
+    spawnSync(process.execPath, ['.agents/scripts/kb-cache-evict.mjs'], { input: files.stdout, stdio: ['pipe', 'ignore', 'ignore'] });
+  }
+} catch { /* 非阻断三重兜底之一 */ }
+
+// 推送积压提醒（eli5 卡片 5「勤推小步」）：合并冲突成本 ∝ 双方分歧规模，本地积压即分歧的一半。
+// intentional-simple: 阈值 10 / 步长 5 硬编码——调整即改此两处，无需配置面。
+try {
+  const aheadRun = spawnSync('git', ['rev-list', '--count', '@{upstream}..HEAD'], { encoding: 'utf8' });
+  const ahead = aheadRun.status === 0 ? Number(String(aheadRun.stdout || '').trim()) : NaN;
+  if (Number.isInteger(ahead) && ahead >= 10 && ahead % 5 === 0) {
+    console.error(`post-commit: 已领先 upstream ${ahead} 个提交（本地引用口径）——勤推小步别攒大包袱，确认后 git push`);
+  }
+} catch { /* 提醒失败不影响提交 */ }
+
+// 离线梦境提醒（2026-11-11，Dreaming 持续运行链路）：距上次离线梦境审计报告 ≥7 天或无报告，
+// 则 stderr 打一行 advisory 提醒跑 dream-run --execute。advisory 非阻断，失败不影响提交。
+try {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const tmpDir = path.join(__dirname, '..', 'tmp'); // post-commit 位于 .githooks/，仓库根为上一级
+  let latest = '';
+  if (fs.existsSync(tmpDir)) {
+    for (const f of fs.readdirSync(tmpDir)) {
+      const m = f.match(/^dream-report-(\d{4}-\d{2}-\d{2})\.md$/);
+      if (m && m[1] > latest) latest = m[1];
+    }
+  }
+  if (!latest) {
+    console.error('[dream] 尚无离线梦境审计报告——可跑 node .agents/scripts/dream-run.mjs --execute（advisory，非阻断）');
+  } else {
+    const days = Math.floor((Date.now() - Date.parse(`${latest}T00:00:00Z`)) / 86400000);
+    if (days >= 7) {
+      console.error(`[dream] 距上次离线梦境审计（${latest}）已 ${days} 天——可跑 node .agents/scripts/dream-run.mjs --execute（advisory，非阻断）`);
+    }
+  }
+} catch { /* 提醒失败不影响提交 */ }
+process.exit(0);

package/templates/git/.githooks/pre-commit

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+// Git 原生 pre-commit hook（经 core.hooksPath 挂载）— 本仓自有编排（decouple-flow-kit 起；
+// 全 node 化：钩子体不再含 sh 逻辑——git 仍以自带 sh 启动本文件（钩子机制要求），但她bang
+// 即 node，PATH 无 sh 不再影响任何逻辑；语言单化后 CI 代理/本地行为一致。
+// 写法为 CommonJS——无扩展名文件 node 缺省按 CJS 解析，不依赖 ≥22.7 的 ESM 语法探测）
+// 通用门禁序（2026-10-21 撤出提交时刻 advisory 五门：配对增量 / 泳道 / wiki 台账 / 叙事承重 / 索引漂移——
+// 四支孤儿增量脚本（配对/叙事/索引/wiki 台账）同日止血批删除，仅 lane-surface 留存（verify 在用）。
+// 撤后去向：配对在 pre-push/关单的 check-loop 已降 WARN（同日门禁极小化第 1 批——红线判低/L3 状态
+// 仍 hard，配对自查走 closeout skill §0）；泳道产品面硬拦 verify lane-surface-ci；wiki 在 verify
+// wiki-consistency；索引/叙事等 hygiene 段已于 2026-10-28 全部退役（引擎减重第一刀））：
+// 【硬拦】确认台账不变量(触及才跑) → 项目门禁(local-pre-commit：架构红线/审计回填/删除守卫/通知守卫，四门并行) → 提交验证(commit-check.cjs；常规提交 --no-build——条件构建后移 pre-push，合并提交仍 --full)
+// 项目专属门禁放 .agents/hooks/local-pre-commit.mjs——存在即在本钩子内执行，返回非零即阻断提交
+// 合并提交场景由 .githooks/pre-merge-commit 原样转发到本脚本（合并时 git 调的是 pre-merge-commit，
+// 不是 pre-commit）——门禁清单只此一份，避免两处分叉
+// fail-closed（口径；随 node 化天然成立——本进程即 node）：门脚本缺失 = 拒提交；
+// 仅 local-pre-commit.mjs 保留「存在即执行」挂载点语义（缺失打 advisory）。
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+
+const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (top.status !== 0 || !top.stdout.trim()) {
+  console.error('pre-commit: 无法定位仓库根（git rev-parse --show-toplevel 失败）——提交已阻止');
+  process.exit(1);
+}
+process.chdir(top.stdout.trim());
+
+// `--merge` 由 .githooks/pre-merge-commit 显式透传：2026-11-06 P1-1 起曾转发给「先确认后改代码」门；
+// 2026-11-08 档 2-D 该门位移 commit-msg 后本钩子不再消费它——仅在下传 commit-check 前滤除（见文末）。
+// 合并自动提交的顺序门跳过信号由 commit-msg 时点的 MERGE_HEAD 等状态文件探测承担（彼时已落盘）。
+
+// gate(label, script, args)：node 直跑门脚本，非零即阻断（含 fail-closed 缺失检查）
+const requireScript = (rel) => {
+  if (!fs.existsSync(rel)) {
+    console.error(`pre-commit: 门脚本缺失 ${rel}——提交已阻止（脚本随仓走；git checkout -- ${rel} 恢复后重试）`);
+    process.exit(1);
+  }
+};
+const gate = (label, script, args = []) => {
+ requireScript(script);
+ const r = spawnSync(process.execPath, [script, ...args], { stdio: 'inherit' });
+ if (r.status !== 0) {
+ console.error(`pre-commit: ${label} 未通过，提交已阻止`);
+ process.exit(r.status === null ? 1 : r.status);
+ }
+};
+
+// （decouple-flow-kit：原「双源一致性 source-sync-check --gate」与「managed 台账快检」两段
+//   已随 kit 解耦删除——两段挂载条件均为包源环境（templates/_agents/），本仓恒假，纯死段。）
+
+// 确认台账不变量前置（--staged，ledger-ci-invariant）：暂存的台账文件必须是各自 HEAD 版本的
+// 逐字节前缀扩展（append-only）——本地提交时刻即拦「顺手重写台账」，CI 历史全扫兜底。
+// ledger-shard-default：确认行默认写 .agents/confirmations.d/<doc>.jsonl 分片，故触发条件
+// 自「仅主台账」扩到「主台账 ∪ 任一分片」——否则默认写入形态下这道门根本不触发，等于关门。
+// 暂存未触任何台账静默；触台账而脚本缺失 fail-closed 阻断。
+const staged = spawnSync('git', ['-c', 'core.quotepath=off', 'diff', '--cached', '--name-only'], { encoding: 'utf8' });
+const stagedFiles = String(staged.stdout || '').split(/\r?\n/).filter(Boolean).map((f) => f.replace(/\\/g, '/'));
+
+// 常驻面体积预算：2026-10-28 退出提交钩子（owner 决策：pre-commit 只留业务门与台账不变量）；
+// 2026-10-29 条件回接（触及预算面才跑）：引擎面直提不经 verify，越限到关单/CI 才红——当日实证
+// runtime-env 越限 972B 无人拦（引擎直提面实为无人执法）。判据单源 rule-budget --staged（只查触及条目），
+// 常规提交零成本；触发面单源 = .agents/config/rule-budgets.txt 首列（改预算表本条件随动）。
+const touchesBudgetFace = (() => {
+  try {
+    const txt = fs.readFileSync('.agents/config/rule-budgets.txt', 'utf8').replace(/\r/g, '');
+    // 触发面 = 首列为「路径形态」的条目（含 / 或含 .）。2026-11-06 修：原判据 `p.includes('/')`
+    // 把根级条目 `AGENTS.md`（预算表首行 8704B，引擎直提最常改的一份）当非路径行滤掉——该条目
+    // 的预算门在提交时刻恒不触发，正是「引擎直提面无人执法」的原始缺口。改用「含 / 或含 .」后
+    // 根级 .md 条目纳入；伪路径行 `check-loop-hard`（既无 / 也无 .）不再靠本判据排除，改显式映射。
+    // 伪路径 `check-loop-hard 5#count` 的执法面在 rule-budget.mjs:118（数 check-loop.mjs 的 hard 段），
+    // 其 --staged 分支只在 check-loop.mjs 或预算表被暂存时才查——故触发面须含这两个实体，
+    // 否则「改段表却绕过段数棘轮」（2026-11-06 实测 D 例）。
+    const PSEUDO_FACE = { 'check-loop-hard': '.agents/scripts/check-loop.mjs' }; // 段数棘轮：伪路径 → 实体
+    const pats = [...new Set(txt.split('\n').filter((l) => l && !l.startsWith('#'))
+      .map((l) => l.split(/\s+/)[0])
+      .filter((p) => p && p !== 'check-loop-hard' && (p.includes('/') || p.includes('.')))
+      .concat(Object.values(PSEUDO_FACE), ['.agents/config/rule-budgets.txt']))];
+    return stagedFiles.some((f) => pats.some((p) => {
+      if (p.endsWith('/')) return f.startsWith(p);
+      if (p.includes('*')) return new RegExp('^' + p.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*') + '$').test(f);
+      return f === p;
+    }));
+  } catch { return false; } // 缺预算表 = 沙箱语义（rule-budget 自身同态 exit 0）
+})();
+if (touchesBudgetFace) {
+  console.log('pre-commit: 触及预算面——跑 rule-budget --staged（常驻面体积，触及条目）');
+  gate('常驻面预算（触及预算面）', '.agents/scripts/rule-budget.mjs', ['--staged']);
+} else {
+  console.log('SKIP: 未触及预算面（rule-budgets.txt 条目）——预算门由 verify/CI 兜底');
+}
+
+const touchesLedger = stagedFiles.includes('.agents/confirmations.jsonl')
+  || stagedFiles.some((f) => f.startsWith('.agents/confirmations.d/'));
+if (touchesLedger) {
+  gate('确认台账不变量', '.agents/scripts/check-ledger-invariant.mjs', ['--staged']);
+}
+
+// 台账分片归位（2026-10-27 ledger-shards-check）：主台账残留数据行 = 分片体系漏网，
+// 会被 agg-delegations 的 splitTables 静默丢弃（实测 delegations 38 行残留在「月度聚合快照」
+// 节之后 → 聚合 exit 1「550 行日期数据，解析入账 512」，其中 10 行只存主台账，直接影响扩容门指标）。
+// 触发面 = 四本分片台账任一被暂存（追加/迁片/改主表都可能造成残留）；未触及静默，不给常规提交加税。
+// 判据单源 ledger-shards --check（<50ms，纯本地读文件）。
+const shardLedgers = ['workflow/delegations.md', 'workflow/papercuts.md', 'workflow/regression-checklist.md', 'workflow/deploy-observations.md'];
+const shardDirs = ['workflow/delegations.d/', 'workflow/papercuts.d/', 'workflow/regression-checklist.d/', 'workflow/deploy-observations.d/'];
+const touchesShardLedger = stagedFiles.some((f) => shardLedgers.includes(f) || shardDirs.some((d) => f.startsWith(d)));
+if (touchesShardLedger) {
+  gate('台账分片归位', '.agents/scripts/ledger-shards.mjs', ['--check']);
+}
+
+// 台账指针存在性（2026-10-24 复核 m5 补挂）：删除 intents/specs/plans/incidents 文档而不走
+// `confirm-doc --to cancelled|superseded` 会让台账行悬空。全量检查约 500 次 existsSync（<100ms），
+// 但只在本次提交**删除/移走**这四目录文件时触发——不给常规提交加税。
+// 判据单源 check-ledger-doc-presence.mjs（与 check-ledger-invariant 行级④同口径，含 archive 回退）。
+// 2026-11-06（P2-B1）：原 `--diff-filter=D` 漏 `git mv`——改名记 `R`（旧路径在第 2 列、新路径在第 3 列），
+// 门恒不触发，指针悬空照常落库。改为 `DR` + 显式 `-M`（不依赖用户 diff.renames 配置），并**按第 2 列
+// （旧路径）**判目录：取第 3 列会把「移入四目录」误判成「移出」，方向相反。
+const DOC_DIRS = ['workflow/intents/', 'workflow/specs/', 'workflow/plans/', 'workflow/incidents/'];
+const deletedDocs = spawnSync('git', [
+  '-c', 'core.quotepath=off', 'diff', '--cached', '--name-status', '--diff-filter=DR', '-M',
+], { encoding: 'utf8' });
+const deletedDocLines = String(deletedDocs.stdout || '').split(/\r?\n/).filter(Boolean)
+  .map((l) => l.split('\t'))
+  .filter((f) => f.length >= 2 && DOC_DIRS.some((d) => f[1].startsWith(d)));
+if (deletedDocLines.length) {
+  gate('台账指针存在性', '.agents/scripts/check-ledger-doc-presence.mjs', ['--staged']);
+}
+
+// 提交期可见性 advisory（2026-11-10，incident 2026-10-26-workflow-confirmation-drift-hard-block 三件套 #1）：
+// 改已关单（done/superseded/closed/cancelled/fixed）workflow 文档正文而同笔无确认台账变更，此前要到
+// 下次关单 check-loop §15 才炸 [确认内容漂移]——前移到提交时刻打 advisory（exit 0 恒不拦、输出不进
+// COMMIT_CHECK_OK 判定；执法面仍是 check-loop §15 关单对账，本门不合门）。触发面 = 暂存含
+// workflow/{intents,specs,plans,incidents}/*.md，未触及静默不给常规提交加税；脚本缺失打 advisory
+// 不阻断（advisory 语义，与 local-pre-commit 挂载点同款）。
+const touchesWorkflowDocFace = stagedFiles.some((f) => /^workflow\/(intents|specs|plans|incidents)\/[^/]+\.md$/.test(f));
+if (touchesWorkflowDocFace) {
+  if (!fs.existsSync('.agents/scripts/check-doc-body-drift.mjs')) {
+    console.error('pre-commit: （advisory）.agents/scripts/check-doc-body-drift.mjs 不在场——提交期正文漂移可见性失效，若为误删请 git checkout -- .agents/scripts/check-doc-body-drift.mjs');
+  } else {
+    console.log('pre-commit: 触及 workflow 四目录文档面——跑 check-doc-body-drift（已关单正文漂移 advisory，不合门）');
+    spawnSync(process.execPath, ['.agents/scripts/check-doc-body-drift.mjs', '--staged'], { stdio: 'inherit' });
+  }
+}
+
+// 密钥扫描本地腿退役（2026-10-21，owner 指令「密钥本地不扫」）：pre-commit 不再扫密钥——原
+// gitleaks protect 暂存增量门与 commit-check.cjs 敏感信息正则段同批撤除（后者误报 papercut ×4 消债）。
+// 执法面收敛 verify 安全段 secrets-scan（关单 + CI main 全量 detect+基线；develop 引擎段不含 security 门）。
+// 登记：mechanism-registry「密钥扫描门」行 + runtime-env §6.5 退役行 + papercuts 2026-10-14 行闭环。
+
+// 先确认后改代码（2026-11-03 建）已于 2026-11-08 档 2-D 位移 .githooks/commit-msg：
+// pre-commit 时点读不到提交消息，豁免 A（L0 trailer）与豁免 B（同批 done plan）都要在消息可见
+// 的时点执法。判据单源 .agents/hooks/check-confirm-order.mjs，本钩子不再启动该门。
+
+// 项目门禁挂载点：.agents/hooks/local-pre-commit.mjs（项目自建门禁/门禁模块接线处，存在即执行；
+// 自 sh 移植 node。挂载点语义保留「可选」：缺失打 advisory 不阻断（-kit 契约），
+// 但缺失不再无声——本仓该文件随仓走，advisory 即误删信号。
+// 2026-10-29 条件化（AI 写路径拦截已前移宿主写前门 .agents/hooks/pre-write-check.cjs——
+// 快照复用同一批 check-*.mjs，判据单源不变）：四门改**触及代码面才跑**（backend/**/*.cs|csproj|sln
+// 或 frontend/src/**），纯文档/台账提交零成本。四门仍保留于此——2026-11-11 起已接入 verify product
+// cohort（CI --mid/--full 执法；本地增量档单边化 CI，口径单源 verify-scope.CI_UNILATERAL_GATE_IDS），
+// 本地 pre-commit 仍是最早拦截点：手工编辑（不经宿主）提交时刻即拦，不得再撤（mechanism-registry 口径）。
+const touchesCodeFace = stagedFiles.some((f) =>
+  (/^backend\/.+\.(cs|csproj|sln)$/i.test(f)) || f.startsWith('frontend/src/'));
+if (!fs.existsSync('.agents/hooks/local-pre-commit.mjs')) {
+  console.error('pre-commit: （advisory）项目门禁挂载点 .agents/hooks/local-pre-commit.mjs 不在场——本仓该文件随仓走，若为误删请 git checkout -- .agents/hooks/local-pre-commit.mjs');
+} else if (touchesCodeFace) {
+  gate('项目门禁（local-pre-commit）', '.agents/hooks/local-pre-commit.mjs');
+} else {
+  console.log('SKIP: 未触及代码面（backend 源码 / frontend/src），四门跳过——AI 写路径已由宿主写前门拦截');
+}
+
+// 合并提交 → 构建验证覆盖【完整合并树】，不做按扩展名的条件裁剪。
+// 常规提交 --no-build（构建门后移 pre-push）：提交内环只跑敏感扫描，条件构建在推送时按
+// old..new 范围执法（.githooks/pre-push）；合并结果是没人验证过的新状态，仍全量构建。
+// 三条路径：
+//  ① `git merge` 自动提交由 .githooks/pre-merge-commit 显式传 `--full` 转发到本脚本；
+//  ② 冲突解决后手动 `git commit` 由 git 直接调本脚本——按 MERGE_HEAD 探测（此时合并仍在进行）；
+//  ③ `git merge --squash` + `git commit`（2026-10-29 补）：MERGE_HEAD 不存在，但 git 留下
+//     SQUASH_MSG（首行 "Squashed commit of the following:"）——语义同合并提交（树 = 两方结果的
+//     新状态，且被压成一个提交，无人验证过），故同样走 --full。
+//     探测用 `git rev-parse --git-path` 而非字面 `.git/SQUASH_MSG`：linked worktree 下 `.git` 是
+//     文件（内容 `gitdir: ...`），字面路径恒不存在 → 门静默失效（2026-10-29 实测）。
+//     不误判：普通提交与 `git commit --amend` 时点该文件均不存在（实测）。
+const gitPath = (rel) => {
+  const r = spawnSync('git', ['rev-parse', '--git-path', rel], { encoding: 'utf8' });
+  const p = r.status === 0 ? String(r.stdout || '').trim() : '';
+  return p && fs.existsSync(p) ? p : null;
+};
+let fullArgs = process.argv.slice(2).filter((a) => a !== '--merge');
+if (fullArgs.length === 0) {
+  const isMergeOrSquash = gitPath('MERGE_HEAD') !== null || gitPath('SQUASH_MSG') !== null;
+  fullArgs = isMergeOrSquash ? ['--full'] : ['--no-build'];
+}
+
+const cc = spawnSync(process.execPath, ['.agents/hooks/commit-check.cjs', ...fullArgs], { stdio: 'inherit' });
+if (cc.status !== 0) {
+ console.error('pre-commit: 验证未通过，提交已阻止');
+ process.exit(cc.status === null ? 1 : cc.status);
+}

package/templates/git/.githooks/pre-merge-commit

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Git 原生 pre-merge-commit hook（经 core.hooksPath 挂载；全 node 化——转发不再经 sh。
+// CommonJS——无扩展名文件 node 缺省按 CJS 解析，不依赖 ESM 语法探测）
+//
+// 背景：git 对 `git merge` 调的是**本钩子**，不是 pre-commit。此前仓库只挂了
+// pre-commit / pre-push / commit-msg，故合并提交绕过全部门禁、未经任何校验直接落库
+// （2026-09-19 实测，见 workflow/papercuts.md 同日行——那次合并带入后端 .cs 改动，
+// 靠人工补跑静态门 + 全量测试才覆盖到）。
+//
+// 做法：转发到 .githooks/pre-commit（门禁清单只此一份，避免两份拷贝日后分叉），
+// 并显式传 `--full` 与 `--merge`——本钩子「只对 merge 触发」这一身份就是最强信号，无需再去探测
+// MERGE_HEAD（2026-09-19 实测：本时点 MERGE_HEAD 已不可靠）。`--full` 令编译验证
+// 覆盖【完整合并树】、不按扩展名的条件裁剪：合并结果是没人验证过的新状态，且其 diff
+// 相对第一父，裁剪会漏掉需要重跑的一侧。`--merge` 令泳道检查 A 跳过（同窗口 MERGE_HEAD 已不在，已关单产品路径会被误判「产品契约面无活跃入口」）。
+//
+// 冲突解决后手动 `git commit` 走的是 pre-commit 自身，那条路径由 pre-commit 内部的
+// MERGE_HEAD 探测覆盖（此时合并仍在进行，MERGE_HEAD 确定存在）。
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (top.status !== 0 || !top.stdout.trim()) {
+  console.error('pre-merge-commit: 无法定位仓库根——合并提交已阻止');
+  process.exit(1);
+}
+const hook = path.join(top.stdout.trim(), '.githooks', 'pre-commit');
+const r = spawnSync(process.execPath, [hook, '--full', '--merge'], { stdio: 'inherit' });
+process.exit(r.status === null ? 1 : r.status);