agentic-flow-kit 1.8.7 → 2.0.0

package/templates/engine/.agents/scripts/verify-scope.mjs

@@ -0,0 +1,163 @@
+// verify-scope.mjs — verify.mjs diff 面增量关单的纯逻辑（verify-diet 2026-10-21 ②；复核修复 2026-10-21）
+// 口径：--scope 取「基线..HEAD ∪ 工作区(含暂存) ∪ untracked」变更面，未被面触及的产品**重门**跳过；
+// 密钥扫描 + wiki 三方一致性 + 关单主干引擎门恒跑（scripts-syntax/workflows-check/rule-budget/
+// effective-policy 秒级、check-loop / lane-surface-ci 是关单本体——后端改动可能使 wiki 断言漂移，
+// 故 wiki 门也不按面裁剪）。引擎测试面已退役（2026-10-28）：engine-tests 门不存在，.agents/ 不映射门。
+// 面触及对应路径 = 相应门自然回列（skipped 收缩）。
+// 基线选择：优先「最近一次全量（非 scope）绿行」的 headShort（调用方自本地台账 ∪ 仓库凭证
+// workflow/verify-evidence.md 读出，须为 HEAD 祖先），否则回落 merge-base(origin/main, HEAD)。
+// 前者让 scope 在长生命特性分支上可用（上次全量绿后只动文档 → 增量）；后者是冷启动基线。
+// 仓库凭证兜底（verify-evidence-fallback 2026-10-22）：新 worktree 无本地台账时不再必然重付全量税。
+// 两态都**过包含**（基线越旧面越大 → 产品门多跑，安全侧）。
+// fail-loud：基线解析失败 / diff 面为空 → 抛错拒增量（跑全量），不猜。
+// 产品门单边化 CI（2026-11-08 档 1-B；2026-11-11 增代码四门）：本地增量档（verify.mjs 缺省 / --scope /
+// --face）不再执行产品 cohort 5 门（= PRODUCT_FACES 门映射并集）＋代码四门（全仓扫描、不映射任何面，
+// 故显式追加，见 CI_UNILATERAL_GATE_IDS），执法点单边移交 CI——本文件的
+// 面分类口径（classifyFace / computeDiffScope）不变，单边化裁剪在 verify.mjs 门清单装配处执行。
+// 面源三路（复核 P1 修复）：committed diff 须 --no-renames（rename 只报目的地会隐藏产品源路径）、
+// 工作区 diff、untracked（ls-files --others——未 add 的新后端文件也必须算面，否则 scope 凭证对
+// 「含未编译后端代码的树」做假担保）。凭证：scope 绿行 entry.scope = { mode, base, baseSource,
+// skipped, fileCount }——gen-verify-evidence 渲染进摘要行；hasFreshVerifyLine 认其为合法关单凭证
+// （面计算已担保「基线以来未触对应产品路径」，与 24h 窗同信任级；关单前新提交须重跑——先提交、后跑门）。
+
+// 产品重门 ←→ 变更面匹配（前缀大小写不敏感——case-only 改名 / Linux CI 检出下不逃逸）。
+// backend 面含 .sql 后缀兜底（防根级数据维护 SQL 绕过；存量 SQL 全在 backend/ 下已由前缀覆盖）；
+// 亦含 scripts/verify/backend/（backend-build/backend-test 门的执行器自身——2026-10-24 复核 P1 修复：
+// 该路径此前 face/scope/语法门/run-tests 四重守护全不触及，只改执行器的提交会静默跳过整个 backend 门）。
+// 收窄到 backend/ 子目录（2026-10-24 复核 m3）：business/（约 70 个 UI 实测脚本）与 e2e/ 改动不驱动
+// backend 重门；新增共享模块须放 scripts/verify/backend/ 或在此显式加前缀。
+export const PRODUCT_FACES = [
+  {
+    face: 'backend',
+    gates: ['backend-build', 'backend-test'],
+    match: (f) => /^(backend|tests|scripts\/verify\/backend)\//i.test(f) || /\.(cs|sln|csproj|props|targets|sql)$/i.test(f),
+  },
+  {
+    face: 'frontend',
+    gates: ['frontend-lint', 'frontend-unit-test', 'frontend-build'],
+    match: (f) => /^frontend\//i.test(f),
+  },
+  {
+    // docs 面（2026-11-08 档 1-B）：显式「无产品面」取值——--face docs 的合法值来源；不匹配任何
+    // 路径、无门映射（gates 空），classifyFace 语义不变（永不触达、skipped 不增）。
+    face: 'docs',
+    gates: [],
+    match: () => false,
+  },
+];
+
+// 产品门单边化 CI（2026-11-08 档 1-B，owner 拍板）：本地增量档不执行的产品门集合 = 各面门映射并集
+// （backend-build / backend-test / frontend-lint / frontend-unit-test / frontend-build；docs 面无门自然
+// 不入）＋代码四门（2026-11-11 owner 拍板接入，审计 P2「--no-verify 远端兜底缺口」：全仓扫描门，
+// 不映射任何面，故在此显式追加）。面内五门单源随 PRODUCT_FACES 演进；verify.mjs 门清单装配与跳过
+// 说明行消费。--full/--mid/--product 三档与 CI（azure-pipelines）不受影响。
+export const CI_UNILATERAL_GATE_IDS = new Set([
+  ...PRODUCT_FACES.flatMap((pf) => pf.gates),
+  'code-architecture', 'code-audit-fields', 'code-delete-guard', 'code-notify-guard',
+]);
+
+// 台账触及面（2026-10-24 复核 P1）：ledger-invariant 不再无条件退 CI-only——本地默认档（diff）在
+// commit/worktree/untracked 触及 confirmations 台账或其 manifest 时回列全史扫描（台账改动才付 ~90s），
+// 未触及仍 loud-skip。全量档（无 scope）与 CI 照跑。判据只加字段，不改 GATE_FACES/skipped 口径
+// （避免与既有门表计数、--list 契约耦合）。
+export const LEDGER_TOUCH_RE = /^\.agents\/confirmations(?:\.jsonl|\.d\/)|^\.agents\/config\/ledger-.*manifest\.json$/i;
+
+// 引擎测试面退役（2026-10-28，owner 决策）：engine-tests 门与 ENGINE_TEST_FACE 一并删除——
+// 引擎改动不再按面触发测试门（.agents/ 全部不再映射到任何门）。产品面不受影响。
+
+const GATE_FACES = [...PRODUCT_FACES];
+
+// 仓库级绿凭证（verify-evidence-fallback 2026-10-22）：workflow/verify-evidence.md 是入库的追加保全
+// 摘要（gen-verify-evidence.mjs 生成），每行 = 某基线提交过全量门禁全绿。本地台账
+// （.agents/verifications.jsonl）per-worktree 且 gitignore——新 worktree 无绿行时默认档会退回全量
+// （verify.mjs 24h 兜底）。本解析把「仓库级绿行」纳入基线候选：跨树/跨机不再重付全量税；基线仍须过
+// merge-base --is-ancestor（非祖先 = 别的分支/rebase 残留，拒用）。
+// 只认全量行：末列以 `scope=`（门被裁过）或 `fast=`（engine-tests 降 --fast 的裁剪绿，
+// 2026-10-24 复核 P1-5）开头的是增量/降档凭证，不能当全量锚；其余（`—` 或 runId）皆全量。
+export const EVIDENCE_REL = 'workflow/verify-evidence.md';
+const EVIDENCE_ROW_RE = /^\|\s*`([0-9a-f]{7,40})`\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|\s*$/;
+
+/** 解析摘要文件 → 全量绿行 [{ headShort, ts }]（坏行/表头/scope 行跳过，不抛）。 */
+export function parseEvidenceGreens(text) {
+  const out = [];
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const m = raw.trim().match(EVIDENCE_ROW_RE);
+    if (!m) continue;
+    // skip-env（2026-10-27 anchor-envskip）：带 CI-only 门跳过标记的绿行实跑门数 < 门表，
+    // 与 scope/fast 同属「裁剪凭证」，不得作全量锚（否则跨机基线建立在漏跑门的树上）。
+    if (/^(scope|fast|skip-env)=/.test(m[5].trim())) continue;
+    const ts = m[2].trim();
+    if (!Number.isFinite(Date.parse(ts))) continue;
+    out.push({ headShort: m[1], ts });
+  }
+  return out;
+}
+
+/**
+ * 纯分类：变更路径数组（POSIX 斜杠）→ { touched:Set<face>, skippedGateIds:string[], matched:string[] }。
+ * 路径按「面序」归属——一条路径只归一个面（backend/tests 前缀优先于扩展名兜底的次序即数组序）。
+ */
+export function classifyFace(files) {
+  const touched = new Set();
+  const matched = [];
+  for (const raw of files || []) {
+    const f = String(raw).replace(/\\/g, '/');
+    for (const pf of GATE_FACES) {
+      if (pf.match(f)) { touched.add(pf.face); matched.push(f); break; }
+    }
+  }
+  const skippedGateIds = GATE_FACES.filter((pf) => !touched.has(pf.face)).flatMap((pf) => pf.gates);
+  return { touched, skippedGateIds, matched };
+}
+
+/**
+ * 组装 scope：git(args) 注入（返回 { status, stdout }，cwd=仓库根），便于夹具测试；
+ * baseHint = 调用方选出的「最近全量绿行 headShort」（可为 null）；baseSourceHint = 该 hint 的来源
+ * （'ledger' 本地台账 | 'evidence' 仓库凭证），原样写进凭证供审计对质。
+ * 返回 { baseShort, baseSource:'ledger'|'evidence'|'origin/main', fileCount, touched, skippedGateIds, matched }；
+ * 任何解析失败抛 Error（中文，直出 stderr）。
+ */
+export function computeDiffScope(git, baseHint = null, baseSourceHint = 'ledger') {
+  const out = (args) => {
+    const r = git(args);
+    if (r.status !== 0) throw new Error(`git ${args.join(' ')} 失败——无法确定增量基线（先 git fetch origin，或跑全量 verify）`);
+    return String(r.stdout || '').trim();
+  };
+  const head = out(['rev-parse', 'HEAD']);
+  let base = null;
+  let baseSource = null;
+  if (baseHint) {
+    const anc = git(['merge-base', '--is-ancestor', baseHint, head]);
+    if (anc.status === 0) { base = baseHint; baseSource = baseSourceHint; }
+  }
+  if (!base) {
+    base = out(['merge-base', 'origin/main', 'HEAD']);
+    baseSource = 'origin/main';
+  }
+  const baseShort = out(['rev-parse', '--short', base]);
+  const committed = out(['-c', 'core.quotepath=off', 'diff', '--name-only', '--no-renames', `${base}..${head}`])
+    .split(/\r?\n/).filter(Boolean);
+  const worktree = out(['-c', 'core.quotepath=off', 'diff', '--name-only', '--no-renames', 'HEAD'])
+    .split(/\r?\n/).filter(Boolean);
+  // untracked 亦须 quotepath=off（2026-10-24 复核 M2）：默认 core.quotepath=true 时非 ASCII 路径被
+  // 加引号转义（"backend/\344\270\255..."），前缀与扩展名双双失配 → 新后端文件逃出变更面、scope 绿行假担保
+  const untracked = out(['-c', 'core.quotepath=off', 'ls-files', '--others', '--exclude-standard'])
+    .split(/\r?\n/).filter(Boolean);
+  const files = [...new Set([...committed, ...worktree, ...untracked])];
+  if (!files.length) {
+    throw new Error('diff 面为空（基线以来无任何变更）——无增量依据，跑全量 verify');
+  }
+  const cls = classifyFace(files);
+  return {
+    baseShort,
+    baseSource,
+    fileCount: files.length,
+    touched: cls.touched,
+    skippedGateIds: cls.skippedGateIds,
+    matched: cls.matched,
+    // 变更面文件清单（统一斜杠）：供 --scope 档做「只 lint 变更文件」这类按面缩范围的门
+    files: files.map((f) => String(f).replace(/\\/g, '/')),
+    // 台账触及（ledger-invariant 本地回列判据；见头注 LEDGER_TOUCH_RE）
+    ledgerTouched: files.some((f) => LEDGER_TOUCH_RE.test(String(f).replace(/\\/g, '/'))),
+  };
+}

package/templates/engine/.agents/scripts/verify-wiki-consistency.mjs

@@ -0,0 +1,264 @@
+// wiki 三方一致性验证：磁盘 ↔ INDEX.md ↔ 知识沉淀总览.html(DATA) ＋ 数据维护台账登记 ＋ 看板链接可达性
+// 用法: node .agents/scripts/verify-wiki-consistency.mjs   （不一致 exit 1）
+// 约定见 .agents/skills/wiki/SKILL.md；归档 drafts-archive 仅计数，不参与文件比对。
+// 口径（2026-09-17 起，与 gen-wiki-board.mjs 保持一致）：主题目录顶层全量文件登记 +
+//      直属子目录中的 md/html 知识文档（排除 *.visual-check.* 工具产物；数据维护主题例外——
+//      其子目录 schema变更/<批次>/ 等走 README 台账，不参与三方文件比对与 summary 统计）；
+//      递归扫描仅用于「断链守卫 + 数据维护批次台账登记」两项断言，避免改变既有统计口径误报。
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { checkNarrativeClaims } from './gen-narrative-claims.mjs';
+
+const WIKI = 'wiki';
+const problems = [];
+const notes = [];
+
+// 类型判定：Dirent 直判（2026-11-06 P1）——原实现每条目一次 statSync（wiki 803 文件 / 212 目录，
+// 多轮遍历累计 ~2000+ 次 stat，Windows ~0.5-1ms/次）；symlink 回落 statSync 保持原语义（跟随链接）。
+const isDirEntry = (e, parent) => e.isDirectory() || (e.isSymbolicLink() && fs.statSync(path.join(parent, e.name)).isDirectory());
+const isFileEntry = (e, parent) => e.isFile() || (e.isSymbolicLink() && fs.statSync(path.join(parent, e.name)).isFile());
+
+// 递归列目录（相对 dir 的路径，仅正斜杠）；drafts-archive 由调用方排除
+const walkTree = (dir, rel = '') => {
+  const acc = { files: [], dirs: [] };
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (isDirEntry(e, dir)) {
+      acc.dirs.push(r);
+      const sub = walkTree(path.join(dir, e.name), r);
+      acc.files.push(...sub.files);
+      acc.dirs.push(...sub.dirs);
+    } else acc.files.push(r);
+  }
+  return acc;
+};
+
+// ---- 磁盘枚举（登记口径与 gen-wiki-board.mjs 一致）----
+const isKnowledgeDoc = (f) => /\.(md|html)$/i.test(f) && !/\.visual-check\./i.test(f);
+// gitignore 豁免（F4，incident 2026-09-23-code-review-f3-f4-closeout）：drafts-archive 含
+// .gitignore 忽略的本机文件（如 *.xlsx），计入会使生成物计数在 fresh clone 必然漂移；
+// 口径 = 排除忽略文件（git 不可用/非仓库时退化为全量计数，fixture 环境不受影响）
+const gitIgnoredArchive = (() => {
+  try {
+    const out = execSync('git -c core.quotepath=false status --ignored=matching --porcelain -uall -- wiki',
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const prefix = 'wiki/';
+    return new Set(out.split(/\r?\n/)
+      .filter((l) => l.startsWith('!! '))
+      .map((l) => l.slice(3).trim().replace(/\/$/, ''))
+      .filter((p) => p.startsWith(prefix))
+      .map((p) => p.slice(prefix.length)));
+  } catch {
+    return new Set();
+  }
+})();
+const diskFiles = new Set(); // "主题/文件名"（子目录文件名带 子目录/ 前缀）
+const diskTopics = new Set();
+const activeTree = { files: [], dirs: [] }; // 递归视图（断链守卫 / 台账登记断言用）
+for (const dEnt of fs.readdirSync(WIKI, { withFileTypes: true })) {
+  if (!isDirEntry(dEnt, WIKI)) continue;
+  const d = dEnt.name;
+  const p = path.join(WIKI, d);
+  if (d === 'drafts-archive') continue;
+  diskTopics.add(d);
+  // gitignore 豁免消费（p2-batch2 复核 P1-3）：gen 侧排除 ignored 本机件，verify 须同口径——
+  // 否则「gen 恒写 N、verify 恒数 N+1」门禁死锁且自愈指引（重跑 gen）无效
+  const isIgnored = (rel) => { const k = rel.replace(/\/$/, ''); return gitIgnoredArchive.has(`${d}/${k}`) || gitIgnoredArchive.has(`${d}/${k}/`); }; // 尾斜杠归一（复核 P2-a）
+  for (const fEnt of fs.readdirSync(p, { withFileTypes: true })) {
+    if (isFileEntry(fEnt, p) && !isIgnored(fEnt.name)) diskFiles.add(`${d}/${fEnt.name}`);
+  }
+  if (d !== '数据维护') {
+    for (const subEnt of fs.readdirSync(p, { withFileTypes: true })) {
+      if (!isDirEntry(subEnt, p)) continue;
+      const sp = path.join(p, subEnt.name);
+      for (const fEnt of fs.readdirSync(sp, { withFileTypes: true })) {
+        if (isFileEntry(fEnt, sp) && isKnowledgeDoc(fEnt.name) && !isIgnored(`${subEnt.name}/${fEnt.name}`)) diskFiles.add(`${d}/${subEnt.name}/${fEnt.name}`);
+      }
+    }
+  }
+  const sub = walkTree(p, d);
+  activeTree.files.push(...sub.files);
+  activeTree.dirs.push(...sub.dirs);
+}
+
+
+// drafts-archive 缺失：ENOENT 崩栈改明示失败（本脚本是门禁，协议目录被删应 exit 1 而非崩栈，2026-09-24）
+const ARCHIVE_DIR = path.join(WIKI, 'drafts-archive');
+let archiveCount = 0;
+if (fs.existsSync(ARCHIVE_DIR)) archiveCount = walkTree(ARCHIVE_DIR).files.filter((r) => !gitIgnoredArchive.has(`drafts-archive/${r}`)).length; // 集合键带 drafts-archive/ 前缀（复核 P2-b）
+else problems.push('wiki/drafts-archive/ 目录缺失（wiki 协议结构，模板自带）——归档一致性无从校验');
+
+// ---- 看板 DATA 解析 ----
+const html = fs.readFileSync(path.join(WIKI, '知识沉淀总览.html'), 'utf8');
+const m = html.match(/const DATA = (\{[\s\S]*?\n\});/);
+if (!m) {
+  console.error('❌ 看板 DATA 解析失败：知识沉淀总览.html 中找不到 `const DATA = {...}`');
+  process.exit(1);
+}
+// JSON.parse（p2-batch2）：DATA 由 gen-wiki-board 经 JSON.stringify 生成、必为合法 JSON——
+// eval 换 JSON.parse 消除门禁脚本对 repo 内文件执行任意 JS 的面；解析失败即 fail-loud 门禁失败
+let DATA;
+try {
+  DATA = JSON.parse(m[1]);
+} catch (e) {
+  console.error(`❌ 看板 DATA 不是合法 JSON（应跑 gen-wiki-board.mjs 重生成）：${e.message}`);
+  process.exit(1);
+}
+// 合计行比对（p2-batch2）：合计行有生成（fail-loud 锚点）无验证——手改/陈旧此前不可见
+{
+  const totalM = fs.readFileSync(path.join(WIKI, 'INDEX.md'), 'utf8').match(/合计：\*\*(\d+) 份\*\*知识文档，\*\*(\d+) 个主题\*\*/);
+  if (totalM) {
+    if (Number(totalM[1]) !== diskFiles.size || Number(totalM[2]) !== diskTopics.size) {
+      console.error(`❌ INDEX 合计行与磁盘不一致：合计 ${totalM[1]} 份/${totalM[2]} 主题 vs 磁盘 ${diskFiles.size} 份/${diskTopics.size} 主题——跑 gen-wiki-board.mjs 重生成`);
+      process.exit(1);
+    }
+  }
+}
+const boardFiles = new Set();
+for (const t of DATA.topics) for (const f of t.files) boardFiles.add(`${t.name}/${f.file}`);
+const boardTopics = new Set(DATA.topics.map((t) => t.name));
+
+// ---- INDEX 映射表解析 ----
+const indexFiles = new Set();
+const indexTopicCounts = new Map(); // 速览表 topic → 文件数
+for (const line of fs.readFileSync(path.join(WIKI, 'INDEX.md'), 'utf8').split(/\r?\n/)) {
+  const mm = line.match(/^\| ([^|]+) \| ([^|]+) \| wiki\/([^/]+)\/[^|]*\|$/);
+  if (mm) indexFiles.add(`${mm[3].trim()}/${mm[1].trim()}`);
+  // 速览行用途列容忍转义管道（p2-batch2 复核 P2-4：gen 侧转义写入后本解析须同款，否则该主题计数核对静默跳过）
+  const ov = line.match(/^\| ([^|]+) \| (\d+) \|((?:\\.|[^|])*)\|$/);
+  if (ov && ov[1].trim() !== '主题') indexTopicCounts.set(ov[1].trim().replace(/\\\|/g, '|'), Number(ov[2]));
+}
+
+const diff = (a, b) => [...a].filter((x) => !b.has(x));
+const eq = (a, b) => a.size === b.size && diff(a, b).length === 0;
+
+// ---- 1. 文件级三方比对 ----
+for (const [label, extra] of [
+  ['看板→磁盘', diff(boardFiles, diskFiles)],
+  ['磁盘→看板', diff(diskFiles, boardFiles)],
+  ['INDEX→磁盘', diff(indexFiles, diskFiles)],
+  ['磁盘→INDEX', diff(diskFiles, indexFiles)],
+]) {
+  if (extra.length) problems.push(`文件集合不一致（${label}）: ${extra.join('；')}`);
+}
+if (problems.length === 0) notes.push(`文件级三方一致：${diskFiles.size} 份`);
+
+// ---- 2. 幽灵目录：磁盘有主题目录但看板没有 ----
+const ghosts = diff(diskTopics, boardTopics);
+if (ghosts.length) problems.push(`磁盘存在看板未登记的主题目录: ${ghosts.join('、')}`);
+
+// ---- 3. 占位主题（看板有、磁盘 0 文件）——允许，仅提示 ----
+for (const t of DATA.topics) {
+  if (t.files.length === 0 && fs.existsSync(path.join(WIKI, t.name))) {
+    const real = fs.readdirSync(path.join(WIKI, t.name), { withFileTypes: true }).filter((e) => isFileEntry(e, path.join(WIKI, t.name))).length;
+    if (real > 0) problems.push(`看板主题「${t.name}」files 为空但磁盘有 ${real} 个文件`);
+    else notes.push(`占位主题「${t.name}」：0 文件（允许）`);
+  } else if (t.files.length === 0) {
+    problems.push(`看板主题「${t.name}」files 为空且磁盘无此目录`);
+  }
+}
+
+// ---- 4. INDEX 速览表文件数 vs 磁盘 ----
+for (const [topic, count] of indexTopicCounts) {
+  const actual = [...diskFiles].filter((f) => f.startsWith(topic + '/')).length;
+  if (!diskTopics.has(topic) && count > 0) problems.push(`INDEX 速览表主题「${topic}」(${count}) 磁盘无此目录`);
+  else if (actual !== count) problems.push(`INDEX 速览表「${topic}」标 ${count}，磁盘实际 ${actual}`);
+}
+
+// ---- 5. summary 统计字段 ----
+const s = DATA.summary;
+const sumChecks = [
+  ['summary.total', s.total, diskFiles.size],
+  ['summary.files', s.files, diskFiles.size],
+  ['summary.topics', s.topics, DATA.topics.length],
+  ['summary.archive', s.archive, archiveCount],
+];
+for (const [label, declared, actual] of sumChecks) {
+  if (declared !== actual) problems.push(`${label}=${declared}，实际 ${actual}`);
+}
+
+// ---- 6. 活跃文件禁 file:/// 绝对链（搬家断链防复发；递归覆盖子目录）----
+const badLinks = [];
+for (const f of activeTree.files) {
+  if (!/\.(md|html)$/i.test(f)) continue;
+  if (fs.readFileSync(path.join(WIKI, f), 'utf8').includes('file:///')) badLinks.push(f);
+}
+if (badLinks.length) problems.push(`以下活跃文件含 file:/// 绝对路径链接: ${badLinks.join('、')}`);
+
+// ---- 7. 数据维护台账登记：子目录（含批次目录）须在 wiki/数据维护/README.md 有登记行 ----
+// 「数据维护走 README 台账」是可选主题约定——目录不存在（新项目未建该主题）时整体跳过
+const maintLedger = path.join(WIKI, '数据维护', 'README.md');
+if (fs.existsSync(maintLedger)) {
+const maintReadme = fs.readFileSync(maintLedger, 'utf8');
+const maintReadmeFlat = maintReadme.replace(/\s+/g, ''); // README 标题写作「schema 变更」（带空格），故去空白再比对
+const maintDirs = activeTree.dirs.filter((d) => d.startsWith('数据维护/'));
+const unregistered = maintDirs
+  .map((d) => d.split('/').pop())
+  .filter((name) => !maintReadme.includes(name) && !maintReadmeFlat.includes(name.replace(/\s+/g, '')));
+if (unregistered.length) problems.push(`数据维护台账未登记（wiki/数据维护/README.md 无此行）：${unregistered.join('、')}`);
+else notes.push(`数据维护台账登记完整：${maintDirs.length} 个子目录（含批次目录）均有登记`);
+}
+
+// ---- 8. 看板链接可达性：DATA.dir（「打开目录」href）+ 静态相对 href 解析后须存在 ----
+const deadLinks = [];
+for (const t of DATA.topics) {
+  for (const f of t.files) {
+    const p = path.join(WIKI, f.dir); // 看板自身位于 wiki/，dir 为相对它解析
+    if (!fs.existsSync(p) || !fs.statSync(p).isDirectory()) deadLinks.push(`${t.name}/${f.file} → ${f.dir}`);
+  }
+}
+// 静态 href 扫描守的是「手工编辑看板」时加的链接（生成链接全在 JS 运行时拼，不落静态属性）——看板是 owned 内容，人为改动须可达
+for (const m2 of html.matchAll(/href="([^"]+)"/g)) {
+  const href = m2[1];
+  if (/^(https?:|mailto:|#)/i.test(href) || href.includes('${')) continue; // 外链 / 锚点 / 模板占位
+  if (!fs.existsSync(path.join(WIKI, href))) deadLinks.push(`静态 href → ${href}`);
+}
+if (deadLinks.length) problems.push(`看板链接指向不存在的路径（相对 wiki/ 解析）: ${deadLinks.join('；')}`);
+
+// ---- 5b. 未入库文件参与登记（warning 级，L43；2026-10-07）----
+// 缺口方向（实测 worktree 检出态复现后订正，勿与台账初记混淆）：
+//   · 「已入库但磁盘缺失」→ 本脚本既有判定已能拦（worktree 检出态删文件 → exit 1）
+//   · 「磁盘有但未入库，且被 INDEX/summary 登记」→ **本脚本拦不住**：口径只扫磁盘，
+// 未跟踪文件照样进 diskFiles 并与 INDEX 合计对齐 → 全绿。历史提交时点门 check-wiki-ledger.mjs
+//     （2026-10-21 止血批删除）当时也只判「有 wiki/ 暂存变更即放行」，不校验入库状态 →
+//     漏提交要等别人 clone 后才炸。
+// 取 warning 不取 problems：漏提交本身不破坏本机三方一致性，硬拦会在正常开发中途
+// （新文件先落地、登记后提交）误报。提示即可，commit 前的人工确认负责拦住。
+const untrackedRegistered = (() => {
+  let out;
+  try {
+    out = execSync('git -c core.quotepath=false ls-files --others --exclude-standard -- wiki',
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch {
+    return []; // 非 git 仓 / git 不可用：跳过（与 gitIgnoredArchive 降级口径一致）
+  }
+  return out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean)
+    .filter((p) => /\.(md|html)$/i.test(p) && !/\.visual-check\./i.test(p));
+})();
+if (untrackedRegistered.length) {
+  notes.push(`⚠️ ${untrackedRegistered.length} 份 wiki 文件未入库但已参与登记校验：`
+    + `${untrackedRegistered.slice(0, 5).join('、')}${untrackedRegistered.length > 5 ? ' 等' : ''}`
+    + '——提交前须 git add，否则别的 clone 检出后一致性校验必红');
+}
+
+// ---- 9. 叙事计数声明对账（2026-10-11 C5 终局方案 A：与 gen-narrative-claims.mjs 共用声明形态表）----
+// 门=必响 / 生成器=写即对，双消费者单源（沿 gen-effective-policy「生成 + --check」惯例）——
+// 形态表、单源取数、扫描面全部在本模块，此处只消费结果。历史叙述请写成不含现态声明形态的措辞。
+{
+  const { claims, mismatches } = checkNarrativeClaims(process.cwd());
+  if (mismatches.length) {
+    for (const mm of mismatches) problems.push(`叙事计数声明漂移：${mm.file}「${mm.label}」——跑 node .agents/scripts/gen-narrative-claims.mjs 改写或改为非现态措辞`);
+  } else {
+    notes.push(`叙事计数声明对账：${claims} 项现态声明对单源一致`);
+  }
+}
+
+// ---- 输出 ----
+for (const n of notes) console.log('ℹ️  ' + n);
+if (problems.length) {
+  console.error('\n❌ wiki 一致性校验失败：');
+  for (const p of problems) console.error('  - ' + p);
+  process.exit(1);
+}
+console.log(`✅ wiki 三方一致：文件 ${diskFiles.size} 份 / 主题 ${DATA.topics.length} 个（含占位）/ 归档 ${archiveCount} 份`);