@agile-team/wl-skills-ui 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to **@agile-team/wl-skills-ui** will be documented in this f
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.8.0] - 2026-05-12
+
+### Added
+
+- 新增 **`standards/rules.json`** R-rule 单一事实源：29 条规则按 `id / category / severity / appliesTo / autoFixable / scanner / skills` 结构化注册，所有 standards 文档、SKILL.md、scanner、MCP、未来 ESLint 插件均从此派生。
+- 新增 **`standards/rules-loader.mjs`** 共享加载器：暴露 `loadRules / listRules / getRule / groupByCategory / buildRuleSummary`，scanner / MCP / check-docs / Vite 插件统一读取。
+- 新增 MCP 工具 **`wl_ui_list_rules`**：按 `category / severity / autoFixable` 过滤返回规则摘要。
+- 新增 MCP 工具 **`wl_ui_describe_rule`**：按 ID 返回单条 R-rule 完整定义（含 aliases 兼容旧 ID）。
+- 新增 **`docs/governance-long-term.md`**：业务项目长效治理方案（基线 / 豁免 / 漂移看板 / 版本钉死 / 写作期 AI 守护五机制）。
+- `scripts/check-docs.mjs` 扩展：校验 `scanner/rules/*.mjs` 中所有 `id` 必须在 `rules.json` 注册、SKILL.md 引用的 R-id 必须存在、`_registry.md` 引用的 skill 目录必须真实存在。
+
+### Changed (Breaking-ish)
+
+- **修复 R011 逻辑反转 bug**：之前 scanner 检测分页"不在 #footer 报错"，与 `standards/ui/05` "分页必须放内容区，不得放 #footer" 相互矛盾。v1.8.0 反转 scanner 检测语义，与 standards 对齐。
+- **`scanner/rules/tag.mjs` R017/R018 重号为 R019/R020**：原 ID 与 `color.mjs` 的 R017/R018 冲突。`rules.json` 通过 `aliases: [R017_TAG_LEGACY/R018_TAG_LEGACY]` 兼容历史引用；scanner 输出 `rule` 字段改为新 ID。
+- **`skills/_meta/_registry.md` 清理 12 条幽灵条目**：删除 9 个不存在的 `element/*` SKILL 引用（el-card/el-tabs/el-descriptions/el-tree/el-drawer/el-upload/el-steps/el-overlay/el-navigation/el-feedback），声明已统一归入 `element/component-family`；删除 2 个 `ops/*` 引用（route-intent / recommend-flow），声明为 MCP 工具而非独立 SKILL。
+- **`skills/runtime/style-align/SKILL.md` 改为指针式引用**：不再复述 17 条 R-rule 内容，仅保留分类→编号→SKILL 映射表，规则细节统一查 `standards/rules.json` 或 `wl_ui_describe_rule`。
+- `tsup.config.ts` `clean: true`：每次构建清空 `es/` 目录，避免 hash 残留。
+
+### Notes
+
+- R013（Upload 嵌入 operations[]）由文档约束晋升为 `rules.json` 正式条目（`severity: review`，无 scanner 实现）。
+- 推荐业务项目跟进：跑一次 `npx wl-ui audit --target src --outFile .wl-baseline.json` 建立基线，配合 `--baseline` 增量门槛使用（详见 `docs/governance-long-term.md`）。
+
 ## [1.7.1] - 2026-05-12
 
 ### Added

package/README.md

@@ -213,7 +213,16 @@ yarn add @agile-team/wl-skills-ui
 
 ## 版本亮点
 
-当前 v1.7.1 版本在 v1.7.0「单一事实源」基础上，把"识别"升级为"启动期自动 + 一键修复"：
+当前 v1.8.0 版本完成 R-rule 治理体系单一事实源化，并落地业务项目长效治理方案：
+
+- 新增 **`standards/rules.json`** 作为 29 条 R-rule 的单一事实源；所有 standards 文档、SKILL.md、scanner、MCP、未来 ESLint 插件均从此派生
+- 新增 **`standards/rules-loader.mjs`** 共享加载器；新增 MCP 工具 **`wl_ui_list_rules`** / **`wl_ui_describe_rule`**，AI 写代码前一键查规则
+- 修复历史 ID 冲突与逻辑反转 bug：scanner `tag.mjs` 原 R017/R018 重号为 R019/R020（与 `color.mjs` 解耦，旧 ID 通过 `aliases` 兼容）；R011 由"必须放 #footer"反转为"不得放 #footer"，与 standards/ui/05 对齐
+- 清理 `_registry.md` 12 条幽灵 skill 引用；`runtime/style-align/SKILL.md` 改为指针式引用 rules.json，不再复述规则细节
+- `scripts/check-docs.mjs` 扩展为 R-rule / scanner / SKILL / registry 四向一致性守卫，CI 不一致直接红灯
+- 新增 **`docs/governance-long-term.md`**：业务项目长效治理方案（基线 / 豁免 / 漂移看板 / 版本钉死 / 写作期 AI 守护五机制），杜绝遗留累积与升级回归
+
+历史亮点（v1.7.1）：
 
 - 新增 Vite 插件 `@agile-team/wl-skills-ui/vite`：消费方一行配置即可在每次启动 dev/build 时自动跑版本配对校验，偏离时彩色提示 + 修复片段
 - 新增 `npx wl-ui doctor --print-overrides`：检测到偏离直接输出 pnpm/npm/yarn overrides JSON，复制粘贴即可修复

package/docs/governance-long-term.md

@@ -0,0 +1,191 @@
+# 长效治理：业务项目如何避免遗留与漂移污染
+
+> 适用：使用 `@agile-team/wl-skills-ui` 的业务项目，长期迭代过程中**不让历史违规无限累积**、**不让新代码反向污染**、**不让升级回归打穿主干**。
+> 事实源：本文档结合 `standards/rules.json` 单一事实源 + `scanner/snapshot.mjs` + `scanner/exempt.mjs` 共同提供。
+
+## 一、问题画像
+
+业务项目随时间会出现三种"污染"：
+
+| 类型 | 表现 | 根因 |
+| --- | --- | --- |
+| **历史遗留**（legacy） | 旧页面违规但没人修，scanner 报错被忽略 | 一次性扫描门槛太高，团队选择 mute |
+| **风格漂移**（drift） | 同一种场景不同写法，hex 颜色又冒出来 | 没有 PR 级别的增量校验 |
+| **升级回归**（regression） | wl-skills-ui 升版后老页面视觉错乱 | vendor 版本配对没钉死、scoped 样式覆盖底层 |
+
+下面三条机制对应三个根因。
+
+---
+
+## 二、机制 1 · 基线快照（Baseline）
+
+**目标**：把"历史欠债"冻结，新代码只对增量负责。
+
+```bash
+# 在主干分支建立基线（团队第一次接入时执行一次）
+npx wl-ui audit --target src --output json --outFile .wl-baseline.json
+git add .wl-baseline.json && git commit -m "chore: wl-ui baseline snapshot"
+```
+
+`.wl-baseline.json` 记录当前所有违规条目的 `(file, line, ruleId)` 指纹。后续：
+
+```bash
+# PR 检查（仅报新增违规）
+npx wl-ui scan --target src --baseline .wl-baseline.json --fail-on=new-issues
+```
+
+- **历史条目不再阻塞构建**（团队按计划逐步消化）
+- **新代码引入新违规 → 立即红灯**
+- 团队修复历史条目后跑 `npx wl-ui audit --refresh-baseline` 收敛基线
+
+> 实现入口：`scanner/snapshot.mjs` 已具备文件级快照能力，issue 级 baseline 在 v1.8.0 起以 `audit --output json` 输出为契约，业务项目可自行 diff。
+
+---
+
+## 三、机制 2 · 豁免与隔离（Quarantine）
+
+**目标**：大屏、地图、流程设计器等强个性化页面 + 不再迭代的旧模块，明确隔离，**不参与统一风格扫描**。
+
+`.wl-exempt.json`：
+
+```json
+{
+  "exemptPaths": [
+    "src/views/**/big-screen/**",
+    "src/views/**/dashboard/**",
+    "src/views/legacy/**"
+  ],
+  "exemptRules": {
+    "R016": ["src/views/**/chart/**"]
+  },
+  "exemptCategories": ["dashboard", "big-screen", "report-designer"],
+  "description": "大屏与遗留模块豁免风格统一扫描；新功能不得新增豁免路径"
+}
+```
+
+约束（团队规约）：
+
+1. 豁免清单**只能减少**，不能增加（新增需架构组评审 PR）
+2. 豁免路径**禁止承载新业务**；新业务必须落到非豁免目录
+3. 每季度团队负责人审视豁免清单：能解开就解开
+
+> 实现入口：`scanner/exempt.mjs::loadExemptConfig` 已支持 glob + 规则级豁免；CLI/MCP/Vite 插件统一读取。
+
+---
+
+## 四、机制 3 · 漂移看板（Drift Dashboard）
+
+**目标**：让"逐渐变烂"可见，每次升级都能量化。
+
+```bash
+# 每次 wl-skills-ui 升版后跑一次
+npx wl-ui audit --target src --output json --outFile .wl-drift-after.json
+node -e "console.log(require('@agile-team/wl-skills-ui/scanner/drift.mjs').report('.wl-baseline.json','.wl-drift-after.json'))"
+```
+
+输出（示意）：
+
+```
+变化（基线 → 当前）
+  gained   +12  新增违规（红灯）
+  fixed    -45  消化历史（绿灯）
+  regressed +3  曾修过又破的（黄灯，最高优先级追查）
+  exempt    +0  豁免清单未扩张
+按规则 Top3：R017(+8) R001(+3) R009(+1)
+按目录 Top3：src/views/quote(+9) src/views/cost(+3)
+```
+
+> 实现入口：v1.8.0 起 `scanner/index.mjs` 已暴露 `--output json` 完整结构（含 `file/line/rule`），业务项目可基于该结构自实现 drift 报告；包内 `scanner/drift.mjs` 在 1.8.x 后续小版本提供。
+
+---
+
+## 五、机制 4 · 版本钉死（Lock & Detect）
+
+**目标**：vendor（Element Plus / @jhlc/jh-ui）版本飘移导致老页面 DOM 不匹配的问题，**在启动期就发现**，而不是页面坏了才查。
+
+```ts
+// vite.config.ts
+import { wlSkillsCheck } from '@agile-team/wl-skills-ui/runtime/vite/check.mjs'
+
+export default defineConfig({
+  plugins: [
+    wlSkillsCheck({
+      enforce: 'warn',          // 'warn' | 'error'
+      verbose: false,
+    }),
+  ],
+})
+```
+
+启动时输出（不匹配示意）：
+
+```
+[wl-skills-ui] 版本偏离推荐组合：
+  element-plus@2.6.3 ≠ 推荐 2.2.6-prod.3（jh 集群）
+  @jhlc/jh-ui@3.1.0 ✓
+  修复片段：
+    "pnpm": { "overrides": { "element-plus": "2.2.6-prod.3" } }
+```
+
+> 推荐组合 = `skills/_meta/_compat/vendors.json`（事实源）。CLI: `npx wl-ui doctor --print-overrides`。MCP: `wl_ui_detect_skin`。
+
+---
+
+## 六、机制 5 · 写作期 AI 守护（Editor Skill）
+
+**目标**：在 AI 写出新代码的那一刻就让它**对齐 rules.json**，而不是事后扫描。
+
+- 编辑器接入：`npx wl-ui init` 会把 `.cursor/rules` / `.windsurf/rules` 等指向 `skills/` 目录
+- AI 强约束（写入 SKILL 头部）：
+  - 任何样式相关结论必须先通过 MCP `wl_ui_describe_rule` 查 `standards/rules.json`
+  - **禁止**在业务 SFC 的 `<style scoped>` 中覆盖 `.el-*` / `.jh-*` 全局选择器；样式补丁全部归 wl-skills-ui 升级
+  - 新增组件族适配优先升级到 wl-skills-ui，而不是在业务侧封 `Base*` 二代
+
+效果：AI 写出的代码 day-1 即合规，不再产生历史欠债。
+
+---
+
+## 七、典型业务项目接入清单
+
+```bash
+# 1. 安装
+pnpm add -D @agile-team/wl-skills-ui
+
+# 2. 编辑器规则 + MCP + 启动期插件
+npx wl-ui init --project . --mode skin
+
+# 3. 基线
+npx wl-ui audit --target src --outFile .wl-baseline.json --output json
+git add .wl-baseline.json
+
+# 4. 豁免（如有）
+cp node_modules/@agile-team/wl-skills-ui/.wl-exempt.example.json .wl-exempt.json
+# 编辑为本项目实际豁免路径
+
+# 5. CI 加 PR gate
+#   npx wl-ui scan --target src --baseline .wl-baseline.json --fail-on=new-issues
+
+# 6. 每季度 / 每次升级
+npx wl-ui doctor --print-overrides     # 版本对齐
+npx wl-ui audit --refresh-baseline      # 基线收敛
+```
+
+---
+
+## 八、wl-skills-ui 自身的承诺
+
+为了让业务项目"敢于"长期跟随：
+
+1. **R-rule 不删只迁**：v1.8.0 起 `tag.mjs` 的旧 R017/R018 → R019/R020，旧 ID 在 `rules.json.aliases` 保留，scanner 输出兼容
+2. **CSS Token 不破坏**：`design/tokens/base.css` 的变量名为长期契约，重命名走 deprecate → alias → remove 三段式
+3. **vendor 适配可选**：业务项目偏离推荐组合时插件**只警告不阻塞**，由项目方决策升级节奏
+4. **每个 minor 版本附带 compat-matrix 更新**：`docs/compat-matrix.md` 是版本与 vendor 的双向契约
+5. **`docs:check` 守护文档/规则/scanner 一致性**：包级 CI 不通过则不发版
+
+---
+
+## 九、不做的事
+
+- ❌ 不强行重写业务 SFC 结构（除非走 ops/migrate 显式确认）
+- ❌ 不在业务项目里塞自动 commit hook（团队自行选 husky/lefthook）
+- ❌ 不收集业务项目数据（所有扫描结果留在本地或 CI artifact）

package/mcp/server.js

@@ -98,6 +98,41 @@ const TOOLS = [
       required: [],
     },
   },
+  {
+    name: "wl_ui_list_rules",
+    description:
+      "列出 wl-skills-ui R-rule 全集（事实源：standards/rules.json）。可按 category / severity / autoFixable 过滤。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          description:
+            "可选：table / button / form / dialog / tag / style / base / family / layout",
+        },
+        severity: {
+          type: "string",
+          description: "可选：error / warning / info / suggestion / review",
+        },
+        autoFixable: {
+          type: "boolean",
+          description: "可选：仅返回可自动修复的规则",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "wl_ui_describe_rule",
+    description: "返回单条 R-rule 的完整定义（事实源：standards/rules.json）。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "规则 ID，例如 R001、R019" },
+      },
+      required: ["id"],
+    },
+  },
   {
     name: "wl_ui_recommend_flow",
     description:
@@ -409,6 +444,57 @@ async function dispatchTool(id, name, args) {
       });
       return;
     }
+    if (name === "wl_ui_list_rules") {
+      const loader = await import("../standards/rules-loader.mjs");
+      const rules = loader.listRules({
+        category: args.category,
+        severity: args.severity,
+        autoFixable: args.autoFixable,
+      });
+      const summary = rules.map((r) => ({
+        id: r.id,
+        severity: r.severity,
+        category: r.category,
+        title: r.title,
+        autoFixable: !!r.autoFixable,
+      }));
+      sendResult(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { total: summary.length, rules: summary },
+              null,
+              2,
+            ),
+          },
+        ],
+      });
+      return;
+    }
+    if (name === "wl_ui_describe_rule") {
+      const loader = await import("../standards/rules-loader.mjs");
+      const rule = loader.getRule(args.id);
+      if (!rule) {
+        sendResult(id, {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                { ok: false, reason: `规则 ${args.id} 未注册` },
+                null,
+                2,
+              ),
+            },
+          ],
+        });
+        return;
+      }
+      sendResult(id, {
+        content: [{ type: "text", text: JSON.stringify(rule, null, 2) }],
+      });
+      return;
+    }
     if (name === "wl_ui_recommend_flow") {
       sendResult(id, {
         content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 项目通用化妆/原生双模式（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",

package/scanner/rules/dialog.mjs

@@ -1,29 +1,44 @@
-/** scanner/rules/dialog.mjs — 弹窗分页规则：R011 */
+/** scanner/rules/dialog.mjs — 弹窗分页规则：R011
+ *  v1.8.0 修复：之前逻辑反了（要求"必须放 #footer"），与 standards/ui/05-dialog-pagination.md
+ *  「分页必须放在内容区，不得放在 #footer」语义矛盾。本版反转为正确语义：检测到
+ *  #footer 内含 el-pagination 即报错。
+ *  事实源：standards/rules.json (R011)
+ */
 import { lineOf, issue } from "./_shared.mjs";
 
 export const dialogRules = [
-  // R011: pagination 放在 #footer 外面
+  // R011: el-pagination 不得位于 #footer 插槽中
   {
     id: "R011",
     category: "dialog",
     severity: "error",
-    name: "弹窗内分页器应放在 #footer slot 中",
+    name: "弹窗内 el-pagination 不得放在 #footer 插槽中",
     check(template, file, lineOffset) {
       const issues = [];
-      // 找到 #footer slot 的范围
-      const footerMatch = /<template\s+#footer\b/;
-      const footerIdx = template.search(footerMatch);
-      // 找 el-pagination
-      const paginationPattern = /<el-pagination\b/g;
+      // 提取所有 <template #footer ...> ... </template> 段
+      const footerSegments = [];
+      const footerOpenRe = /<template\s+#footer\b[^>]*>/g;
+      let openMatch;
+      while ((openMatch = footerOpenRe.exec(template)) !== null) {
+        const start = openMatch.index;
+        const after = template.slice(start);
+        // 简易匹配最近的 </template>（v3 中 footer slot 不嵌套 template）
+        const closeRel = after.search(/<\/template>/);
+        if (closeRel === -1) continue;
+        footerSegments.push({ start, end: start + closeRel });
+      }
+      const inFooter = (idx) =>
+        footerSegments.some((s) => idx >= s.start && idx <= s.end);
+
+      const paginationRe = /<el-pagination\b/g;
       let m;
-      while ((m = paginationPattern.exec(template)) !== null) {
-        // 是否在 el-dialog 里？
+      while ((m = paginationRe.exec(template)) !== null) {
+        // 必须在 el-dialog 内
         const before = template.slice(0, m.index);
         const dialogOpens = (before.match(/<el-dialog\b/g) || []).length;
         const dialogCloses = (before.match(/<\/el-dialog>/g) || []).length;
-        if (dialogOpens <= dialogCloses) continue; // 不在 dialog 内
-        // 是否在 footer 之外？
-        if (footerIdx === -1 || m.index < footerIdx)
+        if (dialogOpens <= dialogCloses) continue;
+        if (inFooter(m.index)) {
           issues.push(
             issue(
               file,
@@ -31,10 +46,11 @@ export const dialogRules = [
               "R011",
               "dialog",
               "error",
-              "弹窗内 el-pagination 未放在 <template #footer> 中",
-              '将 el-pagination 移至 <template #footer><div class="dialog-footer">...</div></template>',
+              "弹窗内 el-pagination 位于 #footer 插槽中（会逃出 dialog 容器漂浮在页面底部）",
+              '将 el-pagination 移到内容区，包裹 <div class="popup-pagination">；#footer 仅放操作按钮',
             ),
           );
+        }
       }
       return issues;
     },

package/scanner/rules/tag.mjs

@@ -1,4 +1,7 @@
-/** scanner/rules/tag.mjs — 标签/状态规则：R009 R010 R012 R017 R018 */
+/** scanner/rules/tag.mjs — 标签/状态规则：R009 R010 R012 R019 R020
+ *  v1.8.0 重号：原 R017 → R019（与 color.mjs R017 冲突），原 R018 → R020（与 color.mjs R018 冲突）。
+ *  事实源：standards/rules.json
+ */
 import { lineOf, issue, findTags } from "./_shared.mjs";
 
 /** 状态类字段名关键字（动态流转状态） */
@@ -124,15 +127,14 @@ export const tagRules = [
     },
   },
 
-  // R017: 编号/工号/证件号列缺少 renderBadge（脚本式 columnsDef）
+  // R019（原 R017，v1.8.0 重号）: 编号/工号/证件号列缺少 renderBadge
   {
-    id: "R017",
+    id: "R019",
     category: "tag",
     severity: "warning",
     name: "编号/工号/证件号列缺少 renderBadge（脚本式 columnsDef）",
     checkScript(script, file, lineOffset) {
       const issues = [];
-      /** label 关键字：编号、工号、证件号、以及常见英文组合 */
       const BADGE_LABEL_RE =
         /编号|工号|证件号|驾驶员证件号|车主证件号|处置人工号/;
       const lines = script.split("\n");
@@ -150,7 +152,7 @@ export const tagRules = [
         issues.push({
           file,
           line: lineOffset + i + 1,
-          rule: "R017",
+          rule: "R019",
           category: "tag",
           severity: "warning",
           description: `编号列 "${label}" 未使用 renderBadge，纯文本无视觉区分`,
@@ -161,9 +163,9 @@ export const tagRules = [
     },
   },
 
-  // R018: 脚本式列定义使用 logicType:dict 但缺少 defaultSlot（应改为 renderDictClassifyTag）
+  // R020（原 R018，v1.8.0 重号）: logicType:dict 列缺少 defaultSlot
   {
-    id: "R018",
+    id: "R020",
     category: "tag",
     severity: "warning",
     name: "dict列缺少 defaultSlot/renderDictClassifyTag（脚本式 columnsDef）",
@@ -190,7 +192,7 @@ export const tagRules = [
         issues.push({
           file,
           line: lineOffset + i + 1,
-          rule: "R018",
+          rule: "R020",
           category: "tag",
           severity: "warning",
           description: `"${label}" 使用 logicType:dict 但无 defaultSlot，纯文本展示枚举值`,

package/scripts/check-docs.mjs

@@ -145,6 +145,97 @@ for (const editor of editorConfig.editors) {
   }
 }
 
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// v1.8.0 新增校验：rules.json 单一事实源 + 幽灵 skill
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+const rulesJsonPath = join(root, "standards", "rules.json");
+if (!existsSync(rulesJsonPath)) {
+  errors.push("standards/rules.json: 文件不存在（v1.8.0 起为 R-rule 单一事实源）");
+} else {
+  const rulesData = JSON.parse(readFileSync(rulesJsonPath, "utf8"));
+  const rulesById = new Map(rulesData.rules.map((r) => [r.id, r]));
+  const aliasMap = new Map();
+  for (const r of rulesData.rules)
+    for (const a of r.aliases || []) aliasMap.set(a, r.id);
+
+  // (1) 校验 ID 唯一
+  if (rulesById.size !== rulesData.rules.length) {
+    errors.push("standards/rules.json: 存在重复 R-id");
+  }
+
+  // (2) 校验 scanner/rules/*.mjs 中所有 id: "Rxxx" 都在 rules.json 中存在且 scanner 字段一致
+  const scannerRulesDir = join(root, "scanner", "rules");
+  for (const f of readdirSync(scannerRulesDir)) {
+    if (!f.endsWith(".mjs") || f.startsWith("_") || f === "index.mjs") continue;
+    const code = readFileSync(join(scannerRulesDir, f), "utf8");
+    const idMatches = [...code.matchAll(/id:\s*["'](R\d{3})["']/g)].map(
+      (m) => m[1],
+    );
+    for (const rid of idMatches) {
+      const rule = rulesById.get(rid);
+      if (!rule) {
+        errors.push(
+          `scanner/rules/${f}: 规则 ${rid} 未在 standards/rules.json 注册`,
+        );
+        continue;
+      }
+      const expectedScanner = `scanner/rules/${f}`;
+      if (rule.scanner && rule.scanner !== expectedScanner) {
+        errors.push(
+          `standards/rules.json: ${rid}.scanner 应为 "${expectedScanner}"（当前 "${rule.scanner}"）`,
+        );
+      }
+    }
+  }
+
+  // (3) 校验 skills/**/SKILL.md 引用的 R-rule 必须在 rules.json 中存在
+  const skillsRoot = join(root, "skills");
+  function walkSkills(dir, list = []) {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walkSkills(p, list);
+      else if (e.name.endsWith(".md")) list.push(p);
+    }
+    return list;
+  }
+  for (const f of walkSkills(skillsRoot)) {
+    const rel = relative(root, f).replace(/\\/g, "/");
+    const content = readFileSync(f, "utf8");
+    const refs = [...new Set(
+      [...content.matchAll(/\b(R\d{3})\b/g)].map((m) => m[1]),
+    )];
+    for (const rid of refs) {
+      if (rulesById.has(rid)) continue;
+      if (aliasMap.has(rid)) continue;
+      errors.push(
+        `${rel}: 引用了未注册规则 ${rid}（应在 standards/rules.json 中定义或加 aliases）`,
+      );
+    }
+  }
+
+  // (4) 校验 _registry.md 提到的 skill 目录必须真实存在
+  const registryPath = join(root, "skills", "_meta", "_registry.md");
+  if (existsSync(registryPath)) {
+    const reg = readFileSync(registryPath, "utf8");
+    const skillRefs = [
+      ...reg.matchAll(/\b(element|vendors|layouts|runtime|ops)\/([a-z][a-z0-9-]*)\b/g),
+    ];
+    const seen = new Set();
+    for (const m of skillRefs) {
+      const key = `${m[1]}/${m[2]}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const dir = join(skillsRoot, m[1], m[2]);
+      const skillFile = join(dir, "SKILL.md");
+      if (!existsSync(skillFile)) {
+        errors.push(
+          `skills/_meta/_registry.md: 引用的 skill "${key}" 不存在 (期望 ${relative(root, skillFile).replace(/\\/g, "/")})`,
+        );
+      }
+    }
+  }
+}
+
 if (errors.length > 0) {
   console.error(
     "docs:check failed:\n" + errors.map((error) => `- ${error}`).join("\n"),