agentic-flow-kit 1.8.7 → 2.1.0

package/templates/engine/.agents/config/steering.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "defaultTier": "standard",
+  "tiers": {
+    "frontier": {
+      "scaffolding": "goal",
+      "judgmentLatitude": "high",
+      "guidance": "给目标、约束、验收与红线；少给逐步指令。固定‘只记失败’这类规则可能削弱强模型，保留判断空间。"
+    },
+    "standard": {
+      "scaffolding": "mixed",
+      "judgmentLatitude": "medium",
+      "guidance": "保留确认门与检查清单；实现步骤可精简，关键判据必须显式。"
+    },
+    "lean": {
+      "scaffolding": "step",
+      "judgmentLatitude": "low",
+      "guidance": "给明确步骤、模板与反例；用门禁兜住判断缺口。"
+    }
+  },
+  "invariants": [
+    "确认门与不可逆操作红线",
+    "独立复核与职责分离",
+    "单源纪律（同一事实只写一处）",
+    "测试不可弱化",
+    "提交与推送门禁"
+  ]
+}

package/templates/engine/.agents/config/workflow-enums.txt

@@ -0,0 +1,25 @@
+# workflow 文档枚举单源（2026-09-25 enum-single-source）
+# 本文件会被 core.autocrlf 检出为 CRLF——读取方显式去 \r（node parseEnums），禁止依赖行尾格式（rule-budgets.txt 同约定）。
+# 消费方：check-loop.mjs / workflow-board-server.mjs / kb-search.mjs / gen-workflow-index.mjs /
+#         fill-{intent,plan,spec}.mjs（均经 scripts/workflow-enums.mjs 读取器）——改枚举改这里，别改消费方。
+# 格式：key=value value value（空格分隔；# 注释行忽略；键重复 / 值重复 / 缺键 = 消费方 fail-loud）
+# 语义：doc = intent/spec/plan 三件；incident = 事故件。
+#   all       全生命周期状态
+#   confirmed 已确认（check-loop「状态未确认」放行口径 = 看板枚举告警口径）
+#   active    活跃（INDEX 活跃层 / kb-search 活跃 ×1.3 排序）
+#   terminal  终态（看板「入口已 done 而 plan 未终态」告警口径）
+#   abandoned 放弃留档（L3 确认三件豁免口径）
+doc.status.all=draft approved done superseded cancelled
+doc.status.confirmed=approved done superseded cancelled
+doc.status.active=draft approved
+doc.status.terminal=done superseded cancelled
+doc.status.abandoned=superseded cancelled
+incident.status.all=open fixed closed
+incident.status.active=open
+# 归因枚举（2026-10-11 incident-attribution）：incident frontmatter 的「来源:」/「影响环境:」（原由检查 24 校验，检查 24 已于 2026-10-28 退役，现为人工纪律）。
+#   source = 谁发现（self=AI 自查 / user=用户报出 / test=测试或实测暴露 / monitor=监控告警）
+#   env    = 缺陷触达的环境（none=未触达任何运行环境，如仅静态检查发现）
+# 锚前存量不回填（policy attributionSince）；新 open 件必填。
+incident.source.all=self user test monitor
+incident.env.all=dev staging prod none
+level.all=L0 L1 L2 L3

package/templates/engine/.agents/evals/README.md

@@ -0,0 +1,49 @@
+# 行为评测（agent-eval）
+
+静态门回答“脚本是否还能跑”；行为评测回答“智能体的行为是否还一样”。
+
+适用改动面（`.agents/config/agent-eval.json` 的 `sensitive`）：
+
+- `.agents/skills/**`、`.agents/commands/**`、`.agents/roles/**`
+- 模型角色 / 严格度 / pipeline 配置
+
+## 跑一次
+
+1. 按 `.agents/skills/eval/SKILL.md` 准备任务集：5–10 条，有已知判据，正负例都有。
+2. 用新子代理跑两臂（A=新配置，B=旧配置），同模型、同上下文、盲评。
+3. 用 `eval-score.mjs` 算通过率，然后落凭证：
+
+```bash
+node .agents/scripts/agent-eval.mjs record --pass-rate 0.9 --tasks 8 --model opus --note "skill x v2"
+```
+
+4. 门禁检查：
+
+```bash
+node .agents/scripts/agent-eval.mjs check            # 严格：无凭证/过期/不达标 → 非零
+node .agents/scripts/agent-eval.mjs check --advisory # 试点：只告警
+```
+
+## 新装为什么严格 check 会失败
+
+新装项目没有任何评测凭证，`check` 报 `no-eval-for-tree` 是**门在工作**，不是安装坏了。
+此时只有两条路：
+
+1. 按上面的流程真跑一次评测并 `record`（推荐）；
+2. 试点期在 CI 里用 `--advisory`，严格 check 留到改敏感面时再跑。
+
+`record` 拒绝不可追溯的凭证：`--pass-rate` 必须是 0..1 的显式值，`--tasks` 不少于
+`minTasks`（默认 5），`--model` 不能为空。不要把 `record --pass-rate 1` 当“免测开关”。
+
+## 判据
+
+- 凭证绑定的是**评测敏感面的内容签名**，不是提交号：只改业务代码不会让凭证失效。
+- 凭证默认 30 天过期；模型升级、技能重写、命令改步骤都应重跑。
+- `results.jsonl` 是 append-only 台账；多机/多分支用 jsonl-union 合并。
+- 通过率写“A 臂命中率”；Δ 与翻转任务留在评测报告里，不进凭证。
+- `results.jsonl` 属于运行态：不随安装器模板出厂（`listFiles` 已排除），否则新项目会继承一张假凭证。
+
+## 放进 CI
+
+`templates/git/azure-pipelines.yml` 与 `templates/git/.github/workflows/ci.yml`
+在 `verify --full` 之后调用 `check --advisory`。稳定后去掉 `--advisory`。

package/templates/engine/.agents/evals/tasks.tsv

@@ -0,0 +1,6 @@
+task	expected
+skill-trigger-positive	相关任务能加载该技能并按其约束执行
+skill-trigger-negative	无关任务不加载该技能、不引入额外步骤
+command-step-order	按命令文件的确认门顺序执行，不跳过确认
+role-contract	角色只做契约内动作，越界即停
+model-quality	强模型档不因过度分步提示而降低判断质量

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