add-coder 0.3.33 → 0.3.35

package/templates/core/scripts/mcp-server/tools/review.ts

@@ -8,6 +8,8 @@ import { prisma } from "../shared/prisma.js"
 import type { PlanRow, ReviewRow } from "../shared/db-types.js"
 import { PlanRowSchema, ReviewRowSchema, validatedDelegate } from "../shared/db-types.js"
 import { getRuntimeContext } from "../shared/env.js"
+// 审查文档命名识别（纯函数，见 shared/review-files.ts：两种命名并存，规则需被用例钉住）
+import { pickReviewFiles, derivePlanNameFromReviewFile } from "../shared/review-files.js"
 import { assertPathInRuntimeScope } from "../shared/runtime-context.js"
 
 const db = {
@@ -52,18 +54,19 @@ export function registerReviewTools(server: ToolRegistrar) {
       const reviewsDir = join(PROJECT_ROOT, MAGIC_DIR, "reviews")
       if (!existsSync(reviewsDir)) return errorResponse(`reviews 目录不存在: ${reviewsDir}`)
       const allFiles = await readdirRecursive(reviewsDir)
-      const reviewFiles = allFiles.filter(f => f.endsWith(".md") && f.includes("-review-"))
+      /*
+       * 审查文档命名兼容（2026-09-14 放宽）：
+       * 仓库里同时存在两种形态 —— `{planPrefix}-review-v1.md`（历史）与
+       * `{planPrefix}-plan-v1-review.md`（create_hitl 的占位路径落点，也是 review 文档的自然命名）。
+       * 旧匹配要求包含 `-review-`（review 后必须跟连字符），会把后者整类漏掉。
+       */
+      const reviewFiles = pickReviewFiles(allFiles)
       const results: string[] = []
       let count = 0
 
       for (const rf of reviewFiles) {
         const fullPath = join(reviewsDir, rf)
-        // 从文件名推导 planName
-        // 格式: {plan-name}-review-v1.md 或 {plan-name}-review-implementation.md
-        const derivedPlan = basename(rf, ".md")
-          .replace(/-review-.*$/, "")
-          .replace(/-implementation.*$/, "")
-          .replace(/-runtime.*$/, "")
+        const derivedPlan = derivePlanNameFromReviewFile(rf)
         // [2026-08-09 修复] 过滤方向颠倒：derivedPlan 是前缀，pn 是完整 planName（{prefix}-plan-v{n}），
         // 应为 pn.includes(derivedPlan)；原实现 derivedPlan.includes(pn) 永远 false → 传入 planName 时全部跳过
         if (pn && !pn.includes(derivedPlan)) continue

package/templates/core/scripts/mcp-server.ts

@@ -12,6 +12,40 @@ import {
 } from "./mcp-server/shared/plan-lifecycle-subscriber.js"
 import { PlanRoundSubscriber } from "./mcp-server/shared/plan-round-subscriber.js"
 import { queryPlanRounds, type PlanRoundReadClient } from "./mcp-server/shared/plan-round-store.js"
+import { PROJECT_ROOT, MAGIC_DIR } from "./mcp-server/shared/env.js"
+import { clearRestartRequiredMarker } from "./mcp-server/shared/runtime-freshness.js"
+
+/**
+ * 启动后清掉本 adapter 的"需重启"标记（2026-09-14）：
+ * 该标记的语义是"运行中的 server 早于产物"，本进程刚启动 → 必然晚于现有产物，
+ * 旧标记已失效。不清掉会留下**过期告警**（实测：重启后标记仍在，谁读到都以为还得重启）。
+ */
+function clearOwnStaleMarker(): void {
+  try {
+    clearRestartRequiredMarker(MAGIC_DIR, PROJECT_ROOT)
+  } catch {
+    /* fail-open：标记清理失败不影响启动 */
+  }
+}
+
+/**
+ * 孤儿自退（2026-09-14）：IDE/app 退出时通常只杀直接子进程（`npx`），
+ * `npm exec → sh -c → tsx → node` 这几代会被 reparent 到 systemd 继续存活
+ * （实测同一逻辑 server 5 个进程，旧实例的 server 在 app 重启后仍活 20+ 分钟；
+ * `.codex` 与 `.qoder` 上都反复出现）。
+ * 记录启动时的父 pid，一旦被 reparent 即视为启动者已死 → 自杀退出（stdio 对端本就没了）。
+ */
+function watchLauncher(): void {
+  const launcherPid = process.ppid
+  const timer = setInterval(() => {
+    if (process.ppid !== launcherPid) {
+      console.error(`[ADD-MCP] 启动者已退出（ppid ${launcherPid} → ${process.ppid}），孤儿自退`)
+      clearInterval(timer)
+      process.exit(0)
+    }
+  }, 15_000)
+  timer.unref?.()
+}
 
 async function main() {
   const server = new McpServer(
@@ -21,6 +55,8 @@ async function main() {
   registerAll(server)
   const transport = new StdioServerTransport()
   await server.connect(transport)
+  clearOwnStaleMarker()
+  watchLauncher()
   let lifecycleSubscriber: PlanLifecycleSubscriber | undefined
   let planRoundSubscriber: PlanRoundSubscriber | undefined
   if (/^postgres(ql)?:\/\//.test(DATABASE_URL)) {

package/templates/core/templates/checklist-template.md

@@ -13,6 +13,7 @@
 
 - [ ] [T] 检查项1 — 证据: (待填写)|审计: (初验从 record_dev_operation 返回值写入真实 cuid，**禁止写 `cmq...` 占位符**)
 - [ ] [T] 检查项2 — 证据: (待填写)|审计: (初验从 record_dev_operation 返回值写入真实 cuid，**禁止写 `cmq...` 占位符**)
+- [ ] [T] schema 变更后运行实例 client 新鲜度（`db:generate` + 重启校验）— 证据: (待填写)|审计: (待填写) [来源: farm-agent 9737ab4 回灌；Prisma+Atlas 项目通用]
 
 ## ADD 规则合规检查
 
@@ -29,10 +30,22 @@
 > `[T]` = 编译期可验证（AI 可在代码环节直接检查）
 > `[R]` = 运行时验证（需部署运行后才能确认，自动流转到 review-runtime.md）
 
+### 三通道验收（涉及图/节点/流式呈现时必做）
+
+> [来源: farm-agent 9737ab4 回灌；与 review/review-implementation 的「三通道矩阵」配套，缺一即失败]
+
+- [T] 逐节点三通道矩阵闭环：①生命周期 ②内容 ③结构化，缺一即失败 — 证据: 对照 Plan 三通道矩阵
+- [T] 服务端未写死用户文案（文案在前端 i18n；服务端只发结构化字段/内容片段）— 证据: diff + grep
+- [T] 终态渲染不覆盖运行期累计内容 — 证据: 实机/单测
+- [T] 空态可渲染（0 条数据仍显示同构 DOM 或明确降级文案）— 证据: 实机截图/DOM 断言
+- [T] 耗时刷新有事件源（服务端心跳或前端 ticker，二者已定稿其一）— 证据: 契约/实现 diff
+- [R] 实机逐节点核对：运行中可见内容/结构化数据，终态内容不消失 — 证据: (待填写)
+
 ### 格式契约
 
 - [T] 所有跨系统 API：发送方参数类型 = 接收方解析类型，字段名一致
 - [T] 响应 Content-Type 匹配客户端解析器（JSON vs `text/event-stream` vs NDJSON）
+- [T] 外部契约版本漂移：外部契约（如 API collection）更新后 diff 契约并对齐 client（详见 review-implementation §6.1）
 
 ### 框架版本
 

package/templates/core/templates/review-implementation-template.md

@@ -24,6 +24,20 @@
 
 ---
 
+## 0. 三通道矩阵（涉及图/节点/流式呈现的变更强制）
+
+> **规则**：实现审查逐节点核对 ①生命周期流 ②内容流 ③结构化流；缺任一 = P0。
+> 与 Plan/Spec 的逐节点矩阵**逐项对齐**，并给出代码落点与实测证据。
+> [来源: farm-agent 9737ab4 回灌；域字段已泛化为占位符]
+
+| # | 节点 | action | ①生命周期流 | ②内容流 | ③结构化流 | 证据 |
+|---|------|--------|:---:|------|------|------|
+| 1 | {节点名} | {action 名} | {埋点/包装函数落点} | {内容承载} | {结构化字段投影} | {命令/抓包} |
+
+- [ ] 三通道逐节点闭环（N/N，与 Plan 矩阵一致）
+
+---
+
 ## 1. 跨仓库格式契约
 
 列出所有跨系统 API，逐对验证请求/响应格式：
@@ -74,6 +88,16 @@
 
 ---
 
+## 6.1 流式端点结构化字段投影完整性
+
+> [来源: farm-agent 9737ab4 回灌；原为具体域字段（reasoningPath/evidenceChain 等），此处泛化为契约表述]
+
+- [ ] GUI 消费者必须覆盖流式事件（如 `{结构化事件名}`）的**全部业务字段**，禁止按最小可用裁剪
+- [ ] 字段投影契约（spec `{契约章节}`）与前端消息字段 / UI 槽位**双向一致**（可用 `check_spec_sync` 校验）
+- [ ] 外部契约版本漂移：外部契约（如 API collection）更新后 **diff 契约 + 对齐 client**
+
+---
+
 ## 7. 关联 Checklist
 
 - 本 review 的检查项与 `{checklist 文档路径}` 的"跨项目联调检查"章节一一对应

package/templates/core/templates/review-template.md

@@ -25,6 +25,22 @@
 
 ---
 
+## 0. 三通道矩阵（涉及图/节点/流式呈现的变更强制）
+
+> **规则**：逐节点核对 ①生命周期流 ②内容流 ③结构化流；**缺任一通道 = P0，不得通过 Review**。
+> 「生命周期自动可观测」≠「内容存在」——内容/结构化数据必须由节点**显式发出**。
+> [来源: farm-agent 9737ab4 回灌；域字段已泛化为占位符]
+
+| # | 节点 | action | ①生命周期流 | ②内容流 | ③结构化流 | 证据/落点 |
+|---|------|--------|:---:|------|------|---------|
+| 1 | {节点名} | {action 名} | ✅/❌ | {内容载体（token/文本片段/其他）} | {结构化事件名 + 字段} | {文件/事件} |
+
+- [ ] 每个节点三通道均已定义（无「只有状态没有内容」的节点）
+- [ ] 空态（0 条数据 / 降级）仍有 DOM 或明确降级文案
+- [ ] 耗时/进度刷新有事件源（心跳或前端 ticker，二者已定稿其一）
+
+---
+
 ## 1. 问题复现
 
 为什么需要这次评审？

package/templates/core/validation/index.ts

@@ -0,0 +1,136 @@
+/*
+ * 校验层单一入口（Plan core-validation-lifecycle Task 1.3 / Spec §4 §LifecycleWiring）
+ *
+ * **所有调用方（hook 卡位 / 收尾 / 批量命令 / 封口判定）都调这一个入口**：
+ *   validate({ type, path, hook, mode?, expectRounds?, projectRoot, magicDir })
+ *
+ * 入口职责：读文档 → 解析类型配置（工厂）→ 取 schema 真源 → 执行 schema 校验 → 应用策略（口径）。
+ * 不在本层做任何"该类型特有"的判定（那是 validators/* 的专司）。
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { resolveValidator } from "./registry.js"
+import { applyApplicability, decidePolicy, type GovernanceHook, type ValidationMode } from "./policy.js"
+import { typeCheckFor } from "./validators/index.js"
+import {
+  validateAgainstSchema,
+  type SchemaFile,
+  type ValidationIssue,
+} from "./schema-validator.js"
+
+export interface ValidateInput {
+  type: string
+  /** 文档绝对路径 */
+  path: string
+  hook: GovernanceHook
+  /** 显式覆盖策略（缺省按卡位） */
+  mode?: ValidationMode
+  /** 多轮文档的期望轮次（由调用方给出，不由本层猜） */
+  expectRounds?: number
+  projectRoot: string
+  magicDir: string
+}
+
+export interface ValidateOutcome {
+  ok: boolean
+  type: string
+  hook: GovernanceHook
+  mode: ValidationMode
+  /** 策略依据（可审计） */
+  basis: string
+  schemaPath: string | null
+  /** 该卡位算作缺陷的问题（参与 ok 判定） */
+  issues: ValidationIssue[]
+  /** 该卡位不算缺陷、但仍需可见的问题（诊断；不参与 ok 判定）——规则适用性过滤的产物 */
+  diagnostics: ValidationIssue[]
+}
+
+/** schema 查找顺序：magic 目录副本优先，其次 templates/core 真源 */
+function resolveSchemaPath(input: ValidateInput, schemaFile: string): string | null {
+  const candidates = [
+    join(input.projectRoot, input.magicDir, "templates", schemaFile),
+    join(input.projectRoot, "templates", "core", "templates", schemaFile),
+  ]
+  return candidates.find((p) => existsSync(p)) ?? null
+}
+
+/** 模板查找（anchor 校验需要从模板对应行提取 token；顺序同 schema） */
+function resolveTemplatePath(input: ValidateInput, templateFile: string): string | null {
+  const candidates = [
+    join(input.projectRoot, input.magicDir, "templates", templateFile),
+    join(input.projectRoot, "templates", "core", "templates", templateFile),
+  ]
+  return candidates.find((p) => existsSync(p)) ?? null
+}
+
+export function validate(input: ValidateInput): ValidateOutcome {
+  const config = resolveValidator(input.type) // 未注册类型 → 抛错（不回落通用校验）
+  const policy = decidePolicy(input.hook, input.type, input.mode)
+  const schemaPath = resolveSchemaPath(input, config.schema)
+
+  const base: Omit<ValidateOutcome, "ok" | "issues" | "diagnostics" | "schemaPath"> = {
+    type: input.type,
+    hook: input.hook,
+    mode: policy.mode,
+    basis: policy.basis,
+  }
+
+  // schema 缺失 = 无法判定 → 显式失败（禁止静默放行，Spec §1）
+  if (!schemaPath) {
+    return {
+      ...base,
+      ok: false,
+      schemaPath: null,
+      issues: [
+        {
+          code: "MISSING_SECTION",
+          detail: `schema 真源缺失：${config.schema}（请执行 add-coder sync 或核对 templates/core/templates/）`,
+          expected: config.schema,
+        },
+      ],
+      diagnostics: [],
+    }
+  }
+  if (!existsSync(input.path)) {
+    return {
+      ...base,
+      ok: false,
+      schemaPath,
+      issues: [{ code: "MISSING_SECTION", detail: `文档不存在：${input.path}`, expected: input.path }],
+      diagnostics: [],
+    }
+  }
+
+  const schema = JSON.parse(readFileSync(schemaPath, "utf-8")) as SchemaFile
+  const content = readFileSync(input.path, "utf-8")
+  // 锚点规则需要模板内容（token 从模板行提取）；缺模板则锚点规则自动跳过（不误判）
+  const templatePath = schema.template ? resolveTemplatePath(input, schema.template) : null
+  const templateContent = templatePath ? readFileSync(templatePath, "utf-8") : undefined
+  // schema 层（形式）+ 专司层（本类型特有语义）——两层各自负责，互不重复
+  const rawIssues = validateAgainstSchema(content, schema, {
+    expectRounds: config.multiRound ? input.expectRounds : undefined,
+    templateContent,
+  })
+  const typeCheck = typeCheckFor(input.type)
+  if (typeCheck) {
+    rawIssues.push(...typeCheck({ type: input.type, content, path: input.path, expectRounds: input.expectRounds }))
+  }
+  // 规则适用性（Rule × Hook）：不在本卡位生效的规则降级为诊断，不参与 ok 判定
+  const { applicable, diagnostics } = applyApplicability(rawIssues, input.hook)
+  return { ...base, ok: applicable.length === 0, schemaPath, issues: applicable, diagnostics }
+}
+
+export { resolveValidator, VALIDATOR_REGISTRY, UnknownValidatorTypeError } from "./registry.js"
+export { decidePolicy, applyApplicability, DEFAULT_RULE_APPLICABILITY } from "./policy.js"
+export type { RuleApplicability, ApplicabilityResult } from "./policy.js"
+export type { ValidationMode, GovernanceHook } from "./policy.js"
+export {
+  validateAgainstSchema,
+  inferRoundHeading,
+  countRounds,
+  stripFencedBlocks,
+  normalizeWidth,
+} from "./schema-validator.js"
+export type { SchemaFile, SchemaSection, ValidationIssue, IssueCode } from "./schema-validator.js"
+export { typeCheckFor, uncoveredTypes } from "./validators/index.js"
+export type { TypeCheck, TypeCheckContext } from "./validators/types.js"

package/templates/core/validation/policy.ts

@@ -0,0 +1,91 @@
+/*
+ * 校验策略（Plan core-validation-lifecycle Task 1.2 / Spec §3 §Policy）
+ *
+ * 口径由**卡位 + 文档类型**共同决定，且结果必须携带 mode 与依据（可审计）。
+ * 卡位编号沿用 `templates/core/docs/ADD-governance-*.md` 的 ADD 治理卡位 ①–⑭。
+ */
+
+export type ValidationMode = "advisory" | "blocking"
+export type GovernanceHook =
+  | "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "PostToolUseFailure"
+  | "Stop" | "StopFailure" | "SessionEnd" | "PreCompact" | "SubagentStart" | "SubagentStop"
+  | "Notification" | "PermissionRequest" | "PermissionDenied" | "ConfigChange"
+  | "WorktreeCreate" | "WorktreeRemove" | "manual"
+
+export interface PolicyDecision {
+  mode: ValidationMode
+  /** 依据说明（进入结果，可审计） */
+  basis: string
+}
+
+/** 卡位默认口径（Spec §4 矩阵） */
+const HOOK_DEFAULT: Partial<Record<GovernanceHook, { mode: ValidationMode; basis: string }>> = {
+  PreToolUse: { mode: "blocking", basis: "④ 写入前置守卫：预检阻断，避免写出不合规文档" },
+  PostToolUse: { mode: "advisory", basis: "⑤ 文档守卫：写后复检不阻断，转告警 + 留痕" },
+  Stop: { mode: "blocking", basis: "⑦ 验收检查：跨文档一致性与封口判定，阻断未收敛" },
+  SubagentStop: { mode: "blocking", basis: "⑪ 子代理结果校验：产物同样须合规" },
+  SessionEnd: { mode: "advisory", basis: "② 审计结算：批量结果入库，不阻断" },
+  manual: { mode: "advisory", basis: "手工/批量调用：仅报告，不阻断" },
+}
+
+export function decidePolicy(hook: GovernanceHook, type: string, override?: ValidationMode): PolicyDecision {
+  if (override) {
+    return { mode: override, basis: `调用方显式指定 mode=${override}（type=${type}）` }
+  }
+  const byHook = HOOK_DEFAULT[hook]
+  if (byHook) return { mode: byHook.mode, basis: byHook.basis }
+  return { mode: "advisory", basis: `卡位 ${hook} 未声明口径 → 默认 advisory（不阻断）` }
+}
+
+/* ───────────────────────── 规则适用性（Rule × Hook） ─────────────────────────
+ * 为什么需要（2026-09-13 修订：抽层时发现的范围放大）：
+ * 规则集中到 core 后，若不加适用性约束，**原本只在某个卡位生效的规则会在所有卡位生效**——
+ * 例：锚定规则原为「写入时防劣化」，搬进 core 后会在收尾批量校验里把**历史文档**判为缺陷，
+ * 把噪音当违规。故规则集（what）与适用性（where）必须分开，严重度（how）由 decidePolicy 决定。
+ * ───────────────────────────────────────────────────────────────────────── */
+
+import type { ValidationIssue } from "./schema-validator.js"
+
+/** 规则码 → 适用卡位；`"*"` 表示全卡位 */
+export type RuleApplicability = Readonly<Record<string, readonly GovernanceHook[] | "*">>
+
+export const DEFAULT_RULE_APPLICABILITY: RuleApplicability = {
+  // 锚定类：仅"写入时防劣化"场景生效；批量/收尾不据此判历史文档为缺陷
+  ANCHOR_MISS: ["PreToolUse", "SubagentStop"],
+  // 缺失类：全卡位有效（文档缺失章节在哪都算缺陷）
+  MISSING_SECTION: "*",
+  MISSING_SUBSECTION: "*",
+  ROUND_COUNT_SHORT: "*",
+  // 占位符残留：全卡位有效
+  PLACEHOLDER_LEFT: "*",
+  // 结构位禁词：全卡位有效（0.3.27 语义）
+  FORBIDDEN_TERM: "*",
+  // checklist 证据占位：仅收尾/封口相关卡位算缺陷，写入时属"进行中"（advisory 诊断）
+  EVIDENCE_PLACEHOLDER_LEFT: ["Stop", "SessionEnd", "manual"],
+} as const
+
+export interface ApplicabilityResult {
+  /** 在该卡位算作缺陷的问题（参与 ok 判定） */
+  applicable: ValidationIssue[]
+  /** 在该卡位不算缺陷、但仍需可见的问题（诊断；不参与 ok 判定） */
+  diagnostics: ValidationIssue[]
+}
+
+/**
+ * 按卡位过滤问题：未声明适用性的规则码默认**全卡位适用**（保守：新规则不会因漏登记而静默失效）。
+ */
+export function applyApplicability(
+  issues: readonly ValidationIssue[],
+  hook: GovernanceHook,
+  applicability: RuleApplicability = DEFAULT_RULE_APPLICABILITY,
+): ApplicabilityResult {
+  const applicable: ValidationIssue[] = []
+  const diagnostics: ValidationIssue[] = []
+  for (const issue of issues) {
+    const scope = applicability[issue.code]
+    const inScope = scope === undefined || scope === "*" || scope.includes(hook)
+    if (inScope) applicable.push(issue)
+    else diagnostics.push(issue)
+  }
+  return { applicable, diagnostics }
+}

package/templates/core/validation/registry.ts

@@ -0,0 +1,61 @@
+/*
+ * validator 注册表（Plan core-validation-lifecycle Task 1.2 / Spec §2 §ValidatorRegistry）
+ *
+ * 文档类型 → validator 配置的**工厂**。未注册类型直接报错——不回落"通用校验"，
+ * 否则遗漏一个类型不会被发现（Spec §2）。
+ *
+ * 17 类文档与 schema 真源的对应关系见 Spec §5 覆盖表；schema 文件名由本表推导，不散落在调用方。
+ */
+
+export interface ValidatorConfig {
+  /** 文档类型标识（与 Spec §5 覆盖表一一对应） */
+  type: string
+  /** schema 文件名（位于 `{magicDir}/templates/` 或 `templates/core/templates/`） */
+  schema: string
+  /** 是否多轮文档（需要 expectRounds） */
+  multiRound?: boolean
+  /** 该类型特有的附加规则标识（由 validators/* 实现消费） */
+  extra?: "checklistT" | "tasksCheckbox" | "addRouteSteps"
+}
+
+export const VALIDATOR_REGISTRY: readonly ValidatorConfig[] = [
+  { type: "plan.standard", schema: "standard-plan-template.schema.json" },
+  { type: "plan.simple", schema: "simple-plan-template.schema.json" },
+  { type: "spec", schema: "spec-template.schema.json" },
+  { type: "tasks", schema: "tasks-template.schema.json", extra: "tasksCheckbox" },
+  { type: "checklist", schema: "checklist-template.schema.json", extra: "checklistT" },
+  { type: "add-route", schema: "add-route-template.schema.json", extra: "addRouteSteps" },
+  { type: "handoff.single", schema: "handoff-single-round-template.schema.json" },
+  { type: "handoff.multi", schema: "handoff-multi-round-template.schema.json", multiRound: true },
+  { type: "review", schema: "review-template.schema.json" },
+  { type: "review.implementation", schema: "review-implementation-template.schema.json" },
+  { type: "review.runtime", schema: "review-runtime-template.schema.json" },
+  { type: "hitl", schema: "hitl-template.schema.json" },
+  { type: "report", schema: "report-template.schema.json" },
+  { type: "runtime-report", schema: "runtime-report-template.schema.json" },
+  { type: "collab-contract", schema: "collab-contract-template.schema.json" },
+  { type: "fix-verification", schema: "fix-verification-template.schema.json" },
+  { type: "prd", schema: "prd-standard-template.schema.json" },
+] as const
+
+export class UnknownValidatorTypeError extends Error {
+  constructor(type: string) {
+    super(
+      `未注册的文档类型：${type}。已注册：${VALIDATOR_REGISTRY.map((v) => v.type).join(", ")}`,
+    )
+    this.name = "UnknownValidatorTypeError"
+  }
+}
+
+/** 工厂：按类型取配置；未注册即抛（不回落通用校验） */
+export function resolveValidator(type: string): ValidatorConfig {
+  const found = VALIDATOR_REGISTRY.find((v) => v.type === type)
+  if (!found) throw new UnknownValidatorTypeError(type)
+  return found
+}
+
+/** 覆盖完整性自检：返回 schema 清单中未被注册的类型对应文件（供 checklist 断言用） */
+export function unregisteredSchemas(schemaFiles: readonly string[]): string[] {
+  const registered = new Set(VALIDATOR_REGISTRY.map((v) => v.schema))
+  return schemaFiles.filter((f) => !registered.has(f))
+}