@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/check-sop-consistency.mjs

@@ -0,0 +1,431 @@
+#!/usr/bin/env node
+/**
+ * SOP / 判据**一致性门禁**（P4，2026-09-17）。
+ *
+ * 为什么需要它：今天两次事故都不是"写错逻辑"，而是**同一件事在两处各写了一份**：
+ *   ① 引擎上传箱唛时勾 `产品箱唛`（写死在 orchestrator 的字段映射里），而写入守卫的白名单
+ *      来自注册表 `fields` —— 注册表没声明该字段 ⇒ 合法写入被守卫拒了（用户发现"附件传了但勾没打"）；
+ *   ② 失败分类在两处（orchestrator._is_network_error 与 flow_failure 关键词表）⇒ 同一段错误文本
+ *      两个层给出不同结论。
+ * 判据散落本身可以接受（分层是有意为之），但**副本之间不能悄悄漂移**。本门禁就是那道锁：
+ * 任何一处漂移 ⇒ 退出码 1。
+ *
+ * 检查项：
+ *   C1 引擎实际写入的字段 ⊇ 注册表声明（守卫白名单）—— 防"合法写入被守卫拒"
+ *   C2 提示词里提到的相位 ∈ 引擎实际产出的相位 —— 防"提示词教角色做不存在的相位"
+ *   C3 失败分类金样例（固定错误文本 → 期望分类）—— 防分类规则被无意改动
+ *   C4 每流程提示词模板存在，且占位符都在渲染变量表里 —— 防生产里残留 `{{…}}`
+ *   C5 引擎步骤集合 vs SKILL 记录的步骤（不一致只告警，供人工复核）
+ *
+ * 用法：node scripts/check-sop-consistency.mjs [--json]   退出码 0=一致 / 1=有漂移
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, resolve, dirname } from 'node:path'
+import { loadRegistryDoc, resolveFlowId } from './lib/registry.mjs'
+import { fileURLToPath } from 'node:url'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+export const REPO = resolve(here, '..')
+const SCRIPTS = join(REPO, 'scripts')
+const PY = (process.env.ARGENT_PY || process.env.ARGENT_PYTHON || `${process.env.DSH_HOME || `${process.env.HOME}/.dsh`}/argent/venv/bin/python3`)
+
+const read = (p) => readFileSync(p, 'utf8')
+const uniq = (a) => [...new Set(a)]
+
+/** 域内字段键（引擎用它们映射"逻辑角色 → 真列名"）。 */
+export const DOMAIN_KEYS = ['status', 'ready', 'store', 'step', 'note', 'shipment',
+  'labelFile', 'boxLabelFile', 'labelCheck', 'boxCheck', 'label_attach', 'box_attach',
+  'label_check', 'box_check']
+
+/** C1 用：从 orchestrator 源码里取"引擎会写入的字段名"（映射字面量）。 */
+export function engineFields(orchestratorSrc) {
+  // 只取**中文列名**：字段映射的值都是中文列名，而 `"status": "success"` 这类是结果枚举，
+  // 混进来会淹掉真信号（第一版就是这样，报了 9 个假阳性）。
+  // 另排除 `store`：引擎只**读**店名列（用途是匹配紫鸟店铺），不写它。
+  const out = new Set()
+  const keys = DOMAIN_KEYS.filter((k) => k !== 'store')
+  const re = new RegExp(`"(${keys.join('|')})"\\s*:\\s*"([^"]*[\\u4e00-\\u9fff][^"]*)"`, 'g')
+  for (const m of orchestratorSrc.matchAll(re)) out.add(m[2])
+  return out
+}
+
+/** C1 用：注册表里声明的字段名（= 写入守卫白名单的来源）。 */
+export function declaredFields(registryDoc) {
+  const out = new Set()
+  for (const spec of Object.values(registryDoc.flows || {})) {
+    for (const v of Object.values((spec.source || {}).variants || {})) {
+      for (const val of Object.values(v.fields || {})) if (typeof val === 'string' && val) out.add(val)
+    }
+    for (const val of Object.values((spec.source || {}).fields || {})) if (typeof val === 'string' && val) out.add(val)
+  }
+  out.add('货件号')   // 票号列：脚本与守卫都按名字用
+  return out
+}
+
+/** 跑一个 Python 探针并取回它打印的 JSON（stdout 允许有噪声：优先取最后一个 `__JSON__` 标记行）。
+ *  **拿不到就返回 `{__error}`**，由调用方决定"响亮"还是"跳过"——⛔ 不允许静默当成空结果。 */
+export function runPyJson(file, args = []) {
+  try {
+    const out = execFileSync(PY, [file, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+    const lines = out.split('\n').filter(Boolean)
+    const marked = lines.filter((l) => l.startsWith('__JSON__')).pop()
+    const raw = marked ? marked.slice('__JSON__'.length) : lines.pop() || ''
+    return JSON.parse(raw)
+  } catch (e) {
+    return { __error: (String(e.message || e) + ' | stderr: ' + String(e.stderr || '').trim().split('\n').pop()).slice(0, 300) }
+  }
+}
+
+/** C2 用：**问引擎**它实际产出哪些相位（数据源 = 引擎自己的声明，见下）。
+ *  `flow_source.py --list-phases` 是既有 CLI 入口（与 `--list-sources` 同规矩），
+ *  它转达的是 `flow_sources/common.py#PHASES`。⛔ 不要在门禁里解析引擎源码文本。 */
+export function enginePhasesProbe() {
+  return runPyJson(join(SCRIPTS, 'flow_source.py'), ['--list-phases'])
+}
+
+/** C2 用：引擎实际产出的相位。
+ *
+ *  **为什么是"问引擎"而不是解析源码**（2026-10-08 修根因）：
+ *  第一版只读 `scripts/flow_source.py` 的文本，用正则捞 `_phase'?]? = '…'`；而**相位赋值**
+ *  在 P4（2026-09-29）已搬进 `scripts/flow_sources/common.py`（`apply_pick()`）⇒ 那个文件里
+ *  `_phase` 出现 **0 次** ⇒ 本函数恒返回**空集合** ⇒ C2 退化成"空集 ⊆ 任何集合"的
+ *  **静默空转**（门禁输出里 `引擎产出（）`）：今天不红只是因为历史提示词目录已空，
+ *  一旦扫描面扩到 `verticals/<id>/prompts/`，真实提示词里的 identify/execute/await_release/
+ *  needs_human 会**立刻变成 4 个假红**。更糟的是它第二行还**写死**了一份相位名单 ——
+ *  那是"判据副本"本身（引擎改名它照样通过）。
+ *  ⇒ 现在只有一个真源：引擎的 `PHASES`（`apply_pick()` 打 `_phase` 时只从它取），
+ *  经既有 CLI 转达；本函数只负责"问 + 校验形状"。`probe` 可注入（回归夹具用）。
+ *  ⛔ 空集/读不到 ⇒ **抛错**（由 C2 判红），绝不返回空集让判据静默失效。 */
+export function producedPhases(probe = enginePhasesProbe) {
+  const raw = probe()
+  if (raw && raw.__error) throw new Error(`读不到引擎相位（--list-phases 执行失败）：${raw.__error}`)
+  const list = Array.isArray(raw) ? raw : (raw || {}).phases
+  if (!Array.isArray(list) || !list.length) throw new Error(`--list-phases 没给出相位：${JSON.stringify(raw).slice(0, 160)}`)
+  return new Set(list.map((x) => String(x)))
+}
+
+/** C2 的**核心相位**（金丝雀锚点）：这几个相位一旦从引擎侧消失，C2 必须先响亮、再谈其它 ——
+ *  否则"相位集合"塌成小集合时门禁会跟着一起塌（同第一版的空集空转）。 */
+export const CORE_PHASES = ['identify', 'execute', 'await_release', 'needs_human']
+
+/** C2 判据核（**纯函数**，便于夹具/金丝雀两向回归）：提示词声明的相位 ∉ 引擎产出 ⇒ 逐条列出。
+ *  `templates` = `[{file, src}]`；`produced` = 相位集合（Set 或数组）。 */
+export function promptPhaseBogus(produced, templates) {
+  const set = produced instanceof Set ? produced : new Set(produced || [])
+  const bogus = new Set()
+  for (const t of templates) {
+    for (const ph of mentionedPhases(t.src)) {
+      if (!set.has(ph) && !KNOWN_EVENTS.has(ph)) bogus.add(`${ph}@${t.file}`)
+    }
+  }
+  return [...bogus]
+}
+
+/** C2 用：台账事件名（提示词里合法出现，但**不是**相位）—— 用于把 C2 的误报排除掉。 */
+export const KNOWN_EVENTS = new Set(['done', 'failed', 'blocked', 'planned', 'dispatched', 'wake',
+  'retry', 'failed_ack', 'phase', 'policy_apply', 'policy_new'])
+
+/** C2 用：提示词里**声明为相位**的清单项（形如 `- \`identify\` —— …`）。
+ *  只认这种"清单式声明"，不去抓正文里出现过的任何小写词 —— 第一版用白名单正则，
+ *  结果永远抓不到"引擎不产出的相位"（因为它只匹配已知名字），等于没检查。 */
+export function mentionedPhases(promptSrc) {
+  const out = new Set()
+  for (const m of promptSrc.matchAll(/^\s*-\s*`([a-z_]{3,24})`\s*(?:——|—|-)/gm)) out.add(m[1])
+  return out
+}
+
+/** C2 用：历史提示词目录（`scripts/flow-prompts/`）里的模板文件名。
+ *
+ *  **为什么容忍缺失**（2026-10-08 修）：该目录是 **P2a 之前**的提示词位置 —— commit `48016b8`
+ *  已把 8 份模板全部迁到 `verticals/<id>/prompts/`，注册表 `trigger.promptTemplate` 是**唯一出处**。
+ *  迁移把 `scripts/flow-prompts/` 下的跟踪文件全删了 ⇒ 该目录**没有任何被跟踪的内容**，
+ *  而 **git 不跟踪空目录** ⇒ `git archive` 与 `git clone` **都不会产生它**。
+ *  于是真·新克隆上 `readdirSync` 抛 `ENOENT` ⇒ 本条用例判红（`run-tests.sh` 的"镜像空目录"
+ *  只是把目录补回来规避假红，**不等于**用例已健壮）。
+ *  目录不存在 = 「历史位置已废弃」，**不是判据漂移** ⇒ 按空集合处理。
+ *
+ *  ⛔ 只吞 `ENOENT`：其它 IO 错误（EACCES 等）照旧抛出，不假装"目录是空的"。
+ *  ⛔ **判据不放宽**：目录**存在**时逐份模板的断言与从前**完全一致**（下方 for 循环原样）。 */
+export function legacyPromptFiles(dir = join(REPO, 'scripts', 'flow-prompts')) {
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith('.md'))
+  } catch (e) {
+    if (e.code === 'ENOENT') return []
+    throw e
+  }
+}
+
+/** C4 用：模板占位符集合。 */
+export const placeholders = (src) => uniq([...src.matchAll(/\{\{(\w+)\}\}/g)].map((m) => m[1]))
+
+/** C4 用：wake 脚本提供的渲染变量。 */
+export function renderVars(wakeSrc) {
+  const block = wakeSrc.slice(wakeSrc.indexOf('const vars = {'), wakeSrc.indexOf('const PROMPT ='))
+  return new Set([...block.matchAll(/^\s{2}(\w+):/gm)].map((m) => m[1]))
+}
+
+/** C3 金样例：固定错误文本 → 期望分类（分类器是判据副本，必须锁住行为）。 */
+export const GOLDEN = [
+  ['失败：页面导航失败: Page.goto: Target page, context or browser has been closed', 'retryable'],
+  ['超时 timeout waiting for selector', 'retryable'],
+  ['预约失败：货件状态为「Reserva cancelada」且产品标签/箱唛均未上传，流程未完成', 'needs_agent'],
+  ['缺 SKU：运营未填', 'needs_human'],
+  ['紫鸟未授权该店铺环境', 'needs_human'],
+]
+
+export function classify(text) {
+  const out = execFileSync(PY, [join(REPO, 'scripts', 'flow_failure.py'), '--error', text, '--attempt', '1', '--json'],
+    { encoding: 'utf8' })
+  return JSON.parse(out).kind
+}
+
+
+/** C7 用（纯函数，便于回归）：检查"裁定沉淀"两边是否互相指得上。
+ *  规则：① 每条政策必须有 sourceCase 与 authorizer（可追溯红线）；
+ *       ② whyRef 形如 `<file>#<anchor>` 时，文件要存在且含该锚点；
+ *       ③ 技能条目里引用的 `政策 \`pol-…\`` 必须真实存在于政策库。 */
+export function learnLinkProblems(policies = [], { readFile = () => null, exists = () => false } = {}) {
+  const problems = []
+  const ids = new Set(policies.map((p) => p.id))
+  for (const p of policies) {
+    if (!p.sourceCase) problems.push(`政策 ${p.id} 缺 sourceCase（无法追溯来源案例）`)
+    if (!p.authorizer) problems.push(`政策 ${p.id} 缺 authorizer（不知道谁授权的）`)
+    const ref = String(p.whyRef || '')
+    if (ref.includes('#')) {
+      const [file, anchor] = ref.split('#')
+      if (!exists(file)) problems.push(`政策 ${p.id} 的 whyRef 指向不存在的文件：${file}`)
+      else {
+        const text = readFile(file) || ''
+        if (!text.includes(anchor)) problems.push(`政策 ${p.id} 的 whyRef 锚点 ${anchor} 在 ${file} 里找不到`)
+      }
+    }
+  }
+  return problems
+}
+
+/** C7 用：扫描技能文档里对政策 id 的引用。 */
+export function citedPolicyIds(markdown) {
+  return [...String(markdown).matchAll(/政策\s*`(pol-[0-9a-z]+)`/g)].map((m) => m[1])
+}
+
+export function run() {
+  const checks = []
+  const add = (id, level, title, detail = '') => checks.push({ id, level, title, detail })
+
+  // P2a：注册表经加载器合并（base + 业务线）；别直读 base（会漏业务线流程）
+  const reg = loadRegistryDoc()
+  const orch = read(join(REPO, 'scripts', 'orchestrator.py'))
+  const wake = read(join(REPO, 'scripts', 'flow-trigger-wake.mjs'))
+
+  // C1 守卫白名单覆盖引擎写入字段
+  const decl = declaredFields(reg)
+  const eng = engineFields(orch)
+  const missing = [...eng].filter((f) => !decl.has(f))
+  if (missing.length) {
+    add('C1', 'fail', `引擎写入字段未在注册表声明：${missing.join('、')}`,
+      '守卫白名单来自注册表 ⇒ 这类写入会被静默拒绝（2026-09-17 产品箱唛就是如此）。修：把字段加进 flows.<id>.source.variants.<v>.fields')
+  } else {
+    add('C1', 'ok', `引擎写入的 ${eng.size} 个字段都在注册表声明内（守卫不会误拒）`)
+  }
+
+  // C2 提示词相位 ⊆ 引擎产出相位
+  // 数据源 = **引擎自己的声明**（`flow_sources/common.py#PHASES`），经既有 CLI 转达；
+  // ⛔ 不再解析 `flow_source.py` 的源码文本（P4 搬走赋值后那次解析恒得空集 ⇒ C2 静默空转）。
+  let produced = new Set()
+  let producedErr = ''
+  try { produced = producedPhases() } catch (e) { producedErr = String(e.message || e) }
+  const coreMissing = CORE_PHASES.filter((p) => !produced.has(p))
+  // 历史目录可能**根本不存在**（git 不跟踪空目录 ⇒ 新克隆/裸检出没有它）—— 那不判红，见 legacyPromptFiles。
+  const LEGACY_PROMPTS = join(REPO, 'scripts', 'flow-prompts')
+  const prompts = legacyPromptFiles(LEGACY_PROMPTS)
+  const templates = prompts.map((f) => ({ file: f, src: read(join(LEGACY_PROMPTS, f)) }))
+  const bogus = promptPhaseBogus(produced, templates)
+  if (producedErr || !produced.size || coreMissing.length) {
+    // 数据源断了 / 相位集合塌了 ⇒ **响亮判红**：此时 bogus 全是假红，不能拿它当结论
+    add('C2', 'fail', `读不到引擎产出的相位（数据源断了）：${producedErr || `集合=${[...produced].sort().join('/') || '（空）'}`
+      + (coreMissing.length ? `，缺核心相位 ${coreMissing.join('、')}` : '')}`,
+    'C2 的判据是「提示词相位 ⊆ 引擎产出」⇒ 源侧塌成空集/小集合时它会**静默假绿**。'
+    + '修：让 `flow_source.py --list-phases`（唯一真源 flow_sources/common.py#PHASES）能正常输出，'
+    + '并确认 apply_pick() 仍在打这些相位')
+  } else if (bogus.length) {
+    add('C2', 'fail', `提示词提到引擎不会产出的相位：${bogus.join('、')}`, '改提示词或改引擎，二选一')
+  }
+  // 「扫了几份」写在 title 里（ok 的 detail 不打印）—— 免得 C2 空转时被误读成"8 份模板都验过了"
+  else add('C2', 'ok', `提示词相位集合 ⊆ 引擎产出（${[...produced].sort().join('/')}）` + (prompts.length
+    ? `；已扫历史目录 ${prompts.length} 份模板`
+    : '；`scripts/flow-prompts/` 不在（P2a 已迁到 verticals/<id>/prompts/）⇒ 按空集合通过，判据未放宽'))
+
+  // C3 分类金样例
+  const bad = []
+  for (const [text, want] of GOLDEN) {
+    let got = '（异常）'
+    try { got = classify(text) } catch (e) { got = '（执行失败）' }
+    if (got !== want) bad.push(`「${text.slice(0, 26)}…」期望 ${want} 实得 ${got}`)
+  }
+  if (bad.length) add('C3', 'fail', `失败分类与金样例不一致：${bad.join('；')}`, '分类是判据副本（政策/重跑/唤醒都依赖它）⇒ 改动必须同步更新金样例并说明理由')
+  else add('C3', 'ok', `失败分类金样例 ${GOLDEN.length} 条全部一致`)
+
+  // C4 模板存在 + 占位符有定义
+  const vars = renderVars(wake)
+  const probs = []
+  for (const [fid, spec] of Object.entries(reg.flows || {})) {
+    // 模板路径：注册表可声明 trigger.promptTemplate，否则按 flow_config 的缺省推导规则取 flow-prompts/<id>.md
+    const rel = (spec.trigger || {}).promptTemplate || `flow-prompts/${fid}.md`
+    // P2a：路径解析与 flow_config._resolve_prompt_path 同规矩 ——
+    // 业务线声明的路径是**仓库根相对**（verticals/<id>/prompts/…），历史缺省是 scripts/ 相对。
+    const tpl = existsSync(join(REPO, rel)) ? join(REPO, rel) : join(REPO, 'scripts', rel)
+    if (!existsSync(tpl)) { probs.push(`${fid}: 模板缺失`); continue }
+    for (const ph of placeholders(read(tpl))) if (!vars.has(ph)) probs.push(`${fid}: {{${ph}}} 无定义`)
+    const ftpl = tpl.replace(/\.md$/, '.failure.md')
+    if (!existsSync(ftpl)) probs.push(`${fid}: 失败模板缺失`)
+  }
+  if (probs.length) add('C4', 'fail', `提示词模板问题：${probs.join('；')}`, '占位符必须都能被 flow-trigger-wake.mjs 渲染，否则生产里会残留 {{…}}')
+  else add('C4', 'ok', `全部流程的派发/失败模板存在，占位符（${vars.size} 个变量）都有定义`)
+
+  // C5 引擎步骤 vs SKILL（不一致只告警）
+  const engSteps = uniq([...orch.matchAll(/步骤\s?(\d+)/g)].map((m) => Number(m[1])).filter((n) => n > 0)).sort((a, b) => a - b)
+  const skill = join(REPO, 'skills', 'ml-fulfillment-sop', 'SKILL.md')
+  const skillSteps = existsSync(skill)
+    ? uniq([...read(skill).matchAll(/步骤\s?(\d+)/g)].map((m) => Number(m[1]))).sort((a, b) => a - b) : []
+  const onlyEng = engSteps.filter((n) => !skillSteps.includes(n))
+  if (!skillSteps.length) add('C5', 'warn', 'SKILL 里没找到步骤编号（无法比对）', 'skills/ml-fulfillment-sop/SKILL.md')
+  else if (onlyEng.length) add('C5', 'warn', `SKILL 缺步骤：${onlyEng.join('、')}（引擎有 ${engSteps.join('/')}）`, '把新步骤补进 SKILL，或确认为内部子步骤')
+  else add('C5', 'ok', `SKILL 步骤覆盖引擎步骤（${engSteps.join('/')}）`)
+
+
+  // C6 判据副本：引擎/分类器的**生效规则**必须与注册表 `failureClasses` 逐字一致（P3）
+  const fc = reg.failureClasses || {}
+  // 不允许"静默跳过"：拿不到就带上真实错误（Python 找不到 / 导入失败 / stdout 有噪声都要能看见）
+  // 探针实现 = 模块级 `runPyJson()`（与 C2 的 `--list-phases` 同一份实现）
+  const engRules = runPyJson(join(REPO, 'scripts', '_engine_rules_probe.py'))
+  const wantKeys = (fc.engineNetwork || {}).patterns || []
+  const wantTypes = (fc.engineNetwork || {}).errTypes || []
+  if (engRules && engRules.__error) add('C6', 'warn', `读不到引擎生效规则：${engRules.__error}`, `PY=${PY}（导入 orchestrator 失败时跳过）`)
+  else if (!engRules) add('C6', 'warn', '读不到引擎生效规则（空输出）', `PY=${PY}`)
+  else if (JSON.stringify(engRules[0]) !== JSON.stringify(wantKeys) || JSON.stringify(engRules[1]) !== JSON.stringify(wantTypes)) {
+    add('C6', 'fail', '引擎网络口径与注册表不一致',
+      `引擎=${JSON.stringify(engRules)}｜注册表=${JSON.stringify([wantKeys, wantTypes])} ⇒ 改一处忘另一处正是今天事故的形态`)
+  } else add('C6', 'ok', `引擎网络口径与注册表一致（${wantKeys.length} 个关键词）`)
+
+  const ffPats = runPyJson(join(REPO, 'scripts', 'flow_failure.py'), ['--patterns'])
+  if (ffPats && ffPats.__error) add('C6b', 'warn', `读不到分类器生效规则：${ffPats.__error}`, `PY=${PY}`)
+  else if (!ffPats) add('C6b', 'warn', '读不到分类器生效规则（空输出）', `PY=${PY}`)
+  else {
+    const bad = []
+    if (JSON.stringify(ffPats.retryable) !== JSON.stringify((fc.flowRetryable || {}).patterns || [])) bad.push('retryable')
+    if (JSON.stringify(ffPats.needs_human) !== JSON.stringify((fc.needsHuman || {}).patterns || [])) bad.push('needs_human')
+    // 2026-10-10（仓容满批）**判据收紧**：分类器新增 `capacityFull` 组（排在 needs_human 之前，
+    // 否则仓容满的文案会被 `需运营` 吞进 needs_human，就再也分不出是哪条链）。既然注册表是
+    // 唯一权威，就必须逐字比 —— 只比两个老组等于给新组留了一个"代码里悄悄另写一份"的口子。
+    // 同批把既有的 `pageFlaky` 也纳入（此前**从未**被比过；现比值与注册表逐字一致，属收紧不属放松）。
+    if (JSON.stringify(ffPats.capacityFull) !== JSON.stringify((fc.capacityFull || {}).patterns || [])) bad.push('capacityFull')
+    if (JSON.stringify(ffPats.pageFlaky) !== JSON.stringify((fc.pageFlaky || {}).patterns || [])) bad.push('pageFlaky')
+    if (bad.length) add('C6b', 'fail', `分类器生效规则与注册表不一致：${bad.join('、')}`, '分类器已改为注册表优先 ⇒ 不一致说明代码里另有内置改动未回写注册表')
+    else add('C6b', 'ok', '分类器生效规则与注册表逐字一致（capacityFull / pageFlaky / retryable / needs_human）')
+  }
+
+
+  // C7 裁定沉淀闭环：政策 ↔ 技能条目互相指得上（P6）
+  const dataDir = resolveDataDir({ env: process.env }).dir   // 内核三级链（唯一判据）
+  const polFile = join(dataDir, 'flow-policy.jsonl')
+  let policies = []
+  if (existsSync(polFile)) {
+    policies = read(polFile).split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l) } catch { return null } }).filter(Boolean)
+  }
+  const readAny = (f) => { try { return readFileSync(f, 'utf8') } catch { return null } }
+  const existsAny = (f) => { try { return existsSync(f) } catch { return false } }
+  const linkProblems = learnLinkProblems(policies, { readFile: readAny, exists: existsAny })
+  // 技能文档里引用的政策 id 必须存在
+  const skillDirs = join(REPO, 'skills')
+  if (existsSync(skillDirs)) {
+    for (const d of readdirSync(skillDirs)) {
+      const f = join(skillDirs, d, 'references', 'pitfalls.md')
+      if (!existsSync(f)) continue
+      for (const id of citedPolicyIds(read(f))) {
+        if (policies.length && !policies.some((p) => p.id === id)) linkProblems.push(`${d}/references/pitfalls.md 引用了不存在的政策 ${id}`)
+      }
+    }
+  }
+  if (linkProblems.length) {
+    add('C7', 'fail', `裁定沉淀的两边对不上（${linkProblems.length} 处）`, linkProblems.slice(0, 3).join('；'))
+  } else {
+    add('C7', 'ok', `政策库 ${policies.length} 条：追溯字段齐、与技能条目的交叉引用可解析`)
+  }
+
+
+  // C8 技能里的表 id 必须是注册表声明过的（2026-09-17：xzh 技能曾指向已作废的旧表 ⇒ 判据漂移）
+  // 2026-09-20（迭代1-步骤4）：表 id 可能是**env 解析出来的**（`baseEnv/tableEnv`），
+  // 只看字面量会把"已声明但走 env"的表误判成未声明 ⇒ 改为"字面量 ∪ 解析结果"。
+  const declaredTables = new Set()
+  const collectFrom = (src) => {
+    if (!src || typeof src !== 'object') return
+    for (const k of ['table', 'base']) {
+      const v = src[k]
+      if (typeof v === 'string' && v) declaredTables.add(v)
+    }
+    for (const v of Object.values(src.variants || {})) collectFrom(v)
+  }
+  for (const spec of Object.values(reg.flows || {})) collectFrom(spec.source)
+  // 解析后的 id（best-effort：缺部署 env 时用 --lax 拿字面量，不因缺凭据让门禁假红）
+  try {
+    const raw = execFileSync(PY, [join(SCRIPTS, 'flow_config.py'), '--list', '--lax'], { encoding: 'utf8' })
+    for (const m of raw.matchAll(/\btbl[A-Za-z0-9]{10,}\b/g)) declaredTables.add(m[0])
+  } catch { /* 解析失败不致命：字面量集合仍然有效 */ }
+  // 另：解析成功时把 base/table 一并收集（--json 逐流程）
+  for (const fid of Object.keys(reg.flows || {})) {
+    try {
+      const cfg = JSON.parse(execFileSync(PY, [join(SCRIPTS, 'flow_config.py'), '--flow', fid, '--json'],
+        { encoding: 'utf8' }))
+      const t = (cfg.source || {}).table
+      if (typeof t === 'string' && t) declaredTables.add(t)
+    } catch { /* 缺 env 的流程跳过 */ }
+  }
+  const skillsRoot = join(REPO, 'skills')
+  const strayTables = []
+  if (existsSync(skillsRoot)) {
+    for (const d of readdirSync(skillsRoot)) {
+      const dir = join(skillsRoot, d)
+      let files = []
+      try { files = readdirSync(dir, { withFileTypes: true }) } catch { continue }
+      for (const f of files) {
+        const fp = f.isDirectory() ? join(dir, f.name, 'pitfalls.md') : join(dir, f.name)
+        if (!f.isDirectory() && !f.name.endsWith('.md')) continue
+        if (!existsSync(fp)) continue
+        for (const line of read(fp).split('\n')) {
+          if (/作废|历史|旧|deprecated|retired/i.test(line)) continue
+          for (const m of line.matchAll(/tbl[A-Za-z0-9]{10,}/g)) {
+            if (!declaredTables.has(m[0])) strayTables.push(`${fp.split('/skills/')[1]}: ${m[0]}`)
+          }
+        }
+      }
+    }
+  }
+  if (strayTables.length) {
+    add('C8', 'fail', `技能里引用了未在注册表声明的表：${[...new Set(strayTables)].join('、')}`,
+      '技能是角色的判读依据 ⇒ 指向已废弃的表会让角色照旧口径干活；改技能或改注册表')
+  } else {
+    add('C8', 'ok', `技能引用的表都在注册表声明内（${declaredTables.size} 张）`)
+  }
+
+  return checks
+}
+
+const isMain = isDirectRun(import.meta.url)
+if (isMain) {
+  const checks = run()
+  const fails = checks.filter((c) => c.level === 'fail')
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify({ checks, summary: { fail: fails.length, ok: checks.filter((c) => c.level === 'ok').length } }, null, 2))
+  } else {
+    const icon = { ok: '✅', warn: '⚠️', fail: '❌' }
+    for (const c of checks) {
+      console.log(`  ${icon[c.level]} [${c.id}] ${c.title}`)
+      if (c.level !== 'ok' && c.detail) console.log(`      ↳ ${c.detail}`)
+    }
+    console.log(fails.length ? `\n❌ 一致性门禁未通过（${fails.length} 项）` : '\n✅ 一致性门禁通过（判据副本未漂移）')
+  }
+  process.exit(fails.length ? 1 : 0)
+}