agentic-flow-kit 1.8.2 → 2.0.0

package/templates/engine/.agents/hooks/check-architecture.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// check-architecture: AGENTS.md 架构红线门禁
+// 红线：Application 禁引用 Infrastructure 项目 / 禁出现 DbContext；EF 模型层解耦（禁关系映射 / Include / 导航属性）；
+//       Controller 禁透传 InnerException。
+// 约定：违例输出到 stderr 并 exit 1；干净无输出 exit 0（stdout 保持为空，兼容 agent hook JSON 解析）
+// 自 check-architecture.sh 移植 node（2026-10-08 门禁去 sh 化第二批）——语义逐条对齐；
+// 红线 4.3 自 Python heredoc 改 node 原生实现：不再依赖 python 存在（sh 版缺 python 时 fail-closed 报警，node 版恒可跑）。
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+
+const gitRoot = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (gitRoot.error || gitRoot.status !== 0) {
+  console.error('check-architecture: 不在 git 仓库内,门禁 fail-closed,不静默放行');
+  process.exit(1);
+}
+process.chdir(gitRoot.stdout.trim());
+
+const requireTarget = (p) => {
+  if (!fs.existsSync(p)) {
+    console.error(`check-architecture: 门禁目标缺失（${p}）——fail-closed,不静默放行`);
+    process.exit(1);
+  }
+};
+
+const APP = 'backend/material/Shipyard.Material.Application';
+const API = 'backend/material/Shipyard.Material.API';
+requireTarget(APP);
+requireTarget(API);
+
+const readLines = (p) => fs.readFileSync(p, 'utf8').replace(/^\uFEFF/, '').split(/\r?\n/);
+// 目录递归收集（排除 /obj/ /bin/），posix 相对路径，与 sh 版 grep -rn 输出行格式 `path:line:content` 对齐
+const csFiles = (dir) => {
+  const out = [];
+  const walk = (d) => {
+    if (!fs.existsSync(d)) return;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) { if (!/[\\/]obj[\\/]|[\\/]bin[\\/]/.test(p)) walk(p); }
+      else if (e.name.endsWith('.cs')) out.push(p.replace(/\\/g, '/'));
+    }
+  };
+  walk(dir);
+  return out;
+};
+
+let violations = '';
+
+// 红线 1：Application csproj 不得引用 Infrastructure 项目
+for (const f of fs.readdirSync(APP).filter((f) => f.endsWith('.csproj')).map((f) => path.join(APP, f))) {
+  if (fs.readFileSync(f, 'utf8').includes('Infrastructure')) {
+    violations += '\n- csproj 引用了 Infrastructure 项目（Application 只允许依赖 Domain 与 shared）';
+    break;
+  }
+}
+
+// 红线 2：Application 代码不得出现 DbContext / Infrastructure 命名空间
+const appHits = csFiles(APP).flatMap((f) => readLines(f).map((c, i) => ({ f, i: i + 1, c })))
+  .filter(({ c }) => c.includes('MaterialDbContext') || c.includes('using Shipyard.Material.Infrastructure'))
+  .map(({ f, i, c }) => `${f}:${i}:${c}`);
+if (appHits.length > 0) {
+  violations += `\n- Application 代码出现 DbContext / Infrastructure 引用：\n${appHits.join('\n')}`;
+}
+
+// 红线 3：API 层 Controller 禁直接注入 MaterialDbContext（豁免：MaterialCodesController 分类树原生 LINQ）
+const apiHits = csFiles(API).flatMap((f) => readLines(f).map((c, i) => ({ f, i: i + 1, c })))
+  .filter(({ f, c }) => f.includes('MaterialCodesController') === false && c.includes('MaterialDbContext'))
+  .map(({ f, i, c }) => `${f}:${i}:${c}`);
+if (apiHits.length > 0) {
+  violations += `\n- API 层出现 DbContext 直接引用（应走 IRepository/IUnitOfWork，豁免仅 MaterialCodesController）：\n${apiHits.join('\n')}`;
+}
+
+// 红线 4：EF 模型层解耦（2026-09-14，intent 2026-09-14-remove-ef-relationships）
+const CTX = 'backend/material/Shipyard.Material.Infrastructure/Data/MaterialDbContext.cs';
+requireTarget(CTX);
+// 4.1 MaterialDbContext 禁关系映射配置
+const relHits = readLines(CTX).map((c, i) => ({ i: i + 1, c }))
+  .filter(({ c }) => /HasOne|HasMany|WithOne|WithMany|HasForeignKey|OnDelete/.test(c))
+  .map(({ i, c }) => `${i}:${c}`);
+if (relHits.length > 0) {
+  violations += `\n- MaterialDbContext 出现关系映射（模型层已解耦，关联一律显式 JOIN/分步查询）：\n${relHits.join('\n')}`;
+}
+// 4.2 Application / API 禁代码级 .Include(（注释里的「原 Include(...)」无前导点，不误报）
+const incHits = [...csFiles(APP), ...csFiles(API)].flatMap((f) => readLines(f).map((c, i) => ({ f, i: i + 1, c })))
+  .filter(({ c }) => /\.Include\(/.test(c))
+  .map(({ f, i, c }) => `${f}:${i}:${c}`);
+if (incHits.length > 0) {
+  violations += `\n- Application/API 出现 EF Include（导航已移除，明细/参照数据经仓储分步查询或显式 JOIN）：\n${incHits.join('\n')}`;
+}
+// 4.3 Domain 实体禁导航属性（按实体类名交叉扫描；枚举/标量属性不误伤）
+const ENT = 'backend/material/Shipyard.Material.Domain/Entities';
+requireTarget(ENT);
+const entFiles = csFiles(ENT);
+const names = new Set(['Staff', 'Company', 'BaseProject']);
+for (const f of entFiles) {
+  for (const m of readLines(f).join('\n').matchAll(/public\s+(?:sealed\s+|abstract\s+|partial\s+)*(?:class|record)\s+(\w+)/g)) names.add(m[1]);
+}
+const navHits = [];
+for (const f of entFiles) {
+  const lines = readLines(f);
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^\s*public\s+(?:virtual\s+)?([\w<>,\s.?]+?)\s+(\w+)\s*\{/.exec(lines[i]);
+    if (!m) continue;
+    const typ = m[1].trim();
+    const mm = /(?:ICollection|List|IEnumerable|IReadOnlyCollection|IReadOnlyList)<\s*(\w+)\s*>/.exec(typ);
+    const core = mm ? mm[1] : (/^\w+\??$/.test(typ) ? typ.replace(/\?$/, '') : null);
+    if (core && (names.has(core))) navHits.push(`${path.basename(f)}:${i + 1} ${m[2]} : ${typ}`);
+  }
+}
+if (navHits.length > 0) {
+  violations += `\n- Domain 实体出现导航属性（模型层已解耦，关联只保留外键标量列）：\n${navHits.join('\n')}`;
+}
+
+// 红线 5：Controller 禁把 InnerException 原文透传进响应体（2026-09-18，incident 2026-09-18-db-exception-message-unify）
+// 进日志不违例（MaterialCodesController 范式）：仅拦非日志行的 InnerException 引用
+const CTRL = 'backend/material/Shipyard.Material.API/Controllers';
+const innerHits = fs.existsSync(CTRL) ? csFiles(CTRL).flatMap((f) => readLines(f).map((c, i) => ({ f, i: i + 1, c })))
+  .filter(({ c }) => c.includes('InnerException') && !/Log(Warning|Error|Information|Debug|Trace)/.test(c))
+  .map(({ f, i, c }) => `${f}:${i}:${c}`) : [];
+if (innerHits.length > 0) {
+  violations += `\n- Controller 出现 InnerException 透传进响应（统一 ErrorHandling/DbErrorMessages 翻译；详情只许进日志）：\n${innerHits.join('\n')}`;
+}
+
+// 红线 6：订单域 Controller 并发冲突文案单源（2026-11-02，incident 2026-11-02-mto-pml-review-defects-batch2；
+// 复发自 2026-10-21-order-concurrency-message-unification）。范围 = 该事件已收口的订单域 7 个控制器；
+// 主数据域与库存域（Inbound/Transfer 的「库存已变动」）沿用各自既有口径，不在本红线执法面。
+const ORDER_CTRL_FILES = [
+  `${CTRL}/Orders/MTOOrdersController.cs`,
+  `${CTRL}/Orders/MTOChangesController.cs`,
+  `${CTRL}/Orders/OutboundOrdersController.cs`,
+  `${CTRL}/Orders/OutboundRequestsController.cs`,
+  `${CTRL}/Orders/PurchaseOrdersController.cs`,
+  `${CTRL}/Orders/PurchaseRequestsController.cs`,
+  `${CTRL}/Orders/PurchaseContractTemplatesController.cs`,
+  `${CTRL}/Orders/PurchaseContractDraftsController.cs`,
+  `${CTRL}/PML/PMLController.cs`,
+].filter((f) => fs.existsSync(f));
+const orderMsgHits = ORDER_CTRL_FILES.flatMap((f) => readLines(f).map((c, i) => ({ f, i: i + 1, c })))
+  .filter(({ c }) => c.includes('该数据已被其他用户修改，请刷新后再试'))
+  .map(({ f, i, c }) => `${f}:${i}:${c}`);
+if (orderMsgHits.length > 0) {
+  violations += `\n- 订单域 Controller 并发文案未走 ApiMessages.DataStateInvalid（2026-10-21 事件复发）：\n${orderMsgHits.join('\n')}`;
+}
+const orderCatchHits = ORDER_CTRL_FILES
+  // OutboundOrders 的确认/拣货 catch 是库存域文案（「库存已变动」），2026-10-21 已裁定保留
+  .filter((f) => !f.endsWith('OutboundOrdersController.cs'))
+  .flatMap((f) => {
+  const lines = readLines(f);
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].includes('catch (DbUpdateConcurrencyException)')) continue;
+    let end = i + 1;
+    while (end < lines.length && !lines[end].trim().startsWith('catch (')) end++;
+    const body = lines.slice(i + 1, end).join('\n');
+    if (!body.includes('ApiMessages.DataStateInvalid')) hits.push(`${f}:${i + 1}:${lines[i].trim()}`);
+  }
+  return hits;
+});
+if (orderCatchHits.length > 0) {
+  violations += `\n- 订单域并发 catch 未使用 ApiMessages.DataStateInvalid：\n${orderCatchHits.join('\n')}`;
+}
+
+if (violations !== '') {
+  console.error(`架构红线违例（AGENTS.md）：\n${violations}\n`);
+  process.exit(1);
+}
+process.exit(0);

package/templates/engine/.agents/hooks/check-audit-fields.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// check-audit-fields: AGENTS.md 审计字段红线门禁（P0 机器兜底，本地暂存区 + CI range）
+// 红线：审计字段（Operator/OperatorJobNo/OperateTime）由 EFRepository<T> 统一写入；
+//       创建审计（CreatedBy/CreatedByJobNo/CreatedTime）由 CreationAuditExtensions.ApplyCreationAudit 统一写入（2026-11-02 B2），
+//       禁止在 Controller/Service 手工补写（见 backend/AGENTS.md「本目录适用的机器门」）
+// 模式：默认扫【暂存区新增行】；可用 `--range <git-range>` 扫范围内新增行——存量违例不拦（渐进收口）
+// 豁免：Infrastructure/Data/EFRepository.cs（统一审计写入）、Data/DbSeeder.cs（种子初始化无 HTTP 上下文，显式 "system" 属「显式值优先」合法用法）、tests/（测试种子需固定审计时间值测边界语义，直填实体不经 EFRepository 审计路径）
+// 约定：违例输出到 stderr 并 exit 1；参数错误 exit 2；干净无输出 exit 0（对齐 check-architecture，兼容 agent hook JSON 解析）
+// 自 check-audit-fields.sh 移植 node（2026-10-08 门禁去 sh 化第二批）——语义逐条对齐。
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+
+const usage = () => console.error(`用法: ${process.argv[1].split(/[\\/]/).pop()} [--range <git-range>]`);
+const args = process.argv.slice(2);
+let gitRange = '';
+if (args.length === 2) {
+  if (args[0] !== '--range' || args[1] === '' || args[1].startsWith('-')) { usage(); process.exit(2); }
+  gitRange = args[1];
+} else if (args.length !== 0) { usage(); process.exit(2); }
+
+const git = (a) => {
+  const r = spawnSync('git', a, { encoding: 'utf8' });
+  return { ok: !r.error && r.status === 0, out: r.stdout || '' };
+};
+const root = git(['rev-parse', '--show-toplevel']);
+if (!root.ok) { console.error('check-audit-fields: 不在 git 仓库内,门禁 fail-closed,不静默放行'); process.exit(1); }
+process.chdir(root.out.trim());
+
+const names = gitRange === '' ? git(['diff', '--cached', '--name-only', '--', '*.cs']) : git(['diff', '--name-only', gitRange, '--', '*.cs']);
+if (!names.ok) { console.error(`无效 git range: ${gitRange}`); usage(); process.exit(2); }
+if (names.out.trim() === '') process.exit(0);
+
+// 左值判定：审计字段被赋值（Operator 后跟 `=` 或 `??=`；OperatorName 等标识符、`==` 比较、`{ get; set; }` 声明天然不匹配）
+const auditRe = /(Operator|OperatorJobNo|OperateTime|CreatedBy|CreatedByJobNo|CreatedTime)\s*(\?\?=|=[^=])/;
+// 右值豁免：同名属性拷贝（手写 DTO 映射 `Operator = x.Operator` 是读不是补写审计）
+const copyRe = /(^|[^?])=\s*[A-Za-z0-9_.]*\.(Operator|OperatorJobNo|OperateTime|CreatedBy|CreatedByJobNo|CreatedTime)\s*([;,})]|$)/;
+
+const patch = gitRange === '' ? git(['diff', '--cached', '-U0', '--', '*.cs']) : git(['diff', '-U0', gitRange, '--', '*.cs']);
+const hits = [];
+let file = '';
+for (const line of patch.out.split('\n')) {
+  if (line.startsWith('+++ b/')) { file = line.slice(6); continue; }
+  if (!/^\+[^+]/.test(line)) continue;
+  const content = line.slice(1);
+  if (!auditRe.test(content) || copyRe.test(content)) continue;
+  if (/\/EFRepository\.cs:/.test(`${file}:${content}`) || /\/CreationAuditExtensions\.cs:/.test(`${file}:${content}`) || /\/DbSeeder\.cs:/.test(`${file}:${content}`) || /tests\//.test(file) || /Migrations\//.test(file)) continue;
+  // ICreationAudit 显式实现桥接（实体 CreatedTime 非空列 → 接口可空）：setter 是单源写入器，不是手工补写
+  if (/set => CreatedTime = value/.test(content)) continue;
+  hits.push(`${file}:${content}`);
+}
+if (hits.length > 0) {
+  console.error('审计字段红线违例（AGENTS.md）：目标 diff 新增行手工补写 Operator*/CreatedBy*，应由 EFRepository / ApplyCreationAudit 统一写入：');
+  console.error(hits.join('\n'));
+  process.exit(1);
+}
+process.exit(0);

package/templates/engine/.agents/hooks/check-commit-plan-ref.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// check-commit-plan-ref.mjs — 提交消息任务短名校验（2026-11-09 建，advisory 先行不阻断）
+// 用途：暂存产品路径被恰好一份覆盖 plan 收口时，提交消息任意位置须含该 plan 短名（文件名去 .md）——
+//   让 `git log` 可按任务短名检索，消息 ↔ plan 可追溯。多 plan 覆盖时至少含其一。
+// 语义与红线：只读裁决；**advisory 期 exit 恒 0**（警告打印不阻断），观察期后再议升硬门。
+//   skip 情形：合并/squash/rebase/cherry-pick（isMergeLike）、未暂存产品路径、消息含 L0 trailer
+//   （豁免 A 同判据复用）、覆盖 plan 为零（顺序门已执法，这里不重判）。
+//   判据全部复用 check-confirm-order.mjs 导出（collectStagedCoverage / coveringDocs / l0Judgement /
+//   isMergeLike），短名边界匹配模板单源 .agents/config/commit-msg-rules.json planSlugRe。
+// 用法：node .agents/hooks/check-commit-plan-ref.mjs <msgFile>（由 .githooks/commit-msg 调用）
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { collectStagedCoverage, coveringDocs, l0Judgement, isMergeLike } from './check-confirm-order.mjs';
+
+const RULES = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'config', 'commit-msg-rules.json');
+const msgFile = process.argv[2];
+
+const warn = (lines) => {
+  console.error('commit-msg ⚠（advisory）任务短名：');
+  for (const l of lines) console.error(`  ${l}`);
+};
+
+if (isMergeLike()) {
+  console.log('SKIP: 任务短名校验——合并/squash/rebase/cherry-pick');
+  process.exit(0);
+}
+if (l0Judgement(msgFile)) {
+  console.log('SKIP: 任务短名校验——L0 极简道（消息含 L0 trailer）');
+  process.exit(0);
+}
+
+const cov = collectStagedCoverage();
+if (cov.error) {
+  warn(['暂存列表读不到，本次无法校验（advisory 期不阻断）']);
+  process.exit(0);
+}
+if (!cov.products.length) {
+  console.log('SKIP: 任务短名校验——未暂存产品路径');
+  process.exit(0);
+}
+
+const covers = coveringDocs(cov.docs, cov.stagedAdded)
+  .filter((d) => cov.products.some((p) => d.text.includes(p)));
+if (!covers.length) {
+  console.log('SKIP: 任务短名校验——无覆盖 plan（顺序门已执法，此处不重判）');
+  process.exit(0);
+}
+
+let msg = '';
+try { msg = fs.readFileSync(msgFile, 'utf8'); } catch { /* 读不到按空消息走 advisory */ }
+
+let boundaryTpl = '(^|[^A-Za-z0-9-])<slug>($|[^A-Za-z0-9-])';
+try {
+  const rules = JSON.parse(fs.readFileSync(RULES, 'utf8'));
+  if (rules.planSlugRe) boundaryTpl = rules.planSlugRe;
+} catch { /* 模板读不到用内联默认（advisory 期不 fail-closed） */ }
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const hitRe = (slug) => new RegExp(boundaryTpl.replace(/<slug>/g, esc(slug)));
+
+const slugs = [...new Set(covers.map((d) => path.basename(d.rel, '.md')))];
+const hits = slugs.filter((s) => hitRe(s).test(msg));
+
+if (slugs.length === 1) {
+  if (!hits.length) {
+    warn([
+      `本次提交由 plan「${slugs[0]}」覆盖，但提交消息未含任务短名。`,
+      `建议写法：feat(${slugs[0]}): <摘要>  或正文任意位置提及 ${slugs[0]}。`,
+      '（advisory 期不阻断；观察期后拟升硬门——git log 须可按任务短名检索）',
+    ]);
+  } else {
+    console.log(`任务短名校验：消息已含「${slugs[0]}」✅`);
+  }
+} else if (!hits.length) {
+  warn([
+    `本次提交被 ${slugs.length} 份 plan 覆盖，提交消息须至少含其一短名：`,
+    ...slugs.map((s) => `- ${s}`),
+    '（advisory 期不阻断）',
+  ]);
+} else {
+  const missed = slugs.filter((s) => !hits.includes(s));
+  console.log(`任务短名校验：消息已含 ${hits.map((s) => `「${s}」`).join('')}✅${missed.length ? `（未提及：${missed.join('、')}——多 plan 合提建议拆分或补提）` : ''}`);
+}
+process.exit(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);