agentic-flow-kit 1.8.7 → 2.1.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-pipeline-state.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// check-pipeline-state.mjs — pipeline-run 状态机闭包检查（静态，零依赖）
+//
+// 背景（Anthropic《The AI-native SDLC playbook》Stage 6）：闭环执行器的可信度
+// 来自“状态转移是闭集”。pipeline-run 自述“保留待用、零 run”，在第一次真实 run 之前，
+// 至少要有机器检查保证：脚本里出现的 stage / stopType 都在登记表内，登记表里的 stage
+// 也都在脚本里可达。
+//
+// 这是静态合同检查，不替代一次端到端 run；它拦住“新增/改名 stage 忘了登记”的低级漂移。
+//
+// 用法：
+//   node .agents/scripts/check-pipeline-state.mjs [--json] [--file <path>]
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_FILE = '.agents/scripts/pipeline-run.mjs';
+const DEFAULT_CFG = '.agents/config/pipeline.json';
+
+export function analyze(source, config) {
+  const problems = [];
+  const stages = new Set(config.stages || []);
+  const stopTypes = new Set(config.stopTypes || []);
+
+  const stageLiterals = [...String(source).matchAll(/(?:run\.stage\s*=\s*|stage:\s*)'([a-z][a-z0-9-]*)'/g)].map((m) => m[1]);
+  const stopLiterals = [...String(source).matchAll(/(?:run\.stopType\s*=\s*|stopType:\s*)'([a-z][a-z0-9-]*)'/g)].map((m) => m[1]);
+  const handled = [...String(source).matchAll(/(?:\bs\s*===\s*)'([a-z][a-z0-9-]*)'/g)].map((m) => m[1]);
+
+  const seenStages = new Set([...stageLiterals, ...handled]);
+  for (const s of seenStages) if (!stages.has(s) && s !== 'cur' && s !== 'past' && s !== 'string') {
+    problems.push(`stage 未登记：'${s}'（补 .agents/config/pipeline.json 的 stages）`);
+  }
+  for (const s of stages) {
+    if (!seenStages.has(s)) problems.push(`登记的 stage 在 pipeline-run 中不可达：'${s}'`);
+  }
+  for (const s of new Set(stopLiterals)) {
+    if (!stopTypes.has(s)) problems.push(`stopType 未登记：'${s}'（补 stopTypes）`);
+  }
+  for (const s of stopTypes) {
+    if (!stopLiterals.includes(s)) problems.push(`登记的 stopType 在脚本中未出现：'${s}'`);
+  }
+  if (!seenStages.has('triage')) problems.push("初始 stage 'triage' 未出现");
+
+  return {
+    ok: problems.length === 0,
+    problems,
+    counts: { stages: stageLiterals.length, handled: handled.length, stopTypes: stopLiterals.length },
+  };
+}
+
+function argOf(argv, name, fallback = null) {
+  const i = argv.indexOf(`--${name}`);
+  if (i < 0) return fallback;
+  const v = argv[i + 1];
+  return v == null || v.startsWith('--') ? true : v;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const root = path.resolve(argOf(argv, 'root', process.cwd()));
+  const file = path.resolve(root, argOf(argv, 'file', DEFAULT_FILE));
+  const cfgFile = path.resolve(root, argOf(argv, 'config', DEFAULT_CFG));
+  if (!fs.existsSync(file)) {
+    console.error(`✗ 找不到 ${path.relative(root, file)}`);
+    return 2;
+  }
+  if (!fs.existsSync(cfgFile)) {
+    console.error(`✗ 找不到 ${path.relative(root, cfgFile)}`);
+    return 2;
+  }
+  const res = analyze(fs.readFileSync(file, 'utf8'), JSON.parse(fs.readFileSync(cfgFile, 'utf8')));
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify(res, null, 2));
+    return res.ok ? 0 : 1;
+  }
+  if (!res.ok) {
+    console.error('✗ pipeline 状态机闭包检查失败：');
+    for (const p of res.problems) console.error(`  - ${p}`);
+    return 1;
+  }
+  console.log(`✅ pipeline 状态机闭包（stages=${res.counts.stages} handled=${res.counts.handled} stopTypes=${res.counts.stopTypes}）`);
+  return 0;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('check-pipeline-state.mjs');
+if (isMain) process.exit(main());

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