agentic-flow-kit 1.8.7 → 2.1.0

package/templates/engine/.agents/hooks/check-confirm-order.mjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+// 先确认后改代码（2026-11-03 建）。2026-11-08 档 2-D：接线自 .githooks/pre-commit 位移到
+// .githooks/commit-msg（规则校验之后）——pre-commit 时点读不到提交消息，豁免 A 的 L0 trailer
+// 必须在消息可见的时点执法；commit-msg 时点合并状态文件（MERGE_HEAD / SQUASH_MSG）已落盘。
+// 提交时刻的顺序信号：暂存了产品路径时，每条路径必须出现在「本次提交能看见」的
+// workflow/plans 正文里，且该 plan 状态为 approved。
+//   看得见 = 已暂存用暂存 blob；否则用 HEAD；都没有则用未跟踪的工作区文件。
+//   done 的历史 plan 不算覆盖（否则旧 plan 里出现过的路径永远放行）；豁免 B（L1 单笔提交）：
+//   覆盖性 plan 文件本身与产品路径同批暂存时 done 亦可（plan(done)+代码+确认分片+凭证一笔入库）。
+//   draft 不算。工作区已改成 approved 但没暂存、HEAD 仍是 draft，也不算。
+// 豁免 A（L0 极简道）：消息体含非空 `L0: <判据>` 行（argv[2] = commit-msg 传入的消息文件）
+//   且暂存产品文件 ≤5（2026-11-10 档二：3→5）→ 放行，judgments 落账记 L0 计数；无消息文件参数时豁免不生效（fail-closed）。
+// 合并 / squash / rebase / cherry-pick 跳过：那是在收已经写过的树，不在这里重判顺序。
+//   合并的识别优先看 `--merge`，再看状态文件。
+// 产品路径：backend 源码、frontend/src、tests 下的 cs、数据维护 SQL。精确过滤在本文件。
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { LEDGER_REL } from '../scripts/judgment-ledger.mjs';
+
+const PRODUCT_RES = [
+  /^backend\/.+\.(cs|csproj|sln)$/i,
+  /^frontend\/src\/.+\.(vue|ts|tsx)$/i,
+  /^tests\/.+\.cs$/i,
+  /^wiki\/数据维护\/(?:schema变更|数据修复)\/.+\.sql$/i,
+];
+
+// L0 极简道产品文件上限（2026-11-10 档二放宽：3→5；口径单源 new-task.md §L0）
+// 2026-11-11 export：check-scope-range 复用同一上限做推送范围豁免（判据不复制）。
+export const L0_MAX = 5;
+
+export function isProductPath(rel) {
+  return PRODUCT_RES.some((re) => re.test(rel));
+}
+
+export function statusOf(text) {
+  if (!text) return '';
+  const fm = String(text).match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return '';
+  const m = fm[1].match(/^状态:\s*(\S+)/m);
+  return m ? m[1].trim() : '';
+}
+
+// 覆盖性 plan 过滤（2026-11-09 抽 export：check-commit-plan-ref 复用同判据——消息短名校验的覆盖集来源）。
+// approved 照旧；done 仅当 plan 文件本身在同批暂存（豁免 B，L1 单笔提交）。
+export function coveringDocs(docs, staged = new Set()) {
+  return docs.filter((d) => d.text
+    && (d.status === 'approved' || (d.status === 'done' && staged.has(d.rel))));
+}
+
+/** @param {string[]} paths @param {{rel:string,status:string,text:string}[]} docs @param {Set<string>} staged */
+export function decide(paths, docs, staged = new Set()) {
+  const covers = coveringDocs(docs, staged);
+  const uncovered = paths.filter((p) => !covers.some((d) => d.text.includes(p)));
+  return { uncovered };
+}
+
+function git(args, extra = {}) {
+  return spawnSync('git', ['-c', 'core.quotepath=off', ...args], {
+    maxBuffer: 64 * 1024 * 1024,
+    ...extra,
+  });
+}
+
+function gitText(args) {
+  const r = git(args, { encoding: 'utf8' });
+  return { status: r.status, stdout: String(r.stdout || '') };
+}
+
+function gitPathExists(rel) {
+  const r = gitText(['rev-parse', '--git-path', rel]);
+  const p = r.status === 0 ? r.stdout.trim() : '';
+  return Boolean(p && fs.existsSync(p));
+}
+
+function parseLs(stdout, kind) {
+  const map = new Map();
+  for (const line of stdout.split('\n')) {
+    if (!line) continue;
+    const tab = line.indexOf('\t');
+    if (tab < 0) continue;
+    const meta = line.slice(0, tab).split(' ');
+    const rel = line.slice(tab + 1).replace(/\\/g, '/');
+    const sha = kind === 'index' ? meta[1] : meta[2];
+    if (sha && rel.endsWith('.md')) map.set(rel, sha);
+  }
+  return map;
+}
+
+function catBatch(shas) {
+  const unique = [...new Set(shas)];
+  const out = new Map();
+  if (unique.length === 0) return out;
+  const run = git(['cat-file', '--batch'], { input: Buffer.from(`${unique.join('\n')}\n`) });
+  if (run.status !== 0 || !run.stdout) return out;
+  const buf = run.stdout;
+  let off = 0;
+  while (off < buf.length) {
+    const nl = buf.indexOf(0x0a, off);
+    if (nl < 0) break;
+    const parts = buf.slice(off, nl).toString('utf8').split(' ');
+    if (parts.length < 3 || parts[1] === 'missing') {
+      off = nl + 1;
+      continue;
+    }
+    const size = Number(parts[2]);
+    const start = nl + 1;
+    out.set(parts[0], buf.slice(start, start + size).toString('utf8'));
+    off = start + size + 1;
+  }
+  return out;
+}
+
+function walkPlans(dir, acc) {
+  if (!fs.existsSync(dir)) return acc;
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    const rel = path.join(dir, ent.name).replace(/\\/g, '/');
+    if (ent.isDirectory()) walkPlans(rel, acc);
+    else if (ent.name.endsWith('.md')) acc.push(rel);
+  }
+  return acc;
+}
+
+function visibleDocs(stagedSet) {
+  const indexMap = parseLs(gitText(['ls-files', '-s', '--', 'workflow/plans']).stdout, 'index');
+  const headMap = parseLs(gitText(['ls-tree', '-r', 'HEAD', '--', 'workflow/plans']).stdout, 'head');
+  const onDisk = walkPlans('workflow/plans', []);
+  const wanted = new Map();
+  const untracked = [];
+  for (const rel of new Set([...indexMap.keys(), ...headMap.keys(), ...onDisk])) {
+    if (!rel.startsWith('workflow/plans/')) continue;
+    if (stagedSet.has(rel) && indexMap.has(rel)) wanted.set(rel, indexMap.get(rel));
+    else if (headMap.has(rel)) wanted.set(rel, headMap.get(rel));
+    else if (!headMap.has(rel) && !indexMap.has(rel)) untracked.push(rel);
+  }
+  const blobs = catBatch([...wanted.values()]);
+  const docs = [];
+  for (const [rel, sha] of wanted) {
+    const text = blobs.get(sha);
+    if (text == null) continue;
+    docs.push({ rel, status: statusOf(text), text });
+  }
+  for (const rel of untracked) {
+    let text = '';
+    try { text = fs.readFileSync(rel, 'utf8'); } catch { continue; }
+    docs.push({ rel, status: statusOf(text), text });
+  }
+  return { docs, onDisk };
+}
+
+function hints(uncovered, docs, onDisk) {
+  const draftHits = [];
+  const unstagedApproved = [];
+  for (const rel of onDisk) {
+    let text = '';
+    try { text = fs.readFileSync(rel, 'utf8'); } catch { continue; }
+    if (!uncovered.some((p) => text.includes(p))) continue;
+    const st = statusOf(text);
+    if (st === 'draft') draftHits.push(rel);
+    if (st === 'approved') {
+      const visible = docs.find((d) => d.rel === rel);
+      if (!visible || visible.status !== 'approved') unstagedApproved.push(rel);
+    }
+  }
+  return { draftHits, unstagedApproved };
+}
+
+// 豁免 A（L0 极简道）判据：消息体含非空 `L0: <判据>` 行（行首 L0:，机器可 grep）。
+// 读不到消息文件 / 无该行 → 返回 null，豁免不生效（fail-closed）。
+// 2026-11-09 export：check-commit-plan-ref 复用同判据做 L0 豁免 skip。
+// 2026-11-11 抽 l0JudgementFromText：check-scope-range 从提交消息文本（git log --format=%B）
+// 复用同一正则，不在推送侧复制判据。
+export function l0JudgementFromText(text) {
+  if (!text) return null;
+  const m = String(text).match(/^L0:[ \t]*(\S.*)$/m);
+  return m ? m[1].trim() : null;
+}
+export function l0Judgement(msgFile) {
+  if (!msgFile) return null;
+  try { return l0JudgementFromText(fs.readFileSync(msgFile, 'utf8')); } catch { return null; }
+}
+
+// L0 放行落账：与 judgment-ledger recordRun 同行形（mode=commit-msg）；level=L0 为观测计数，
+// 非 WARN/BLOCK，不影响退役判据的「连续 6 月 = 0」口径（那是针对 hard 拒绝计数的）。fail-open。
+function recordL0(root, count, judgement) {
+  try {
+    if (process.env.CHECK_LOOP_ROOT || process.env.CHECK_LOOP_NO_LEDGER) return;
+    const r = spawnSync('git', ['rev-parse', '--short', 'HEAD'], { encoding: 'utf8' });
+    const row = {
+      ts: new Date().toISOString(),
+      mode: 'commit-msg',
+      rev: r.status === 0 ? String(r.stdout).trim() || null : null,
+      blockers: 0,
+      warnings: 0,
+      rules: [{ rule: '先确认后改代码', level: 'L0', count, judgement }],
+    };
+    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}`);
+  }
+}
+
+// 合并形态判定（2026-11-09 抽 export：check-commit-plan-ref 复用——收树不重判，短名校验同样跳过）。
+// `--merge` = .githooks/pre-merge-commit 透传的「本次是合并自动提交」信号（该钩子时点 MERGE_HEAD
+// 尚未落盘，实测只靠状态文件探测会漏判）；状态文件覆盖 squash/rebase/cherry-pick。
+export function isMergeLike(argv = process.argv) {
+  return argv.includes('--merge')
+    || ['MERGE_HEAD', 'SQUASH_MSG', 'REBASE_HEAD', 'CHERRY_PICK_HEAD'].some(gitPathExists);
+}
+
+// 暂存覆盖集采集（2026-11-09 抽 export：check-commit-plan-ref 复用——同一批暂存、同一套
+// 「看得见」语义与豁免 B 口径，判据单源不复制）。error='staged-unreadable' = 暂存列表读不到。
+export function collectStagedCoverage() {
+  const staged = gitText(['diff', '--cached', '--name-only', '--diff-filter=ACMRD']);
+  if (staged.status !== 0) return { error: 'staged-unreadable' };
+  const stagedFiles = staged.stdout.split(/\r?\n/).filter(Boolean).map((f) => f.replace(/\\/g, '/'));
+  const products = stagedFiles.filter(isProductPath);
+  const stagedSet = new Set(stagedFiles);
+  // 豁免 B 的「同批暂存」只认新增/修改（ACMR）——同批删除中的 plan 不构成覆盖（2026-11-08 C-002 整改：
+  // 旧行为把 D 项计入覆盖集，删旧 plan 的提交可借其正文放行产品路径，超出「同批暂存一笔入库」意图）。
+  // 第二次取数失败 → 空集 → 豁免 B 不生效（fail-closed）。
+  const stagedAddedRaw = gitText(['diff', '--cached', '--name-only', '--diff-filter=ACMR']);
+  const stagedAdded = new Set((stagedAddedRaw.status === 0 ? stagedAddedRaw.stdout : '')
+    .split(/\r?\n/).filter(Boolean).map((f) => f.replace(/\\/g, '/')));
+  const { docs, onDisk } = visibleDocs(stagedSet);
+  return { stagedFiles, products, stagedSet, stagedAdded, docs, onDisk };
+}
+
+function main() {
+  // 2026-11-06（P1-1）：见 isMergeLike 头注。
+  if (isMergeLike()) {
+    console.log('SKIP: 先确认后改代码——合并(--merge)/squash/rebase/cherry-pick，不重判顺序');
+    process.exit(0);
+  }
+  const msgFile = process.argv.slice(2).find((a) => a !== '--merge');
+  const cov = collectStagedCoverage();
+  if (cov.error) {
+    console.error('check-confirm-order: 无法读取暂存列表，提交已阻止');
+    process.exit(1);
+  }
+  const { products, stagedAdded, docs, onDisk } = cov;
+  if (products.length === 0) {
+    console.log('SKIP: 先确认后改代码——未暂存产品路径');
+    process.exit(0);
+  }
+
+  const { uncovered } = decide(products, docs, stagedAdded);
+  if (uncovered.length === 0) {
+    console.log(`先确认后改代码：${products.length} 条产品路径已写在 approved plan 里（或覆盖 plan 与本批同暂存）`);
+    process.exit(0);
+  }
+  const l0 = l0Judgement(msgFile);
+  if (l0 && products.length <= L0_MAX) {
+    console.log(`放行（豁免 A · L0 极简道）：${products.length} 条产品路径 ≤${L0_MAX}，消息判据「${l0}」；L0 计数已落账`);
+    recordL0(process.cwd(), products.length, l0);
+    process.exit(0);
+  }
+  const { draftHits, unstagedApproved } = hints(uncovered, docs, onDisk);
+  const shown = uncovered.slice(0, 20);
+  console.error('BLOCK: 先确认后改代码');
+  console.error('以下暂存路径没有出现在状态为 approved 的 workflow/plans 正文中（done 历史 plan 不算；与产品同批暂存的 done plan 算）：');
+  for (const p of shown) console.error(`- ${p}`);
+  if (uncovered.length > shown.length) console.error(`- …另有 ${uncovered.length - shown.length} 条`);
+  if (draftHits.length) {
+    console.error('这些路径写在仍为 draft 的 plan 里，先 confirm-doc 收到 approved，再暂存代码：');
+    for (const d of draftHits) console.error(`- ${d}`);
+  }
+  if (unstagedApproved.length) {
+    console.error('这些 plan 工作区已是 approved，但本次提交看不见（未暂存，HEAD 仍不是 approved）：');
+    for (const d of unstagedApproved) console.error(`- ${d}`);
+  }
+  console.error('把路径写进 plan，跑 confirm-doc.mjs 收到 approved，并让该 plan 进入本次提交（或已经在 HEAD 里是 approved）；');
+  console.error('产品 ≤5 文件且未命中 L2/L3 的小改可走 L0 极简道：消息体加一行非空 `L0: <判据>`（见 new-task.md §L0）。');
+  process.exit(1);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/templates/engine/.agents/hooks/check-delete-guard.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// 删除拦截门禁：Application/API 层新增 Remove/RemoveRange 调用点必须登记 allowlist 并配守卫用例。
+// 背景：2026-09-11 评审发现 6 处删除拦截存量缺口（incident 2026-09-11-masterdata-delete-interception-gaps），
+// 根因门禁缺位——本脚本做「新增删除路径须显式登记」的触发式审查；守卫正确性由防复发用例保证。
+// 用法：check-delete-guard.mjs [--update]
+// 自 check-delete-guard.sh 移植 node（2026-10-08 门禁去 sh 化第二批）——语义逐条对齐：
+// 按文件聚合计数（行号漂移不误报）、排除 _cache.Remove(、posix 相对路径、字典序对齐 sh sort。
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const SCRIPT_DIR = path.dirname(process.argv[1]);
+const ROOT = path.resolve(SCRIPT_DIR, '..', '..');
+const ALLOWLIST = path.join(ROOT, '.agents', 'hooks', 'delete-guard-allowlist.txt');
+const SCAN_DIRS = [
+  path.join(ROOT, 'backend', 'material', 'Shipyard.Material.Application'),
+  path.join(ROOT, 'backend', 'material', 'Shipyard.Material.API'),
+];
+
+const counts = new Map();
+for (const dir of SCAN_DIRS) {
+  if (!fs.existsSync(dir)) continue;
+  const base = path.basename(dir);
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith('.cs')) {
+        let n = 0;
+        for (const line of fs.readFileSync(p, 'utf8').split(/\r?\n/)) {
+          if (/\.(Remove|RemoveRange)\(/.test(line) && !/_cache\.Remove\(/.test(line)) n++;
+        }
+        if (n > 0) counts.set(`${base}/${path.relative(dir, p).replace(/\\/g, '/')}`, n);
+      }
+    }
+  };
+  walk(dir);
+}
+const current = [...counts.entries()].map(([f, n]) => `${f} ${n}`).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+if (process.argv[2] === '--update') {
+  fs.writeFileSync(ALLOWLIST, current.join('\n') + '\n');
+  console.log(`删除拦截 allowlist 已更新：${ALLOWLIST}`);
+  process.exit(0);
+}
+
+if (!fs.existsSync(ALLOWLIST)) {
+  console.error(`❌ 删除拦截门禁：缺少 ${ALLOWLIST}（首次请跑 check-delete-guard.mjs --update 生成并人工核对全部调用点已配守卫）`);
+  process.exit(1);
+}
+
+const listed = fs.readFileSync(ALLOWLIST, 'utf8').replace(/\r/g, '').split('\n').filter((l) => l.trim() !== '');
+const same = current.length === listed.length && current.every((l, i) => l === listed[i]);
+if (same) {
+  console.log('删除拦截门禁通过：Remove/RemoveRange 调用点与登记一致');
+  process.exit(0);
+}
+console.error('❌ 删除拦截门禁：Remove/RemoveRange 调用点与 .agents/hooks/delete-guard-allowlist.txt 不一致');
+console.error('—— 新增删除路径必须：1) 删前查引用，被引用抛中文 InvalidOperationException（统一 400）');
+console.error('   2) 配防复发用例（删除被引用 → 断言异常） 3) 确认无误后跑 check-delete-guard.mjs --update 更新登记');
+for (const l of current) if (!listed.includes(l)) console.error(`< ${l}`);
+for (const l of listed) if (!current.includes(l)) console.error(`> ${l}`);
+process.exit(1);

package/templates/engine/.agents/hooks/check-notify-guard.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// check-notify-guard: 前端提示守卫门禁（intent 2026-09-19-auth-expiry-explicit-guard）
+// 红线：frontend/src 下禁止直接调用 antd 的 message.error / warning / warn / info——
+//       认证失效跳转期间这些提示必须能被静默，页面层发坏消息一律经 utils/notify.ts 的 notify.*。
+//       message.success / loading / open 不在守卫范围（正常提示），不拦。
+// 扫描面：全仓 frontend/src（非仅暂存区新增行，与 check-audit-fields 的渐进收口不同）——
+//         存量调用点已于 2026-09-19 一次性清零，故可直接全量扫描：既拦新增调用点，也暴露迁移遗漏。
+// 豁免：frontend/src/utils/notify.ts（守卫自身的实现，只有它允许直接调 message.error/warning/info）
+// 约定：违例输出到 stderr 并 exit 1；参数错误 exit 2；干净无输出 exit 0（对齐 check-architecture）
+// 自 check-notify-guard.sh 移植 node（2026-10-08 门禁去 sh 化第二批）——语义逐条对齐。
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+
+if (process.argv.length > 2) {
+  console.error(`用法: ${path.basename(process.argv[1])}（无参数；扫描面为全仓 frontend/src，不区分暂存区）`);
+  process.exit(2);
+}
+const gitRoot = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (gitRoot.error || gitRoot.status !== 0) {
+  console.error('check-notify-guard: 不在 git 仓库内,门禁 fail-closed,不静默放行');
+  process.exit(1);
+}
+process.chdir(gitRoot.stdout.trim());
+if (!fs.existsSync('frontend/src')) process.exit(0);
+
+const HIT = /message\.(error|warning|warn|info)\s*\(/;
+const hits = [];
+const walk = (dir) => {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (/\.(vue|ts)$/.test(e.name)) hits.push(p);
+  }
+};
+walk('frontend/src');
+
+const viol = [];
+for (const f of hits) {
+  const rel = f.replace(/\\/g, '/');
+  if (rel === 'frontend/src/utils/notify.ts') continue; // 守卫自身实现豁免
+  const lines = fs.readFileSync(f, 'utf8').split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    if (!HIT.test(lines[i])) continue;
+    if (/^\s*(\/\/|\*|\/\*)/.test(lines[i])) continue; // 注释行不算违例
+    viol.push(`${rel}:${i + 1}:${lines[i]}`);
+  }
+}
+if (viol.length > 0) {
+  console.error('提示守卫违例：frontend/src 下直接调用 message.error/warning/info（应改经 notify.*，见 utils/notify.ts）：');
+  console.error(viol.join('\n'));
+  process.exit(1);
+}
+process.exit(0);

package/templates/engine/.agents/hooks/commit-check.cjs

@@ -0,0 +1,208 @@
+// commit-check: git commit 前置验证（本仓自有维护——decouple-flow-kit 起，原 agentic-flow-kit 通用版）
+// 1) 条件构建验证（按 .agents/hooks/commit-check.config.json 的 builds 配置；--full 不做 ext/prefix 裁剪，仍尊重 when）
+// 2) 质量检测（config.checks：lint / 类型检查 / vet 等秒级确定性检查；--full 不做 ext/prefix 裁剪，仍尊重 when）
+// （敏感信息扫描段已退役——2026-10-21 owner 指令「密钥本地不扫」：本地双腿（本段正则 + pre-commit gitleaks
+//   protect 门）同批撤除，误报 papercut ×4 消债；执法收敛 verify 安全段 secrets-scan 关单/CI）
+// 旗标（2026-10-15 构建门后移 pre-push）：
+//   --no-build：跳过段 1 条件构建——pre-commit 常规提交用（提交内环提速）；构建在 pre-push 按推送范围
+//               执法，合并提交仍走 --full 全量构建（合并结果是没人验证过的新状态）。
+//   --range <old> <new>：推送范围模式（pre-push 用）——文件面取 git diff --name-only old new；
+//               old 为全零 sha（新分支首推）= 全量匹配语义（等价 --full 的构建面）。默认（无旗标）暂存区模式行为不变。
+// config（.agents/hooks/commit-check.config.json）为本仓自有件（engine 面豁免三件套）；缺失或无 builds/checks 时跳过对应段。
+// 配置示例（.agents/hooks/commit-check.config.json）：
+//   {
+//     "builds": [
+//       { "name": "backend",  "command": "dotnet build", "ext": [".cs", ".sln", ".csproj"] },
+//       { "name": "frontend", "command": "npm run build", "ext": [".ts", ".tsx", ".vue", ".js", ".jsx"],
+//         "cwd": "frontend",
+//         "lockPattern": "MSB3026|MSB3027",                        // 可选：命中时按 lockHint 提示（文件锁类「与代码无关」失败）
+//         "lockHint": "构建被文件锁拦下——本地运行中的进程正占用产物，停进程后重试" },
+//       { "name": "docs-site", "command": "npm run build", "prefix": "docs/", "cwd": "docs" }   // prefix 可选：路径前缀触发
+//     ],
+//     "checks": [
+//       { "name": "typecheck", "command": "npx tsc --noEmit", "ext": [".ts", ".tsx"], "when": ["tsconfig.json"] },
+//       { "name": "lint",      "command": "npx eslint .", "ext": [".ts", ".js"], "when": ["eslint.config.js", ".eslintrc.json"] }
+//     ]
+//   }
+// builds/checks 触发判定（对暂存文件；builds 不计 .agents/ 与 .githooks/ 自身变更，checks 不计 .githooks/——引擎脚本变更照跑秒级检查）：`ext 任一匹配 OR prefix 前缀命中`。
+//   - 只有 ext：按扩展名全局触发（跨目录，适合语言型触发——仓库里该扩展名基本只属于该构建）；
+//   - 只有 prefix：该前缀下任何文件触发（目录型触发——如 monorepo 子包，仓库其他位置的相同扩展名不触发）；
+//   - 两者同配为 OR 并集而非 AND 交集——要「前缀内的特定扩展名」请只配 prefix（目录内文档变更多跑一次构建，方向安全）。
+// when（builds 与 checks 共用）：数组任一满足才启用，无 when 字段 = 无条件启用。
+//   - 路径或尾部 * 一层通配（如 "*.sln"）：相对仓库根做存在性判断；
+//   - pkg:<点分路径>（如 pkg:scripts.build）：读该项 cwd（缺省仓库根）的 package.json，
+//     沿路径取值，非空字符串才算满足。
+//   没有对应配置的项目自动跳过并提示，不 fail-closed 误拦。--full 同样尊重 when。
+// 条件构建执行器（2026-10-07 L31：execSync → spawnSync + 显式 timeout）
+// 症状：托管 Node 22 下 execSync('cd frontend && npm run build') **永不返回**——
+//   vite 8 / rolldown 在 Windows 泄漏 stdout 管道句柄，构建产物实际已写完，但父进程
+//   的读端等不到 EOF → pre-commit 永久挂起，任何含 frontend/ 的提交都卡死
+//   （实测换系统 Node 24 后同一命令 12.6s 正常返回）。
+// 修法：spawnSync 传 timeout，到点判失败而非无限等；spawnSync.error 的 ETIMEDOUT
+//   即超时信号。stdio 沿用 'pipe'（须收 stdout 供失败时打错误行），但 spawnSync 的
+//   pipe 不依赖子进程主动关闭——父进程按固定长度读，泄漏句柄不再导致挂死。
+// 契约不变：返回 { ok, out }，调用方（128/155 行）按字符串消费 out。
+const { execSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// 构建类命令的墙钟上限（毫秒）。npm run build 实测 12.6s / dotnet build 数十秒，
+// 取 10 分钟兼顾慢机与「本该 90 秒内结束」的挂起场景——远小于原来的永不返回。
+const BUILD_TIMEOUT_MS = 10 * 60 * 1000;
+
+process.chdir(path.resolve(__dirname, '../..'));
+
+function sh(cmd, cwd) {
+  try {
+    const r = spawnSync(cmd, {
+      shell: true,                       // 命令串含 && 与路径空格，沿用原 shell 语义
+      encoding: 'utf8',
+      cwd: cwd || undefined,
+      timeout: BUILD_TIMEOUT_MS,         // 到点 kill，判失败（不再无限等待）
+      stdio: ['ignore', 'pipe', 'pipe'],
+      maxBuffer: 32 * 1024 * 1024,
+    });
+    if (r.error) {
+      const timedOut = r.error.code === 'ETIMEDOUT';
+      return {
+        ok: false,
+        out: (timedOut ? `[超时] 命令超过 ${BUILD_TIMEOUT_MS / 1000}s 未结束，已终止（kill 直接子进程，孙进程可能残留）：${cmd}\n` : `[spawn 失败] ${r.error.code || r.error.message}\n`)
+          + String((r.stdout || '') + (r.stderr || '')),
+      };
+    }
+    if (r.status !== 0) {
+      return { ok: false, out: String((r.stdout || '') + (r.stderr || '')) };
+    }
+    return { ok: true, out: String(r.stdout || '') };
+  } catch (e) {
+    return { ok: false, out: String(e.stdout || '') + String(e.stderr || '') + String(e.message || '') };
+  }
+}
+
+// --- 模式旗标（2026-10-15 构建门后移 pre-push；sha 经 git 管道来仍做白名单校验——信任边界） ---
+const NO_BUILD = process.argv.includes('--no-build');
+const rangeIdx = process.argv.indexOf('--range');
+const RANGE = rangeIdx >= 0 ? process.argv.slice(rangeIdx + 1, rangeIdx + 3) : null;
+if (RANGE && (RANGE.length < 2 || !/^[0-9a-f]{4,40}$/i.test(RANGE[0]) || !/^[0-9a-f]{4,40}$/i.test(RANGE[1]))) {
+  console.log(`BLOCK: --range 参数须为两个 git sha（现「${(RANGE || []).join(' ')}」）`);
+  process.exit(1);
+}
+// 全零 old = 新分支首推：git diff 对全零 sha 无从执行，且本就取全量匹配语义——文件面置空即可
+const RANGE_ZERO_OLD = RANGE !== null && /^0+$/.test(RANGE[0]);
+
+let staged = [];
+try {
+  // 2026-11-06（P1-4 同族）：变更面读取统一带 `-c core.quotepath=off`——默认 quotepath=true 下
+  // 非 ASCII 路径被转义（`"frontend/\346\226..."`），下游按路径前缀匹配的门会静默漏判。
+  // （当前 frontend/ 下无中文路径，影响面暂为 0；口径与 pre-commit/pre-push/test-impact-lib 对齐。）
+  const listCmd = !RANGE ? 'git -c core.quotepath=off diff --cached --name-only'
+    : RANGE_ZERO_OLD ? null
+    : `git -c core.quotepath=off diff --name-only ${RANGE[0]} ${RANGE[1]}`;
+  staged = listCmd === null ? []
+    : execSync(listCmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+      .split('\n').map(s => s.trim()).filter(Boolean);
+} catch (e) {
+  console.log('BLOCK: 无法读取变更文件面（git diff 失败）');
+  process.exit(1);
+}
+
+// --- 0) 项目配置（可选） ---
+let config = { builds: [] };
+try {
+  const raw = JSON.parse(fs.readFileSync('.agents/hooks/commit-check.config.json', 'utf8'));
+  config = { ...config, ...raw };
+} catch (e) { /* 无配置 = 跳过构建验证 */ }
+
+// --- 1) 条件构建验证 ---
+// --full：合并提交（pre-merge-commit / 冲突解决后手动 commit）使用——合并结果是没人验证过的新状态，
+// 按 ext/prefix 裁剪可能漏掉需要重跑的一侧，故不做路径裁剪。when 仍生效：没有对应能力就不跑。
+// --range 全零 old sha（新分支首推）同取全量匹配语义。
+// 引擎自身文件（.agents/、.githooks/）不参与构建匹配——工作流引擎不是项目构建产物。
+const FULL = process.argv.includes('--full') || RANGE_ZERO_OLD;
+const stagedForBuild = staged.filter(f => !f.startsWith('.agents/') && !f.startsWith('.githooks/'));
+// 质量检测面（2026-11-10 dev-tour 测试门接线）：checks 是秒级确定性检查，引擎脚本（.agents/）变更同样要过；
+// builds 面维持排除引擎（工作流引擎不是项目构建产物），.githooks/ 对两者都不计。
+const stagedForChecks = staged.filter(f => !f.startsWith('.githooks/'));
+
+// whenSatisfied：任一谓词满足即启用。pkg: 读 cwd 下的 package.json；其余谓词相对仓库根。
+function whenItem(w, cwd) {
+  if (typeof w === 'string' && w.startsWith('pkg:')) {
+    const keys = w.slice(4).split('.').filter(Boolean);
+    if (!keys.length) return false;
+    const pkgPath = path.join(cwd || '.', 'package.json');
+    let pkg;
+    try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch (e) { return false; }
+    let cur = pkg;
+    for (const k of keys) {
+      if (cur == null || typeof cur !== 'object' || !Object.prototype.hasOwnProperty.call(cur, k)) return false;
+      cur = cur[k];
+    }
+    return typeof cur === 'string' && cur.trim() !== '';
+  }
+  const star = String(w).indexOf('*');
+  if (star < 0) return fs.existsSync(w);
+  const suffix = w.slice(star + 1);
+  const dir = path.dirname(w.slice(0, star)) || '.';
+  try { return fs.readdirSync(dir).some((f) => f.endsWith(suffix)); } catch (e) { return false; }
+}
+function whenSatisfied(when, cwd) {
+  if (!when) return true;
+  const list = Array.isArray(when) ? when : [when];
+  return list.some((w) => whenItem(w, cwd));
+}
+function skipWhen(kind, item) {
+  const shown = Array.isArray(item.when) ? item.when.join(' / ') : item.when;
+  console.log(`SKIP: ${item.name}（未找到 ${shown}，跳过${kind}——配置好后自动启用）`);
+}
+
+if (NO_BUILD) {
+  console.log('SKIP: --no-build（2026-10-15 构建门后移 pre-push——常规提交不再构建，推送时按范围执法）');
+} else {
+  let consideredBuild = false;
+  for (const b of (config.builds || [])) {
+    if (!b || !b.command) continue;
+    const exts = Array.isArray(b.ext) ? b.ext : [];
+    const match = FULL || stagedForBuild.some(f => exts.some(e => f.endsWith(e)) || (b.prefix ? f.startsWith(b.prefix) : false));
+    if (!match) continue;
+    consideredBuild = true;
+    if (!whenSatisfied(b.when, b.cwd)) { skipWhen('构建', b); continue; }
+    const r = sh(b.command, b.cwd);
+    if (!r.ok) {
+      if (b.lockPattern && new RegExp(b.lockPattern).test(r.out)) {
+        console.log(`BLOCK: ${b.name} 构建被文件锁拦下（与代码无关）。${b.lockHint || '停掉占用进程后原路重试'}\n` +
+          '锁冲突行：\n' + r.out.split(/\r?\n/).filter(l => new RegExp(b.lockPattern).test(l)).slice(0, 3).join('\n'));
+      } else {
+        console.log(`BLOCK: ${b.name} 构建失败（${b.command}）\n` + r.out.slice(0, 1500));
+      }
+      process.exit(1);
+    }
+    console.log(`OK: ${b.name} 构建通过（${b.command}）`);
+  }
+  if (!consideredBuild) {
+    console.log(config.builds && config.builds.length
+      ? 'SKIP: 无匹配的源码变更，跳过构建验证'
+      : 'SKIP: 未配置 builds（.agents/hooks/commit-check.config.json），跳过构建验证');
+  }
+}
+
+// --- 2) 质量检测（checks：lint / 类型检查 / vet 等秒级确定性检查；测试不放这里——关单在 stages.md Test 章阶段门） ---
+let ranCheck = false;
+for (const c of (config.checks || [])) {
+  if (!c || !c.command) continue;
+  const exts = Array.isArray(c.ext) ? c.ext : [];
+  const match = FULL || stagedForChecks.some(f => exts.some(e => f.endsWith(e)) || (c.prefix ? f.startsWith(c.prefix) : false));
+  if (!match) continue;
+  ranCheck = true;
+  if (!whenSatisfied(c.when, c.cwd)) { skipWhen('质量检查', c); continue; }
+  const r = sh(c.command, c.cwd);
+  if (!r.ok) {
+    console.log(`BLOCK: ${c.name} 质量检查未通过（${c.command}）\n` + r.out.slice(0, 1200));
+    process.exit(1);
+  }
+  console.log(`OK: ${c.name} 质量检查通过（${c.command}）`);
+}
+if (!ranCheck && config.checks && config.checks.length) {
+  console.log('SKIP: 无匹配的源码变更，跳过质量检测');
+}
+
+console.log('COMMIT_CHECK_OK');

package/templates/engine/.agents/hooks/gates.json

@@ -0,0 +1,33 @@
+{
+  "_comment": "PreToolUse 命令门禁清单（单源）。mirrorOf 指向项目安全下限；exempt 为刻意缺省项，须写明原因，防静默漂移。宿主壳（.trae/hooks.json / .zcode/config.json / .codebuddy/settings.json）只接线指向 .agents/hooks/pre-shell-check.cjs，不复制脚本（2026-10-29 owner 单源指示）。",
+  "mirrorOf": ".agents/settings.json#/permissions",
+  "exempt": [
+    {
+      "item": "dotnet ef",
+      "reason": "EF Migrations 禁令属 dotnet-ca 门禁域（提交时拦截）；此处重复会形成双源漂移"
+    },
+    {
+      "item": "git push --force",
+      "reason": "由 pre-shell-check.cjs 的 isForcePush() 做 token 化判定，覆盖面强于子串匹配（含 -f、+refspec、参数换序）"
+    },
+    {
+      "item": "git push -f",
+      "reason": "同上，并入 isForcePush() token 化判定"
+    },
+    {
+      "item": "commit 短旗标簇 / shell 展开（$、反引号）/ hooksPath 配置注入 / 一次性别名 / 大括号展开",
+      "reason": "由 pre-shell-check.cjs isNoVerify 与 1b 块代码层执法（2026-11-09 评审多轮收敛：扁平域/物化/闭集枚举，子串清单不可表达；长旗标已另列 deny 行作子串面镜像）"
+    }
+  ],
+  "deny": [
+    { "pat": "git reset --hard", "reason": "禁破坏性重置" },
+    { "pat": "drop database", "reason": "禁删库" },
+    { "pat": "--no-verify", "reason": "禁绕过 git 钩子（commit/merge/push 三处一律禁，AGENTS.md §2；与 isNoVerify 代码层互补：此行覆盖子串面兜底，代码层覆盖短旗标/展开/注入闭集）" }
+  ],
+  "ask": [
+    { "pat": "git checkout", "reason": "可能切换/丢弃工作区改动" },
+    { "pat": "git clean", "reason": "可能删除未跟踪文件" },
+    { "pat": "git branch -D", "reason": "可能删除未合并分支" },
+    { "pat": "rm -rf", "reason": "可能递归删除文件" }
+  ]
+}