agentic-flow-kit 1.8.7 → 2.0.0

package/templates/engine/.agents/scripts/check-loop-sections/s29-regr-enforcer.mjs

@@ -0,0 +1,69 @@
+// check-loop-sections/s29-regr-enforcer.mjs — 29. 回归清单执法者配对 [hard-block]（2026-11-11；锚 regrEnforcerSince）
+// 背景（2026-11-10 审计 P1）：回归清单「执法者」列 168 条空置长期无告警——规则已写但没有任何东西执法 =
+//   重犯信号（清单规则 7 的人工纪律没有机器面）。2026-11-11 owner 拍板决策二：机器执法补位（当日已人工
+//   清零 + 170 条显式 [prompt-only] 挂债 papercuts；本段让锚后新增行从此有门）。
+// 判据：主台账「## 防复发验证」节 + 全部分片 workflow/regression-checklist.d/<YYYY-MM>.md 的数据行
+//   （双 | 包边、非表头非分隔行；首列剥反引号后以 \d{4}- 开头——主台账 2026-11-10 两行系反引号
+//   incident-slug 形态，同认）。行日期 = 首列前 10 字符；< regrEnforcerSince → 跳过（存量不追溯，
+//   同 convergenceSince 惯例）。锚后行：第 4 列（执法者）非空且非 —/- → 通过；为空或行被切成非 4 列
+//   → HARD-BLOCK（填真执法资产：测试类/脚本/门禁 §N/regression-smoke/verify-ui 证据路径，或显式
+//   [prompt-only] 并登记 papercuts 挂债）。表头行/分隔行/非数据行跳过；主台账无该节不报错。
+// 分工：check-regression-consistency.mjs 查清单引用的资产存在性（关单时触发）；本段查执法者配对
+//   （每次 check-loop 扫描触发）——两门互补，互不替代。
+import {
+  fs, os, path, spawnSync, createHash, createRequire, fileURLToPath,
+  loadEnums, auditEnabled, loadKitPolicy, hasFreshVerifyLine, laneOfDoc, MARK_RE,
+  SCRIPT_DIR, GIT, REV_ARG, REV, ROOT, MAIN_ROOT, ENUMS, inSet, stOkDoc,
+  spawnGit, gitOut, linesOf, fmGet, WF, DOC_DIRS, blockers, warnings, kitPolicy, isTracked, docFiles,
+  addedDateOf, warnEvidenceExempt, VERIFY_GREEN_RE, verifyEvidenceTruth,
+  versionGreater, fmStatus, bindingSha256, readdirOrNull, isDirectoryOrNull,
+} from '../check-loop-kit.mjs';
+
+export function run() {
+// --- 29. 回归清单执法者配对 [hard-block]（2026-11-11；锚 regrEnforcerSince）---
+{
+  const anchor = kitPolicy.regrEnforcerSince;
+  if (anchor) {
+    // 行切分沿用 s23 / agg-delegations splitTables 口径：双 | 包边、slice(1,-1)、逐格 trim
+    const cellsOf = (l) => l.split('|').slice(1, -1).map((c) => c.trim());
+    const isSep = (l) => /^\s*\|[\s:|-]+\|\s*$/.test(l);
+    // 数据行 = 双 | 包边表行、非分隔行、首列（剥反引号）以 \d{4}- 开头；日期 = 首列前 10 字符
+    const isDataRow = (l) => {
+      if (!/^\s*\|.*\|\s*$/.test(l) || isSep(l)) return false;
+      const first = (cellsOf(l)[0] || '').replace(/^`+|`+$/g, '').trim();
+      return /^\d{4}-/.test(first);
+    };
+    const dateOf = (cells) => (cells[0] || '').replace(/^`+|`+$/g, '').trim().slice(0, 10);
+    // 扫描面：主台账「防复发验证」节（## 级开节，### 子节不停）+ 全部分片整文件
+    const targets = [];
+    const secLines = [];
+    let inSec = false;
+    for (const l of linesOf(path.join(ROOT, WF, 'regression-checklist.md')) || []) {
+      if (/^##\s+.*防复发验证/.test(l)) { inSec = true; continue; }
+      if (inSec && /^##\s+/.test(l)) { inSec = false; continue; }
+      if (inSec) secLines.push(l);
+    }
+    targets.push({ base: 'regression-checklist.md', lines: secLines });
+    const shardDir = path.join(ROOT, WF, 'regression-checklist.d');
+    for (const f of (readdirOrNull(shardDir) || []).filter((n) => n.endsWith('.md')).sort()) {
+      targets.push({ base: f, lines: linesOf(path.join(shardDir, f)) || [] });
+    }
+    for (const t of targets) {
+      const missed = [];
+      for (const l of t.lines) {
+        if (!isDataRow(l)) continue; // 表头行/分隔行/非数据行跳过
+        const cells = cellsOf(l);
+        const d = dateOf(cells);
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(d) || d < anchor) continue; // 不可判定或锚前存量不追溯
+        const enforcer = cells.length === 4 ? cells[3] : '';
+        if (enforcer && enforcer !== '—' && enforcer !== '-') continue; // [prompt-only] 合法显式声明
+        const topic = (cells[1] || cells[0] || l).replace(/\s+/g, ' ').trim().slice(0, 40);
+        missed.push(`${d}「${topic}」${cells.length === 4 ? '执法者列为空' : `行被切成 ${cells.length} 列（表头口径 4 列）`}`);
+      }
+      if (missed.length) {
+        blockers.push(`- [回归执法者缺失] ${t.base} ${missed.length} 行执法者未配对（${missed.join('; ')}）——回归清单锚（${anchor}）后行须指认「复发时谁会红」：填真执法资产（测试类 / 脚本 / 门禁 §N / regression-smoke / verify-ui 证据路径）或显式 \`[prompt-only]\` 并登记 papercuts 挂债（检查 29；锚前存量不追溯）`);
+      }
+    }
+  }
+}
+}

package/templates/engine/.agents/scripts/check-loop.mjs

@@ -0,0 +1,131 @@
+// 用法:node .agents/scripts/check-loop.mjs [--rev <sha>] [--all | --hygiene]
+// 默认（现状，2026-11-11 起）：只跑 hard 6 段 = §1 §3x §8 §15 §23 §29（全部有阻断力）；
+// §14 §17 §25 等历史段已退役或下沉（编号留疤不重排），演化史见下方日期注记。
+// 2026-10-21 门禁极小化第 1 批：§17 退役删除；§1 配对/L3 三件、§3 配对/回路、§14 留痕降 WARN——
+//   段仍在 hard 车道默认跑，但只报告不阻断（红线判低/L3 状态例外，保 hard 阻断）；hard 阻断面 =
+//   红线判低(§1) + L3 状态(§1) + 回归证据(§3x) + 验收勾验(§8) + 确认指纹(§15) + 收敛对账(§23)。
+// 2026-10-22 门禁收敛批 1：§3 三件套、§14 留痕、§25 路由预判三段由 hard 车道下沉 hygiene——
+//   实测三段 blockers.push 均为 0（427 次 hard 运行产出 419 次 WARN、0 次阻断），占着默认关单/
+//   pre-push 车道却从不拦任何东西；承载力已前移到动作时刻（§3 → closeout skill §0 第 2 项；
+//   §14 → confirm-doc/stage-gates 落态前置门），下沉不丢校验，只改何时跑。
+//   hard 车道现存 5 段 = §1 §3x §8 §15 §23（全部有阻断力）。
+// 2026-10-22 门禁收敛批 4：§20 已退役（挂载条件为包源环境，本仓恒不触发）。编号留疤不重排。
+// 2026-10-28 引擎测试面退役：§28 脚本覆盖对账随 `.agents/**/*.test.mjs` 与 run-tests 一并删除
+//   （owner 决策：不再跑引擎面全量测试）。编号留疤不重排。
+// 2026-10-28 引擎减重第一刀：hygiene 16 段（§2 §3 §4 §5 §9 §10 §14 §16 §18 §19 §21 §22 §24 §25
+//   §26 §27）全部退役——实测一周 845 次运行 8028 条 WARN、0 条阻断；段体删除，编号留疤。
+//   --hygiene / --all 从此等价，均只跑 hard 5 段。
+// 2026-10-22 门禁收敛批 3：judgment-ledger 规则名归一（剥 WARN/NOTE 严重度前缀）——同一逻辑规则
+//   因前缀写法不同被拆成两条 rule，污染 per-rule 计数与「连续 6 月 = 0」退役候选判据（实证 s27 的
+//   「NOTE 回归清单临时脚本缺失」以带前缀的全名落账 114 次，与无前缀写法分裂）。
+// 2026-10-22 门禁收敛批 2「信噪比」：advisory 告警（WARN/NOTE）按标签折叠输出（同类多行折为
+//   「×N 条同类」单行，明细落 tmp/check-loop-warn.log）——**BLOCK 一律不折**；无标签条目逐条输出。
+//   折叠只改呈现不改判据；实现见 warn-format.mjs（原锁折叠规则的 warn-format.test.mjs 已随引擎测试面退役 2026-10-28）。
+// 2026-11-08 引擎减重档 2-G：三类高频纯 WARN（状态未确认 / L3 确认缺失 / 复核上下文缺失，近 30 天
+//   台账 4185 条、纯检出不阻断）输出层默认静默——stderr 只留一行合计示意有量，judgments 落账与
+//   折叠明细（tmp/check-loop-warn.log）完整保留；CHECK_LOOP_VERBOSE=1 恢复逐条（与折叠开关同门）。
+// 2026-11-08 引擎减重档 3-U1：§23 登记式跳过退役（PREPUSH_SKIP_CONVERGENCE，2026-11-04 建，
+//   仅首日一用、近 30 天零触发）——§23 恒跑；跨机证据不对称红改走人工立项处置。
+// 2026-11-11 owner 拍板决策二：新增 §29 回归清单执法者配对（2026-11-10 审计 P1「168 条空执法者
+//   长期无告警」的机器补位；锚 regrEnforcerSince=2026-11-12，锚前存量不追溯）。hard 阻断面新增
+//   执法者配对(§29)；2026-10-22 gate-health「新增 hard 段须先退役一个」本次由 owner 显式拍板扩界（未退役段）。
+// 现状（2026-10-28）：5 段全部 hard（§1 §3x §8 §15 §23）；2026-11-11 owner 拍板决策二新增 §29
+//   回归清单执法者配对（审计 P1 168 条空执法者补位，扩界理由见 rule-budgets 同日注）→ 6 段全部 hard
+//   （§1 §3x §8 §15 §23 §29）。
+//   段数棘轮见 .agents/config/rule-budgets.txt（check-loop-sections 计数上限 6，退役一段同降一）。
+// --hygiene / --all 等价（hygiene 段已全部退役，见上）。
+// 扫描面（2026-10-28 减重第二刀）：s01/s15 默认只扫本轮 diff 触及的 workflow 文档（3s 级）；
+//   CHECK_LOOP_FULL=1 全量（CI 兜底，见 azure-pipelines.yml）——本地只拦「本轮引入」。
+import * as kit from './check-loop-kit.mjs';
+import { formatWarnings, writeWarnLog, WARN_LOG_REL } from './warn-format.mjs';
+import { recordRun } from './judgment-ledger.mjs';
+
+// 基础设施解构铺平（4a）：段体自单文件时代逐字保留，名字由本解构供给——零漂移迁移
+const {
+  fs, os, path, spawnSync, createHash, createRequire, fileURLToPath,
+  loadEnums, auditEnabled, loadKitPolicy, hasFreshVerifyLine, laneOfDoc, MARK_RE,
+  SCRIPT_DIR, GIT, REV_ARG, REV, ROOT, ENUMS, inSet, stOkDoc,
+  spawnGit, gitOut, linesOf, fmGet, WF, DOC_DIRS, blockers, warnings, kitPolicy, isTracked, docFiles,
+  addedDateOf, warnEvidenceExempt, VERIFY_GREEN_RE, verifyEvidenceTruth,
+  versionGreater, fmStatus, bindingSha256, readdirOrNull, isDirectoryOrNull,
+} = kit;
+
+import { run as s01_pairing } from './check-loop-sections/s01-pairing.mjs';
+import { run as s03x_regr_evidence } from './check-loop-sections/s03x-regr-evidence.mjs';
+import { run as s08_acceptance } from './check-loop-sections/s08-acceptance.mjs';
+import { run as s15_fingerprint } from './check-loop-sections/s15-fingerprint.mjs';
+import { run as s23_convergence_audit } from './check-loop-sections/s23-convergence-audit.mjs';
+import { run as s29_regr_enforcer } from './check-loop-sections/s29-regr-enforcer.mjs';
+// §2 §3 §4 §5 §9 §10 §14 §16 §18 §19 §21 §22 §24 §25 §26 §27 已退役（2026-10-28 引擎减重第一刀：
+//   全部 hygiene 段为纯 WARN、零阻断；段体删除，编号留疤不重排）。
+
+// 顺序 = 原单文件段序。仅 hard 车道（6 段，全部有阻断力）；hygiene 段已于 2026-10-28 全部退役。
+// 编号是承重引用（2026-10-11 D3 定案）：§N 被 policy 锚名（check14Since）、机制台账「门禁位置」列、
+// wiki 车道表、judgments rule 串跨文件引用——§7 空缺与 §3x 插号为历史疤，永不重编号（重编号=打断引用图）。
+const SECTIONS = [
+  { lane: 'hard', run: s01_pairing },
+  { lane: 'hard', run: s03x_regr_evidence },
+  { lane: 'hard', run: s08_acceptance },
+  { lane: 'hard', run: s15_fingerprint },
+  { lane: 'hard', run: s23_convergence_audit },
+  { lane: 'hard', run: s29_regr_enforcer },
+];
+// hygiene 车道已全部退役（2026-10-28 引擎减重第一刀）：--hygiene 与 --all 等价，均只跑 hard 6 段。
+if (kit.LOOP_MODE === 'hygiene') {
+  console.error('check-loop: hygiene 段已全部退役（2026-10-28）——本次只跑 hard 6 段');
+}
+// §23 收敛对账登记式跳过已退役（2026-11-08 减重档 3-U1，头注有记）——§23 恒跑，无环境变量开关。
+for (const section of SECTIONS) {
+  section.run();
+}
+// --- 判定流水落账（judgment-ledger，灰度消费端数据底座）---
+// 每次真实运行追加一行 per-rule 判定计数到 .agents/judgments.jsonl（本地 gitignore；fixture 经
+// CHECK_LOOP_ROOT 守卫自动跳过）——mechanism-registry 月度对账与 advisory→hard 升格判定的数据源
+// 由「人工 grep 输出」升级为 agg-judgments.mjs 查账。fail-open：落账失败不改变门禁裁决与输出契约。
+recordRun({ root: ROOT, mode: kit.LOOP_MODE, blockers, warnings });
+// --- 输出（banner 沿 sh 版格式 = 稳定输出契约：banner 后空行、条目 '- ' 前缀；文件名自称用 check-loop.mjs）---
+// 告警聚合（2026-10-22 门禁收敛批 2「信噪比」）：**折 advisory（WARN / NOTE），一律不折 BLOCK**。
+// 动机（实测）：一次 --all 跑出 17 条 WARN + 19 条 NOTE，其中同类多行 + 多行告警把 actionable 项淹掉——
+// 告警不精确比告警多更伤，输出一旦不可读，门禁即退化形式。折叠后逐条明细仍完整落
+// tmp/check-loop-warn.log（供排障与事后对质），不丢信息、不降判据。
+// 开关口径：只在「真引擎自跑」时折叠——判据取 ROOT 下是否有脚本本体（.agents/scripts/check-loop.mjs），
+// 夹具/临时仓从不落引擎副本（场景 91 用真 git 仓但无脚本本体），断言面因此零变化；
+// CHECK_LOOP_VERBOSE=1 强制逐条（排障用）。worktree 检出同样带脚本，正常折叠。
+// 实现落位：.agents/scripts/warn-format.mjs——本文件无 isMain 守卫（被 import 即全量执行并 exit），
+// 聚合逻辑不可在此直接单测；抽成无副作用模块 warn-format.mjs（原锁折叠规则的 warn-format.test.mjs 已随引擎测试面退役 2026-10-28）。
+const WARN_LOG = path.join(ROOT, 'tmp', 'check-loop-warn.log');
+const selfRun = fs.existsSync(path.join(ROOT, '.agents', 'scripts', 'check-loop.mjs'));
+const compactOn = selfRun && process.env.CHECK_LOOP_VERBOSE !== '1';
+// 三类高频纯 WARN 默认静默（2026-11-08 档 2-G，与头注同源）：仅折叠门（compactOn）开启时静默——
+//   夹具/VERBOSE=1 口径逐条输出不变。只滤 stderr 呈现：judgments 落账（recordRun 用全量 warnings）
+//   与明细日志（writeWarnLog 写全量清单）不受影响，非这三类标签的 WARN 行为不变。
+const QUIET_WARN_TAGS = ['WARN 状态未确认', 'WARN L3 确认缺失', 'WARN 复核上下文缺失'];
+const isQuietWarn = (line) => QUIET_WARN_TAGS.some((t) => line.startsWith(`- [${t}]`));
+const renderWarnings = (list) => {
+  if (!compactOn) return formatWarnings(list, { enabled: false });
+  writeWarnLog(list, WARN_LOG); // 完整明细照旧落盘（含静默三类）——静默只作用于 stderr
+  const quiet = list.filter(isQuietWarn);
+  const rest = list.filter((line) => !isQuietWarn(line));
+  const out = [];
+  if (rest.length) out.push(formatWarnings(rest, { enabled: true, logNote: WARN_LOG_REL }));
+  if (quiet.length) out.push(`- ${quiet.length} 条高频 WARN 已静默（状态未确认/L3 确认缺失/复核上下文缺失；明细 CHECK_LOOP_VERBOSE=1）`);
+  return out.join('\n');
+};
+if (blockers.length) {
+  process.stderr.write(`闭环骨架断档（check-loop.mjs）— HARD-BLOCK:\n\n${blockers.join('\n')}\n\n`);
+  if (warnings.length) process.stderr.write(`WARN（advisory,不阻断）:\n\n${renderWarnings(warnings)}\n`);
+  process.exit(1);
+}
+if (warnings.length) {
+  process.stderr.write(`check-loop.mjs WARN（advisory,不阻断）:\n\n${renderWarnings(warnings)}\n`);
+}
+// C1（2026-10-28）：FULL 手动审计末尾跑合并语义对拍探针——P0-A 修复（first-parent diff）被退化回
+// git show 时立红。仅本地 FULL（无 --rev/worktree、无夹具根）自动跑；探针可独立手动直跑。
+if (kit.FULL_SCAN && !kit.REV && !process.env.CHECK_LOOP_ROOT) {
+  const probe = kit.spawnSync(process.execPath, [path.join('.agents', 'scripts', 'check-loop-rev-semantics.mjs')], { stdio: 'inherit' });
+  if (probe.status !== 0) {
+    process.stderr.write('闭环骨架断档（check-loop.mjs）— 合并语义对拍探针未过（check-loop-rev-semantics.mjs）——REV 面实现疑似退化。HARD-BLOCK\n');
+    process.exit(1);
+  }
+}
+process.exit(0);

package/templates/engine/.agents/scripts/check-regression-consistency.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// check-regression-consistency — 回归清单 + verify-ui 特性地图的引用存在性检查（2026-10-17 关单活文档门，A1；
+//   2026-10-22 扩特性地图漂移：features/*.md 引用的路由/组件/文档/脚本必须还在，符号只做 advisory）
+// 动机：独立复核反复抓到「回归清单/wiki 残留旧口径」这类活文档债（规格内断言失效、被删测试仍被
+//   引用），却只在复核阶段可见。把「清单引用的资产还在吗」前移到关单 + 提交双闸，让残留当场被拦。
+// 口径（弱档 / 存在性，不猜语义）：清单条目是自由文本，无法机器对账语义，故只校验「引用指向的
+//   资产在仓库里仍存在、未改名/删除」。能抓「删了带外列但清单还说有」「测试类改名后清单未跟」；
+//   抓不到「值口径变了但符号还在」——那是强档语义对账，自由文本无结构化契约，显式不做。
+// 特性地图（verify-ui features/）：地图是验证的源，不是验证的果——路由/组件/文档/脚本引用悬空
+//   即漂移；「驱动步骤还能不能走通」仍需实测，机器不假装能证明行为。
+// 检查面（由复核抓到的残留类型定）：
+//   ① *Tests.cs 测试类 —— 在测试项目里确实存在（守卫被删/改名即引用悬空）
+//   ② tmp/*.mjs 脚本 —— 仅 advisory：tmp/ 在 .gitignore 第 67 行，脚本易失，不作为关单硬拦（防
+//      「脚本被本地清掉但条目仍有效」恒误报），只提示「清单引用了一个当前不在的 tmp 脚本」
+//   ③ workflow/*.md 文档 —— 引用的 intent/spec/plan/incident 文件名确实存在
+// 落点：
+//   - confirm-doc.mjs 关单（docs→done / incidents→closed）前置 —— 关单时拦，防残留进归档
+// 用法：node .agents/scripts/check-regression-consistency.mjs [--root <仓库根>]
+//   exit 0 = 无悬空引用；exit 1 = 存在悬空测试类/文档引用；tmp 缺失只警告不拦。
+// 测试面已随引擎减重退役（2026-10-28，owner 决策），本脚本现无测试兜底
+// 非独立门：由 confirm-doc.mjs 关单时动态调用（confirm-doc.mjs:551 附近）；按 check-* 命名易误判为钩子门，勿在钩子/verify 挂载。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+// 提取清单里引用的标识符（纯函数）。
+//   classes: `*Tests` 类名（门禁/单测/集成用例的标准命名）
+//   tmpScripts: `tmp/.../*.mjs` 临时验证脚本（e2e/headless 走查产物）
+//   docs: `workflow/.../*.md` 流程文档（intent/spec/plan/incident 引用）
+// 刻意不含表名/字段名——SQL 标识符在自由文本里误报率过高（MM_/frontend/ 等常见词会被误抓）。
+// 命名空间词排除（修真实误报）：`IntegrationTests` 是 tests/ 的项目目录名，清单叙述「集成测试残留
+//   审计」时以独立词出现，并非类名引用——但它以 Tests 结尾会被类名正则误抓，故显式排除（真实测试类
+//   不会取这个名，它永远是目录/命名空间）。这是唯一的已知系统性误报。
+export function extractRefs(text) {
+  const classes = new Set();
+  const tmpScripts = new Set();
+  const docs = new Set();
+  for (const m of text.matchAll(/\b[A-Za-z][A-Za-z0-9_]*Tests\b/g)) {
+    if (m[0] !== 'IntegrationTests') classes.add(m[0]);
+  }
+  for (const m of text.matchAll(/\btmp\/[A-Za-z0-9_./-]+\.mjs\b/g)) tmpScripts.add(m[0]);
+  for (const m of text.matchAll(/\bworkflow\/[A-Za-z0-9_./-]+\.md\b/g)) docs.add(m[0]);
+  return { classes, tmpScripts, docs };
+}
+
+// 收集测试项目里实际存在的测试类名（纯函数）。
+// 测试项目根：tests/ 下两个项目（Shipyard.Material.Tests / Shipyard.Material.IntegrationTests）。
+// 类名 = 文件名去 .cs（C# 一文件一类型约定）。fixture 目录可能不存在——返回空集，调用方按悬空判。
+function collectTestClasses(root) {
+  const names = new Set();
+  const testsDir = path.join(root, 'tests');
+  if (!fs.existsSync(testsDir)) return names;
+  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 (/\.cs$/i.test(e.name) && /Tests?\.cs$/i.test(e.name)) {
+        names.add(e.name.replace(/\.cs$/i, ''));
+      }
+    }
+  };
+  walk(testsDir);
+  return names;
+}
+
+// 主检查（纯函数）。读回归清单主文件 + 全部分片，对照仓库实际资产。
+// 返回 { danglingClasses, danglingDocs, missingTmp } —— 均为排序后的字符串数组。
+export function scanRegressionRefs(root) {
+  const wf = path.join(root, 'workflow');
+  const readIf = (p) => (fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '');
+  let text = readIf(path.join(wf, 'regression-checklist.md'));
+  const shardDir = path.join(wf, 'regression-checklist.d');
+  if (fs.existsSync(shardDir)) {
+    for (const f of fs.readdirSync(shardDir)) {
+      if (f.endsWith('.md')) text += '\n' + readIf(path.join(shardDir, f));
+    }
+  }
+  const refs = extractRefs(text);
+  const existing = collectTestClasses(root);
+  const danglingClasses = [...refs.classes].filter((c) => !existing.has(c)).sort();
+  const danglingDocs = [...refs.docs].filter((d) => !fs.existsSync(path.join(root, d))).sort();
+  const missingTmp = [...refs.tmpScripts].filter((s) => !fs.existsSync(path.join(root, s))).sort();
+  return { danglingClasses, danglingDocs, missingTmp };
+}
+
+// ---- 特性地图漂移（verify-ui features/，2026-10-22）----
+// 地图是验证的源：它引用的路由/组件/文档/脚本必须还在。机器只查「引用存在性」；
+// 「驱动步骤是否还能走通」仍需实测（月度/关单抽验），机器不假装能证明行为。
+// 符号（`OrderedContribution` / `Service.Method`）只做 advisory——自由文本里的代码符号
+// 可能来自生成物/外部库，硬拦误报率高。
+export function extractFeatureRefs(text) {
+  const routes = new Set();
+  const components = new Set();
+  const docs = new Set();
+  const scripts = new Set();
+  const symbols = new Set();
+  for (const m of text.matchAll(/#\/[A-Za-z0-9_./:-]+/g)) {
+    const r = m[0].replace(/^#/, '').replace(/[.,;)]+$/, '');
+    routes.add(r.length > 1 ? r.replace(/\/+$/, '') : r);
+  }
+  for (const m of text.matchAll(/\bfrontend\/src\/[A-Za-z0-9_./-]+\.(?:vue|ts|js)\b/g)) components.add(m[0]);
+  for (const m of text.matchAll(/\bworkflow\/[A-Za-z0-9_./-]+\.md\b/g)) docs.add(m[0]);
+  for (const m of text.matchAll(/\bscripts\/verify\/[A-Za-z0-9_./-]+\.mjs\b/g)) scripts.add(m[0]);
+  for (const m of text.matchAll(/`([A-Z][A-Za-z0-9_]{5,}(?:\.[A-Za-z0-9_]+)*)`/g)) symbols.add(m[1]);
+  return { routes, components, docs, scripts, symbols };
+}
+
+// 路由表：frontend/src/router/index.ts 的 path 字面量（相对路径补 /）。
+function collectRouterRoutes(root) {
+  const p = path.join(root, 'frontend', 'src', 'router', 'index.ts');
+  if (!fs.existsSync(p)) return null;
+  const routes = new Set();
+  for (const m of fs.readFileSync(p, 'utf8').matchAll(/path:\s*'([^']+)'/g)) {
+    const raw = m[1];
+    routes.add(raw.startsWith('/') ? raw : `/${raw}`);
+  }
+  return routes;
+}
+
+// 符号存在性：单点符号一次 git grep 扫 backend/ + frontend/；点号符号（Type.Member）先找同名
+// 类型文件（Type.cs/ts/js/vue）再查成员名——避免把 `Service.Method` 当字面量搜导致假悬空。
+function missingSymbols(root, symbols) {
+  if (!symbols.length) return [];
+  const simple = symbols.filter((s) => !s.includes('.'));
+  const qualified = symbols.filter((s) => s.includes('.'));
+  const missing = [];
+  if (simple.length) {
+    const args = ['grep', '-h', '-F'];
+    for (const s of simple) args.push('-e', s);
+    args.push('--', 'backend', 'frontend');
+    const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+    const hay = String(r.stdout || '');
+    for (const s of simple) if (!hay.includes(s)) missing.push(s);
+  }
+  for (const s of qualified) {
+    const member = s.split('.').pop();
+    const r = spawnSync('git', ['grep', '-l', '-F', '--', member, '--', 'backend', 'frontend'], { cwd: root, encoding: 'utf8' });
+    const files = String(r.stdout || '').split(/\r?\n/).filter(Boolean);
+    // 成员名在仓库任何位置存在即不判悬空（类型文件可能拆分/部分类/外部库）；成员完全不存在才是漂移信号。
+    if (!files.length) missing.push(s);
+  }
+  return missing.sort();
+}
+
+// 主检查（纯函数）：读 features/*.md，对照路由表 / 文件系统 / 符号面。
+export function scanFeatureMapRefs(root) {
+  const dir = path.join(root, '.agents', 'skills', 'verify-ui', 'features');
+  const empty = { danglingRoutes: [], danglingComponents: [], danglingDocs: [], danglingScripts: [], missingSymbols: [], files: 0 };
+  if (!fs.existsSync(dir)) return empty;
+  const router = collectRouterRoutes(root);
+  const routes = new Set();
+  const components = new Set();
+  const docs = new Set();
+  const scripts = new Set();
+  const symbols = new Set();
+  let files = 0;
+  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md'))) {
+    files++;
+    const r = extractFeatureRefs(fs.readFileSync(path.join(dir, f), 'utf8'));
+    for (const x of r.routes) routes.add(x);
+    for (const x of r.components) components.add(x);
+    for (const x of r.docs) docs.add(x);
+    for (const x of r.scripts) scripts.add(x);
+    for (const x of r.symbols) symbols.add(x);
+  }
+  return {
+    danglingRoutes: router ? [...routes].filter((r) => !router.has(r)).sort() : [],
+    danglingComponents: [...components].filter((c) => !fs.existsSync(path.join(root, c))).sort(),
+    danglingDocs: [...docs].filter((d) => !fs.existsSync(path.join(root, d))).sort(),
+    danglingScripts: [...scripts].filter((s) => !fs.existsSync(path.join(root, s))).sort(),
+    missingSymbols: missingSymbols(root, [...symbols]),
+    files,
+  };
+}
+
+// ---- 验证脚本锚点（scripts/verify/**/*.mjs，2026-10-22）----
+// 脚本里的 #/路由 与 data-testid 必须还在路由表/源码里——文件存在不等于脚本还能跑。
+// advisory：脚本可能引用外部/动态路由，硬拦误报率高。
+export function scanVerifyScriptAnchors(root) {
+  const dir = path.join(root, 'scripts', 'verify');
+  if (!fs.existsSync(dir)) return { danglingRoutes: [], danglingTestIds: [], files: 0 };
+  const router = collectRouterRoutes(root);
+  const routes = new Set();
+  const testIds = new Set();
+  let files = 0;
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) { walk(p); continue; }
+      if (!/\.mjs$/i.test(e.name)) continue;
+      files++;
+      const text = fs.readFileSync(p, 'utf8');
+      for (const m of text.matchAll(/#\/[A-Za-z0-9_./:-]+/g)) {
+        const r = m[0].replace(/^#/, '').replace(/[.,;)]+$/, '');
+        routes.add(r.length > 1 ? r.replace(/\/+$/, '') : r);
+      }
+      for (const m of text.matchAll(/data-testid=["']([^"']+)["']/g)) testIds.add(m[1]);
+    }
+  };
+  walk(dir);
+  const danglingRoutes = router ? [...routes].filter((r) => !router.has(r)).sort() : [];
+  const danglingTestIds = [...testIds].filter((id) => {
+    const a = spawnSync('git', ['grep', '-l', '-F', '--', `data-testid="${id}"`, '--', 'frontend/src'], { cwd: root, encoding: 'utf8' });
+    const b = spawnSync('git', ['grep', '-l', '-F', '--', `data-testid='${id}'`, '--', 'frontend/src'], { cwd: root, encoding: 'utf8' });
+    return a.status !== 0 && b.status !== 0;
+  }).sort();
+  return { danglingRoutes, danglingTestIds, files };
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('check-regression-consistency.mjs');
+if (isMain) {
+  const argv = process.argv.slice(2);
+  let root = process.cwd();
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root') root = path.resolve(argv[++i]);
+    else if (argv[i] === '--help' || argv[i] === '-h') {
+      console.log('用法：node .agents/scripts/check-regression-consistency.mjs [--root <仓库根>]');
+      process.exit(0);
+    }
+  }
+  const r = scanRegressionRefs(root);
+  for (const t of r.missingTmp) {
+    console.log(`ℹ️  清单引用的临时脚本当前不在（tmp/ 易失，不拦）：${t}`);
+  }
+  const fm = scanFeatureMapRefs(root);
+  for (const s of fm.missingSymbols) {
+    console.log(`ℹ️  特性地图引用的符号未在 backend/frontend 找到（advisory，可能是生成物/外部库）：${s}`);
+  }
+  const sa = scanVerifyScriptAnchors(root);
+  for (const r of sa.danglingRoutes) {
+    console.log(`ℹ️  验证脚本引用的路由不在 router（advisory）：${r}`);
+  }
+  for (const t of sa.danglingTestIds) {
+    console.log(`ℹ️  验证脚本引用的 data-testid 不在 frontend/src（advisory）：${t}`);
+  }
+  const problems = [];
+  for (const c of r.danglingClasses) problems.push(`悬空测试类：${c}`);
+  for (const d of r.danglingDocs) problems.push(`悬空流程文档：${d}`);
+  for (const x of fm.danglingRoutes) problems.push(`特性地图悬空路由：${x}`);
+  for (const x of fm.danglingComponents) problems.push(`特性地图悬空组件：${x}`);
+  for (const x of fm.danglingDocs) problems.push(`特性地图悬空文档：${x}`);
+  for (const x of fm.danglingScripts) problems.push(`特性地图悬空脚本：${x}`);
+  if (problems.length) {
+    console.error(`\n❌ 活文档引用了不存在的资产（${problems.length} 处）——残留未清：`);
+    for (const p of problems) console.error('  - ' + p);
+    console.error('  处理：删除/改写清单或特性地图里已过时的条目（维护规则 4），或恢复被误删的资产。');
+    process.exit(1);
+  }
+  console.log(`✅ 活文档引用一致：回归清单无悬空测试类/文档；特性地图 ${fm.files} 件无悬空路由/组件/文档/脚本；验证脚本 ${sa.files} 件锚点无悬空${r.missingTmp.length ? `（${r.missingTmp.length} 个 tmp 脚本缺失仅提示）` : ''}`);
+  process.exit(0);
+}

package/templates/engine/.agents/scripts/check-schema-residue.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * check-schema-residue.mjs — 「已删列/新增列 vs 实库」残留审计（只读）
+ *
+ * 用途：批次（wiki/数据维护/schema变更/*）登记的列变更与 dev 实库比对，
+ *       找出「批次已删却仍在」（残留＝带外加列/批次语句静默失效）
+ *       与「批次已加却不存在」（缺失＝带外删列）两类漂移。
+ *
+ * 起源：2026-10-12 dev 库带外加列反复回加（incident 2026-10-12-outband-column-readd-recurring）；
+ *       同日发现 `LINENO` 为 T-SQL 关键字致 `DROP COLUMN LineNo` 静默不生效 —— 本脚本可一次扫出该类。
+ *
+ * 口径：
+ *   - 取各批次 `0N-*.sql` 中**动作类**脚本：排除 `99-*`（回滚）、`*rollback*`（语义反转）、`*verify*`（核验脚本非动作）；
+ *   - 逐条 `ALTER TABLE` 语句内扫描 `ADD [COLUMN]` / `DROP [COLUMN]` 的**多列清单**（顶层逗号切分；跳过 CONSTRAINT/PRIMARY/UNIQUE/… 等约束子句）；
+ *   - 同（表,列）以批次目录名排序取**最后一次**动作；
+ *   - `ADD` 后缺失 → 缺失；`DROP` 后仍存在 → 残留。
+ *
+ * 已知盲区（人工兜底，勿当全量证明）：
+ *   - 动态 SQL（`EXEC(N'ALTER TABLE … DROP COLUMN …')`）解析不可见（如 2026-09-29-consignment-vmi-rollback）；
+ *   - 同目录内名为 `0N-rollback-*.sql` 的回滚脚本按文件名排除（其语义为撤销 01，判定会反转）。
+ *
+ * 豁免（EXEMPT）：**带方向**的已判定项——只在登记的该方向上豁免，反方向仍照常报警：
+ *   - `direction: 'missing'`：批次已加但实库不存在，且已人工核实为「更晚批次删除」等台账侧过时；
+ *   - `direction: 'residue'`：批次已删但实库仍在，且已人工核实为「实体确实声明该列」（台账注释过时）。
+ *
+ * 依赖：sqlcmd（PATH 可达）与 backend/material/Shipyard.Material.API/appsettings.json 的 DBConnParameter。
+ * 用法：node .agents/scripts/check-schema-residue.mjs [--verbose]
+ * 退出码：0 = 无未解释残留/缺失；1 = 有；2 = 前置缺失（appsettings/sqlcmd）。
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+const base = path.join(root, 'wiki', '数据维护', 'schema变更');
+const verbose = process.argv.includes('--verbose');
+const SKIP = new Set(['CONSTRAINT', 'PRIMARY', 'UNIQUE', 'INDEX', 'CHECK', 'FOREIGN', 'NONCLUSTERED', 'CLUSTERED', 'KEY', 'COLUMN', 'ADD', 'DROP']);
+
+// 已判定豁免（带方向；人工核过，不计入对应方向的残留/缺失信号）
+const EXEMPT = new Map([
+  ['MM_PML_ProductionPMLMaterial.MTOMaterialID', { direction: 'residue', reason: '实体（本仓 ProductionPMLMaterial.cs:18 与并行分支）均声明该属性 → 2026-09-28 批次「实体中无此字段」注释已过期，列合法保留；台账/核验脚本待更新' }],
+  ['MM_INV_InventoryRecord.OwnershipType', { direction: 'missing', reason: '2026-09-29-consignment-vmi-rollback 已用动态 SQL 删除（VMI 货权回滚），旧批次断言过时' }],
+  ['MM_INV_InventoryRecord.OwnerSupplierID', { direction: 'missing', reason: '同上（VMI 货权回滚删除）' }],
+  ['MM_INV_InventoryRecord.OwnerSupplierName', { direction: 'missing', reason: '同上（VMI 货权回滚删除）' }],
+  ['MM_INV_InventoryTransaction.OwnershipType', { direction: 'missing', reason: '同上（VMI 货权回滚删除）' }],
+  ['MM_INV_InventoryTransaction.OwnerSupplierID', { direction: 'missing', reason: '同上（VMI 货权回滚删除）' }],
+  ['MM_ISS_OutboundRequestDetail.OwnershipType', { direction: 'missing', reason: '同上（VMI 货权回滚删除）' }],
+  ['MM_ISS_OutboundRequestDetail.OwnerSupplierID', { direction: 'missing', reason: '同上（VMI 货权回滚删除）' }],
+  ['MM_ISS_OutboundRequestDetail.OwnerSupplierName', { direction: 'missing', reason: '同上（VMI 货权回滚删除）' }],
+  ['MM_ISS_OutboundOrderDetail.OwnershipType', { direction: 'missing', reason: '同上（VMI 货权回滚删除）' }],
+  ['MM_ISS_OutboundOrderDetail.OwnerSupplierID', { direction: 'missing', reason: '同上（VMI 货权回滚删除）' }],
+  ['MM_ISS_OutboundOrderDetail.OwnerSupplierName', { direction: 'missing', reason: '同上（VMI 货权回滚删除）' }],
+  ['MM_PML_ProductionPMLQuota.SourceMaterialCode', { direction: 'missing', reason: '2026-10-23-pml-quota-substitute-columns 批次已 sp_rename 为 SubstituteMaterialCode（本脚本只解析 ADD/DROP，sp_rename 不可见）→ 2026-09-28-pml-source-material-fields 的 ADD 期望过时' }],
+  ['MM_PML_ProductionPMLQuota.SourceMaterialName', { direction: 'missing', reason: '同上（2026-10-23 批次已 sp_rename 为 SubstituteMaterialName）' }],
+]);
+
+const appsettings = path.join(root, 'backend', 'material', 'Shipyard.Material.API', 'appsettings.json');
+if (!fs.existsSync(appsettings)) { console.error(`未找到 ${appsettings}`); process.exit(2); }
+const conn = JSON.parse(fs.readFileSync(appsettings, 'utf8')).DBConnParameter;
+if (!conn) { console.error('appsettings.json 缺 DBConnParameter'); process.exit(2); }
+const pick = (k) => (conn.match(new RegExp(`(?:^|;)\\s*${k}\\s*=\\s*([^;]+)`, 'i')) || [])[1];
+const sqlcmdArgs = ['-S', pick('Server'), '-d', pick('Database'), '-U', pick('User Id'), '-P', pick('Password'), '-h', '-1', '-W', '-f', '65001'];
+
+const sqlcmd = (query) => execFileSync('sqlcmd', [...sqlcmdArgs, '-Q', query], { encoding: 'utf8' });
+
+/** 顶层逗号切分（忽略括号内逗号） */
+function splitTopLevel(text) {
+  const parts = []; let depth = 0; let cur = '';
+  for (const ch of text) {
+    if (ch === '(') depth++;
+    else if (ch === ')') depth = Math.max(0, depth - 1);
+    if (ch === ',' && depth === 0) { parts.push(cur); cur = ''; continue; }
+    cur += ch;
+  }
+  parts.push(cur);
+  return parts;
+}
+
+/** 取一条 ALTER 语句体里的目标列标识符（多列清单 + 跳过约束子句） */
+function targetsOf(body) {
+  const out = [];
+  for (const m of body.matchAll(/\b(ADD|DROP)\s+(?:COLUMN\s+)?/gi)) {
+    const tail = body.slice(m.index + m[0].length);
+    for (const seg of splitTopLevel(tail)) {
+      const cleaned = seg.replace(/^\s*COLUMN\s+/i, '');   // `ADD COLUMN a INT, COLUMN b INT` 的第二段
+      const id = /^\s*\[?(\w+)\]?/.exec(cleaned);
+      if (!id) continue;
+      const name = id[1];
+      if (SKIP.has(name.toUpperCase())) continue;
+      out.push({ action: m[1].toUpperCase(), name });
+    }
+  }
+  return out;
+}
+
+// 1) 解析批次登记动作（表 | 列 → 最后动作）
+const acts = new Map();
+const isActionFile = (x) => /^0\d-.*\.sql$/i.test(x) && !/^99-/.test(x) && !/rollback/i.test(x) && !/verify/i.test(x);
+for (const d of fs.readdirSync(base, { withFileTypes: true }).filter((x) => x.isDirectory()).map((x) => x.name).sort()) {
+  for (const f of fs.readdirSync(path.join(base, d)).filter(isActionFile).sort()) {
+    const raw = fs.readFileSync(path.join(base, d, f), 'utf8')
+      .replace(/\/\*[\s\S]*?\*\//g, ' ')
+      .split(/\r?\n/).map((l) => l.replace(/--.*$/, '')).join('\n');
+    // 语句体边界：分号 **或** 下一条 ALTER TABLE 起（防「无分号 + GO」写法把列记到前一张表名下）
+    for (const m of raw.matchAll(/ALTER\s+TABLE\s+(?:\[?dbo\]?\.)?\[?(\w+)\]?\s+([\s\S]*?)(?=;|\bALTER\s+TABLE\b|$)/gi)) {
+      const [, table, body] = m;
+      for (const { action, name } of targetsOf(body)) {
+        const key = `${table}|${name}`;
+        const cur = acts.get(key);
+        if (!cur || d >= cur.order) acts.set(key, { order: d, action, src: `${d}/${f}` });
+      }
+    }
+  }
+}
+
+// 2) 与实库比对
+const exists = (t, c) => sqlcmd(`SET NOCOUNT ON; SELECT CASE WHEN EXISTS(SELECT 1 FROM sys.columns WHERE object_id=OBJECT_ID('dbo.${t}') AND name='${c}') THEN 'Y' ELSE 'N' END;`).split(/\r?\n/)[0].trim() === 'Y';
+const residue = []; const missing = []; const exempted = [];
+for (const [key, v] of acts) {
+  const [t, c] = key.split('|');
+  if (!/^[A-Za-z_]\w*$/.test(t) || !/^[A-Za-z_]\w*$/.test(c)) continue;
+  const dir = v.action === 'ADD' ? 'missing' : 'residue';
+  const bad = dir === 'missing' ? !exists(t, c) : exists(t, c);
+  if (!bad) continue;
+  const ex = EXEMPT.get(`${t}.${c}`);
+  if (ex && ex.direction === dir) exempted.push([`${t}.${c}`, dir, ex.reason]);
+  else (dir === 'missing' ? missing : residue).push([t, c, v.src]);
+}
+
+console.log(`[schema-residue] 扫描批次动作 ${acts.size} 项（wiki/数据维护/schema变更；排除 99-rollback / *rollback* / *verify*）`);
+console.log(`[schema-residue] 残留（批次已删仍存在）${residue.length} 项 / 缺失（批次已加不存在）${missing.length} 项 / 已豁免 ${exempted.length} 项（按方向）`);
+for (const [t, c, s] of residue) console.log(`  ⚠ 残留 ${t}.${c}  ← ${s}`);
+for (const [t, c, s] of missing) console.log(`  ⚠ 缺失 ${t}.${c}  ← ${s}`);
+if (process.argv.includes('--dump')) {
+  const filter = process.argv[process.argv.indexOf('--dump') + 1];
+  const re = new RegExp(filter ?? '.', 'i');
+  console.log(`[schema-residue] --dump ${filter ?? '.'} 命中：`);
+  for (const [k, v] of acts) if (re.test(k)) console.log(`  · ${k} ${v.action} ← ${v.src}`);
+}
+if (verbose) {
+  console.log('[schema-residue] 豁免明细（带方向；反方向仍会报警）：');
+  for (const [k, dir, reason] of exempted) console.log(`  · [${dir}] ${k} — ${reason}`);
+}
+process.exit(residue.length || missing.length ? 1 : 0);