// X-RULE-BEGIN-STANDARD-x-standard-STD-COMMON-0001-规范简介-P1-X
架构层治理规范(业务架构去漂移与系统架构设计件 V2.0.10)
规范简介:本规范治理.claude/arch/business/业务架构层(DDD bounded context 端到端设计真相;目录两层「中心/域」,中心就是后台菜单第一层,代码目录不跟着分类搬、由各域 describes 认领)。V1.1.0(2026-09-14)起业务架构整体迁入.claude/arch/business/,与系统架构目录.claude/arch/system/并列,适用文件与注册表根同批迁移。V1.2.0(2026-09-14)起增系统组,治理.claude/arch/system/系统架构层(每份规范一个目录,放系统四件套的设计件:架构页 ARCH.html 与变更历史 CHANGELOG.md):规范与目录一一对应、迁移期由系统组注册表的名册只减不增过渡(NS-COMMON-0007);架构页派生区戳记保鲜(NS-COMMON-0008);四件套版本锁步(NS-COMMON-0009);架构页原件写完、测试床点名验真(NS-COMMON-0010)。业务组 NS-COMMON-0002 同批增约束臂:specRefs 的名字必须是存在的规范。V1.2.1(2026-09-14)起 x-arch 自身迁为第一套系统四件套(规则书改写为条款书,建架构页与变更历史),系统组注册表的迁移名册同批划掉 x-arch。强制注册表完整性(登记域必有文档)+ 文档头完整性(frontmatter 契约 + describes 四端键 + layer=business + specRefs 句法代理防第二真相源)+ srcHash 四端保鲜牙(NS-COMMON-0003,改描述域代码逼回看 arch,活体验真:2026-07-11 抓获 customer/dispatch/coupon 真实漂移)。detector 全域无关(读注册表/frontmatter,不硬编码业务域,落实"框架操作业务但绝不依赖业务"铁律)。纯条件检测规范(全 NS,无 STD 模板)。V1.4.0(2026-09-16)起测试床点名验真加两臂(NS-COMMON-0010):床的种类必须写实 —— 不标data-bed-kind的床文件里必须真调用引擎(extractNsRuleDetector或check.js),只守不变量、不跑判据的床写data-bed-kind="invariant";data-guards兼收「规范名:ARCH-条款号」,让由床承接的无机器闸条款有处登记(条款须在该规范条款书里真实存在)。V1.5.0(2026-09-16)起「真调用引擎」的认定扩到四种令牌:extractNsRuleDetector、check.js、buildDetectorTools、X-RULE-BEGIN-SLOT—— 手抠判据 SLOT 块、经引擎buildDetectorTools喂 tools 跑检测器的床同样是真跑判据(V1.4.0 只认前两种,把这类床误判成没跑判据)。V1.6.0(2026-09-18)起令牌认定从「全文出现过这段文字」收紧为「剥掉注释后按调用形态出现」:函数令牌extractNsRuleDetector/buildDetectorTools/checkStandardFormat(本版新增,跑引擎真 STD 执行器的床)须写成调用令牌(,check.js须作为路径段出现,X-RULE-BEGIN-SLOT须出现在注释以外 —— 此前注释里写一句check.js、或一个无关文件名(access-check.js)里恰好含这段文字都能过闸。V1.7.0(2026-09-20)起增 NS-COMMON-0011:架构页必须遵循《系统架构标准》的可机判面(节名册与顺序、节编号属性、表达层在场),判定依据是同前缀名册x-arch-standard.json,名册只减不增、pending 里的域整条静默 —— 此前「按模板长成一个样」这件事零机器强制,33 页可以各长各的而检测全绿。V1.8.0(2026-09-20)曾给 NS-COMMON-0008 增臂B(把变更历史渲染成同目录派生件并核对三戳),V1.8.2(2026-09-20)撤销:渲染改由治理站点在构建时做,产物不进仓、每次构建重生成,因而不需要保鲜闸 —— 闸是「产物进仓」的代价,不进仓就不用付。V1.11.0(2026-09-22)起增 NS-COMMON-0013「业务结构放置」:每张表恰好归一个域、子表与关系表在表文档里写明上级、按放置规则放对一层(子与上级同域;关系两端同域则同域,跨域则归关系域)—— 此前「哪张表属于谁」零机器强制,61 张表里 23 张无主而检测全绿。同批 NS-COMMON-0002 增写法臂:describes 只接受「目录/**」,单文件、中段通配、指向文件的写法会让保鲜闸静默算成没有代码。V1.11.1(2026-09-22)是立闸当日三路对抗检查之后的加固:关系表改写「上级」逃关系域、同名诱饵表文档、注释 / 代码块 / 散文伪造关联、名册豁免外溢与只增不减、忽略目录隐身、describes 路径别名绕过重叠臂 —— 实测打穿的写法全部堵上并钉进床;0002 增别名臂(路径必须是唯一规范写法、大小写与磁盘一致),0003 声明 null 那一支的报文不再印实算指纹。V1.12.0(2026-09-22)业务模块页收敛出一份跨域共用的表达层(.claude/arch/assets/business-module.css,此前企业信息域整份复制了客户域三份样式表),NS-COMMON-0012 臂③ 随之从「刻意不判样式表」改为「第一份样式表必须是它」,名册的放开条件兑现。V1.13.0(2026-09-22)起增 NS-COMMON-0014「业务域版本锁步」:ARCH.md的 version 必须等于CHANGELOG.md最新一条条目的版本,条目标题只认「## v主.次.补 — YYYY-MM-DD」(可接「 · 一句说明」),条目按版本严格从新到旧、日期不倒挂 —— 此前系统四件套有版本锁步闸、业务域没有,保鲜闸放行只证明重算过指纹、不证明升过版(立闸当日 15 个域里 11 个对不上);存量登记在同前缀名册x-arch-business-lockstep.json,只减不增。V1.14.0(2026-09-22)起测试床点名的位置从「x-test 下」放宽为「测试根下」(x-test/、.claude/skills/<技能>/tests/、.claude/hooks/tests/):测试跟着被测对象放,唯一运行器按位置收床。V1.16.0(2026-09-22)起 NS-COMMON-0010 判「床在不在测试根」改用引擎注入的测试根谓词tools.isTestPath(唯一真相源constants/test-roots.js),不再在判据里手抄测试根正则;自研技能的测试根只认x-前缀的技能(第三方技能自带的 tests 不属本仓测试体系)。V1.15.0(2026-09-22)起业务架构的写法从「每个业务模块页十节」换成「每个业务域六个视图」(架构设计 / 流程设计 / 前端设计 / 服务设计 / 数据设计 / 修改历史),《业务架构标准》同批改名《架构设计模板》:NS-COMMON-0012 改判「业务域遵循架构设计模板」,名册换成x-arch-design-template.json,旧名册x-arch-business-standard.json退役 —— 菜单域是第一个样板,其余 14 个域登记在新名册的只减不增清单里。V1.17.0(2026-09-23)起业务架构按后台菜单的四大中心分类(ADR-59):目录固定两层「中心/域」(营销 marketing / 电商 ecommerce / 服务 service / 研发 randd),NS-COMMON-0001 从「登记的域有文档」扩成四臂 —— 注册表「四大中心」一节登记中心、每个域的门牌是「已登记的中心/域」且文档路径就是「门牌/ARCH.md」、磁盘上每个域目录都必须登记;NS-COMMON-0012 与 0014 冻结的立闸当日清单按新门牌改名(同一批域,只换名、不增不减)。V1.18.0(2026-09-24)起 NS-COMMON-0013 认「关联」收紧到条款原意:字段说明里只有紧挨着「表.字段」的「关联」二字才算关联(中间只许空白、冒号与反引号;多态外键每个去向各写一次「关联」)—— 此前同一格里任何「表.字段」提及都算关联,于是购物车、收藏、足迹三张关系表字段说明里的快照来源(「同sku_maintenance_node.spuName」「取spu_base.productType」)会被算成关系的第三、第四端,逼着把快照来源写进两端、把关系域的 relates 撑大;条款书写的一直是「关联表.字段」,判据比条款宽。V1.19.0(2026-09-24,测试闭环 L3)起 NS-COMMON-0010 堵三处:架构页里被 HTML 注释包住的点名不再算数(先剥注释再解析点名);床内文里的「规范名:编号」按完整编号认(前后都不许紧挨字母、数字、下划线或连字符,在四位编号后面多写一位数字的加长写法不再冒充原编号);点名的床不许住在唯一运行器不收床的目录里(夹具、依赖、以「.」或「zz」开头的目录,判据经引擎注入的tools.isTestSkipDir判)—— 此前这三种写法都能过闸,而点名的床要么根本不在页面上、要么守的不是那颗闸、要么永远不会被跑到。V1.19.1(2026-09-24)订正 NS-COMMON-0010 按完整编号认那一臂的转义函数:V1.19.0 写入时替换串里的$&被展开成了邻行代码,转义实际没有生效;编号文法里没有正则元字符,所以行为没有变化,改为函数替换后替换串里不再出现$。V1.20.0(2026-09-24)起架构设计模板加第七个视图「测试设计」(parts/test.html,排在数据设计之后、修改历史之前):宪法测试闭环要求测试守不到的地方写进设计,此前业务域没有地方写「谁在测本域的代码、哪里测不到」。名册加一个视图,NS-COMMON-0012 的四臂不变;报文里写死的「五个视图页」「六个视图」改为从名册派生,以后再增减视图不必改判据代码。V2.0.0(2026-09-28,HARNESS v4.0.0 版本契约)起三层版本统一:业务域的 srcHash 保鲜退役,NS-COMMON-0003 改判「业务域代码锁步」(域的锁清单逐个文件记下封版时的代码,只改注释不算改);NS-COMMON-0009 与 0014 改调检测引擎里唯一一份版本契约代码(经引擎注入的tools.versionContract)—— 变更历史统一写成「## v主.次.补 · YYYY-MM-DD · 一句标题」、文档头 title / unit / kind、封版由统一封版命令写三行指纹与改动清单;业务域版本锁步名册x-arch-business-lockstep.json退役(迁入统一写法后全部锁步,不再需要存量豁免);新增 NS-COMMON-0015「业务总览版本锁步与无主业务代码只减不增」;域目录与系统架构目录的白名单放行锁清单version-lock.json;ARCH.md文档头禁再出现退役的srcHash。
📖 规范定位(三位一体)
规范文档:.claude/skills/x-spec-checker/references/x-arch-spec.md(本文件)
检测脚本:.claude/skills/x-spec-checker/scripts/check-spec/check.js(规范检测脚本)
实际代码:.claude/arch/business/**/*.md(业务架构文档 + 注册表)、.claude/arch/system/**(系统架构目录)、.claude/skills/x-spec-checker/references/x-arch-system.json(系统组注册表)
// X-RULE-END-STANDARD-x-standard-STD-COMMON-0001-规范简介-P1-X
// X-RULE-BEGIN-STANDARD-x-standard-STD-COMMON-0002-规则汇总表-P1-X
📊 规则汇总表
强制标准(STD)
| 规则ID | 规则名称 | 检测阶段 | 检测内容 |
|---|
// X-RULE-MULTILINE-BEGIN-x-standard-STD-COMMON-0002-STD规则行-X
| (无) | - | - | 本规范所有规则均为 NS 类型(条件检测) |
// X-RULE-MULTILINE-END-x-standard-STD-COMMON-0002-STD规则行-X
非标兜底(NS)
| 规则ID | 规则名称 | 检测阶段 | 检测内容 |
|---|
// X-RULE-MULTILINE-BEGIN-x-standard-STD-COMMON-0002-NS规则行-X
| NS-COMMON-0001 | arch 注册表完整性 | 阶段2 | 业务组(锚在注册表 _index.md)。四臂:① 登记的每个业务域有架构文档 ② 「四大中心」一节在场,代号是反引号包住的小写英文、不重复 ③ 域门牌是「中心/域」两层、中心已登记、文档路径就是「门牌/ARCH.md」、不重复登记 ④ 磁盘上每个域目录(含 ARCH.md 的目录)都在注册表登记 |
| NS-COMMON-0002 | arch 文档头完整性 | 阶段2 | 业务架构文档 frontmatter 七字段 + describes 四端键 + layer=business + status 枚举 + specRefs 非空则正文须引用(防第二真相源)+ specRefs 名字必须是存在的规范(V1.2.0 约束臂) |
| NS-COMMON-0003 | 业务域代码锁步 | 阶段2 | 业务组(锚在各域 ARCH.md)。调引擎的版本契约:域描述的代码与设计文件在封版之后改过、新增或删掉而没升版即红(锁清单逐文件比,代码原文比、改了哪个字都算改);施工中(已加新的一版还没封)只在带施工中开关的检测里放过(收尾、开发流 VERIFY、封版的检测前置) |
| NS-COMMON-0004 | 域目录成套 | 阶段2 | 有 ARCH.md 的域目录必须有同级 CHANGELOG.md(成套闸,防「只建正文不建日志」致日志回流 frontmatter) |
| NS-COMMON-0005 | 日志载体分离 | 阶段2 | 双臂。臂A:ARCH.md frontmatter 禁 version-log 键(防 ARCH-SYNC 把日志写回文档头)与退役的 srcHash 键;臂B:CHANGELOG.md frontmatter 禁 describes/srcHash/sourceOfTruth(防日志变第二真相源) |
| NS-COMMON-0006 | 域目录白名单 | 阶段2 | 域目录下只允许 ARCH.md / CHANGELOG.md / version-lock.json / README.md / ARCH.html / CHANGELOG.html / parts/ / adr/ / assets/ / modules/ / tools/(穷举白名单,防目录沦为杂物间;parts/ 是架构设计模板的视图页,modules/ / ARCH.html / CHANGELOG.html 是旧模板形态,只在还没迁过来的域里留着,由 NS-COMMON-0012 管退场) |
| NS-COMMON-0007 | 系统四件套成套 | 阶段2 | 系统组。三臂:规范 → 目录(已迁须有 ARCH.html + CHANGELOG.md 且规则书是条款书,未迁须登记在迁移名册)/ 目录 → 规范(目录名有同名判据、白名单 ARCH.html · CHANGELOG.md · version-lock.json · assets/)/ 迁移名册(排序、不重复、只登记存在的规范、登记数等于 ceiling,只减不增) |
| NS-COMMON-0008 | 架构页派生区保鲜 | 阶段2 | 系统组。逐区核对戳记:必需区齐全、载体对、data-v 等于引擎输出版本、data-out 等于产出指纹(没被直接改)、data-src 来源未变(没过期),普查快照须带日期;系统组注册表必须在场 |
| NS-COMMON-0009 | 四件套版本锁步 | 阶段2 | 系统组(锚在系统组注册表,全量检测)。对每个系统规范域调引擎的版本契约整单元判:变更历史写法(文档头 title / unit / kind、标题「## v主.次.补 · 日期 · 标题」、严格递减、一次只升一步、日期不倒挂、契约生效后的条目有标题有说明)、第一节等于规范简介版本、已封版且锁清单与第一节一致(含整段历史与名册)、判据条款与架构页原件封版后改过没升版即红 |
| NS-COMMON-0010 | 架构页原件完整与测试床验真 | 阶段2 | 系统组。原件区不残留占位符;测试床点名的闸真实存在、本规范每颗闸都被点名(无床写待补床)、点名的床在测试根下真实存在且内文写明所守的「规范名:规则号」 |
| NS-COMMON-0011 | 架构页遵循系统架构标准 | 阶段2 | 系统组(锚在标准名册 x-arch-standard.json)。四臂纯形态判定:① 节 id 全部来自冻结名册、出现顺序与名册一致、必填节齐全(条件节可缺)② 每个节带 data-index 与 data-kicker 编号属性 ③ 页面挂表达层(body 带页面类 + head 引共用样式表)④ 名册自洽(pending 排序不重复、只登记存在的域、登记数等于 ceiling)。名册登记为 pending 的域整条静默,改造完一份划掉一份并降 ceiling |
| NS-COMMON-0012 | 业务域遵循架构设计模板 | 阶段2 | 业务组(锚在各域 ARCH.md + 视图页 parts/*.html + 模板名册 x-arch-design-template.json)。一个业务域 = 七个视图(六页住 parts/,变更历史就是 CHANGELOG.md;视图清单以名册为准)。四臂:① 域 —— 名册里的视图页齐全、旧形态(modules/、ARCH.html、CHANGELOG.html)退场、parts/ 只放视图页 ② 视图页骨架 —— 节取自该视图的名册且顺序一致、必填齐全,场景与逐屏按前缀认且至少一节,流程设计每个场景先流程图后分步操作 ③ 表达层 —— body 带页面类,前两份样式表依次落在共用底座与视图画法(按落点判)④ 名册自洽(视图与节 id 合法不重复,pending 排序不重复、只许是冻结的立闸当日清单里真实存在的域、登记数等于 ceiling)。pending 里的域①臂静默,视图页不豁免;铺完的域报「同批划掉」 |
| NS-COMMON-0013 | 业务结构放置 | 阶段2 | 业务组(锚在每张表文档 + 各域 ARCH.md + 业务结构名册 x-arch-business-structure.json)。四臂:① 归属唯一(恰好一个域的 describes.data 覆盖,无主/重叠都红)② 上级写明(子表写「上级」、关系表写「两端」,声明的表存在且在字段里真实关联,主表不写)③ 放对一层(子与上级同域;关系两端同域则同域,跨域则归 kind: relation 且 relates 与两端所在域一致的关系域;关系域不许拥有主表)④ 名册自洽(两份 pending 排序不重复、登记项存在且仍违规、登记数等于各自 ceiling、只许是冻结的立闸当日存量的子集)。关联只认字段表格行里写成「关联 表.字段」且字段真实存在的(「同 / 取 / 引用 表.字段」这类提及不算);声明与关联先剥注释与代码块;同名多份表文档、忽略目录里的表文档即红 |
| NS-COMMON-0014 | 业务域版本锁步 | 阶段2 | 业务组(锚在各域 ARCH.md + CHANGELOG.md)。调引擎的版本契约整单元判(不比逐个文件,那一半归 NS-COMMON-0003):变更历史写法与顺序(一次只升一步)、ARCH.md 的 version 等于第一节(两个锚都报)、已封版且锁清单与第一节一致(含整段历史);施工中只在带施工中开关的检测里放过(收尾、开发流 VERIFY、封版的检测前置) |
| NS-COMMON-0015 | 业务总览版本锁步与无主业务代码只减不增 | 阶段2 | 业务组(锚在 .claude/arch/business/CHANGELOG.md 与 _context-map.md)。调引擎的版本契约判业务总览单元(跨域关系图与注册表):写法、版本、封版、封版后改过没升版;另判无主业务代码 —— 不归任何业务域的业务代码冻结在业务总览的锁清单里、只减不增,新出现的即红;业务总览的锁清单记业务域名册,新增、删掉业务域即报 |
// X-RULE-MULTILINE-END-x-standard-STD-COMMON-0002-NS规则行-X
// X-RULE-END-STANDARD-x-standard-STD-COMMON-0002-规则汇总表-P1-X
// X-RULE-BEGIN-STANDARD-x-standard-STD-COMMON-0003-STD和NS章节结构-P1-X
🎯 唯一标准格式(STD)
// X-RULE-MULTILINE-BEGIN-x-standard-STD-COMMON-0003-STD规则定义-X
⚠️ 说明:本规范为纯条件检测规范,所有规则均为 NS 类型(检测违规即报错),无 STD 模板。
// X-RULE-MULTILINE-END-x-standard-STD-COMMON-0003-STD规则定义-X
🔍 非标兜底检测(NS)
// X-RULE-MULTILINE-BEGIN-x-standard-STD-COMMON-0003-NS规则定义-X
---
// X-RULE-BEGIN-STANDARD-x-standard-STD-COMMON-0005-NS规则SLOT代码块-P1-X
NS-COMMON-0001:arch 注册表完整性(.claude/arch/business/_index.md 文件)
适用文件:
- 包含:
.claude/arch/business/_index.md - 排除:无
规则:arch 注册表(_index.md)是业务架构目录的唯一名册,四臂(V1.17.0 起):① 「已固化业务域」表格每个登记域第 2 列反引号包裹的架构文档路径必须真实存在(registry opt-in 下,登记即承诺有文档)② 「## 四大中心」一节必须在场,表格每行第 2 列是反引号包住的中心代号(小写英文,与后台菜单 localeKey 第一段同名),代号不重复 ③ 每个登记域的门牌(第 1 列)是「中心/域」两层小写英文、中心已在「四大中心」登记、文档路径就是「门牌/ARCH.md」(同一个域只有一个名字),不许重复登记 ④ 磁盘上 arch/business/ 下每个域目录(含 ARCH.md 的目录)都必须在注册表登记 —— 站点导航按注册表生成,不登记的域在导航里就不存在。防「登记了域却没建文档」「目录与注册表各说各的」「域游离在中心之外」三种失同步。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0001-arch注册表完整性-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const fs = require('fs');
const path = require('path');
const lines = content.split(/\r?\n/);
const archDir = path.join(workspaceRoot, '.claude', 'arch', 'business');
const push = (line, msg) => violations.push({ level: 'error', line: line || 1, lineViolations: [], message: '❌ [NS-COMMON-0001] ' + msg });
const cells = (l) => l.split('|').slice(1, -1).map((c) => c.trim());
const isRow = (l) => /^\|/.test(l) && !/^\|\s*:?-/.test(l);
const NAME = /^[a-z][a-z0-9-]*$/;
// 每一行属于哪一节(按「## 」切)
const sectionOf = [];
let cur = '';
for (const l of lines) { const h = /^##\s+(.+?)\s*$/.exec(l); if (h) cur = h[1]; sectionOf.push(cur); }
// 臂② 四大中心:代号写在第 2 列反引号里
const centers = new Set();
let centerSection = false;
for (let i = 0; i < lines.length; i++) {
if (!/^四大中心/.test(sectionOf[i])) continue;
centerSection = true;
if (!isRow(lines[i])) continue;
const c = cells(lines[i]);
if (c[0] === '中心') continue;
const code = /^`([^`]*)`$/.exec(c[1] || '');
if (!code || !NAME.test(code[1])) { push(i + 1, '「四大中心」这一行的代号必须是反引号包住的小写英文(与后台菜单 localeKey 第一段同名):' + lines[i].trim()); continue; }
if (!c[0]) push(i + 1, '中心「' + code[1] + '」没写中文名');
if (centers.has(code[1])) push(i + 1, '中心代号重复登记:' + code[1]);
centers.add(code[1]);
}
if (!centerSection) push(1, '注册表缺「## 四大中心」一节:业务架构目录的第一层是中心,中心先在这里登记,域才有门牌');
else if (!centers.size) push(1, '「四大中心」一节一个中心都没登记');
// 臂① + 臂③ 已固化业务域:markdown 表格行,第 2 列反引号包裹的 .md 文档路径(相对 arch/business/)
const rowRe = /^\|[^|]*\|\s*`([^`]+\.md)`\s*\|/;
const registered = new Set();
for (let i = 0; i < lines.length; i++) {
const m = lines[i].match(rowRe);
if (!m) continue;
const docRel = m[1].trim();
const id = cells(lines[i])[0];
if (!fs.existsSync(path.join(archDir, docRel))) push(i + 1, 'arch 注册表登记的业务域文档不存在:' + docRel + '\n\n违规行:' + lines[i].trim() + '\n\n注册表每个登记域必须有对应架构文档(存在性闸,防登记↔文档失同步)。');
const seg = id.split('/');
if (seg.length !== 2 || !NAME.test(seg[0]) || !NAME.test(seg[1])) { push(i + 1, '业务域门牌必须是「中心/域」两层小写英文(如 randd/menu),实为「' + id + '」'); continue; }
if (centerSection && !centers.has(seg[0])) push(i + 1, '业务域「' + id + '」的中心「' + seg[0] + '」没在「四大中心」一节登记 —— 先登记中心,或把域放进已登记的中心');
if (docRel !== id + '/ARCH.md') push(i + 1, '业务域「' + id + '」的文档路径必须就是「' + id + '/ARCH.md」(同一个域只有一个名字),实为「' + docRel + '」');
if (registered.has(id)) push(i + 1, '业务域重复登记:' + id);
registered.add(id);
}
// 臂④ 磁盘 → 注册表:含 ARCH.md 的目录就是域目录,每个都要登记(不再往域目录里面走)
const ignored = tools.ignoredDirs;
if (!Array.isArray(ignored)) throw new Error('NS-COMMON-0001 需要引擎注入的 tools.ignoredDirs(忽略目录名册),名册缺席不退回手抄');
const walk = (dir, rel) => {
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
if (!e.isDirectory() || ignored.indexOf(e.name) >= 0 || e.name.startsWith('.')) continue;
const r = rel ? rel + '/' + e.name : e.name;
const abs = path.join(dir, e.name);
if (fs.existsSync(path.join(abs, 'ARCH.md'))) {
if (!registered.has(r)) push(1, '磁盘上有业务域目录「' + r + '」却没在注册表登记:站点导航按注册表生成,不登记它就不存在。在「已固化业务域」表加一行「' + r + ' | `' + r + '/ARCH.md` | …」(门牌须是「已登记的中心/域」两层),或把目录挪到正确的门牌');
continue;
}
walk(abs, r);
}
};
if (fs.existsSync(archDir)) walk(archDir, '');
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0001-arch注册表完整性-P1-X
组成要素(强制要求):
// X-RULE-MULTILINE-BEGIN-x-standard-STD-COMMON-0005-组成要素列表-X
- ✅ 每个NS规则必须包含"检测逻辑代码"代码块(SLOT-X标记包裹的检测函数)
- ✅ 检测代码必须是JavaScript函数格式
- ✅ 每个NS规则必须包含"适用文件"声明
// X-RULE-MULTILINE-END-x-standard-STD-COMMON-0005-组成要素列表-X
// X-RULE-END-STANDARD-x-standard-STD-COMMON-0005-NS规则SLOT代码块-P1-X
NS-COMMON-0002:arch 文档头完整性(.claude/arch/business/**/ARCH.md 文件)
适用文件:
- 包含:
.claude/arch/business/**/ARCH.md - 排除:无(域目录化后「ARCH.md」即域文档身份锚点,「_index.md」/「_context-map.md」/「CHANGELOG.md」天然不匹配,无需字面排除)
规则:业务架构文档必须有合法 frontmatter:七字段(title/layer/status/version/describes/specRefs/sourceOfTruth)+ describes 四端键(data/server/admin/client,N/A 端显式 null)+ layer 必须 business(框架详图归 harness-engineering.md,不进 arch/business/)+ status 枚举(active/superseded/deprecated)+ specRefs 非空则正文须引用其名(I2 句法代理:arch 引用系统架构 rule 而不复述技术契约,防第二真相源漂移)。V1.2.0 约束臂:specRefs 里的每个名字必须是 references 下真实存在的规范 —— 业务架构对系统四件套只经这一个通道约束,写错名字即红。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0002-arch文档头完整性-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const lines = content.split(/\r?\n/);
// 基解析定位 frontmatter(首行须 ---,到次个 ---),避免裸 content 匹配(NS-COMMON-0024)。
let fmStart = -1, fmEnd = -1;
for (let i = 0; i < lines.length; i++) {
if (lines[i].trim() === '---') {
if (fmStart === -1) fmStart = i;
else { fmEnd = i; break; }
}
}
if (fmStart !== 0 || fmEnd === -1) {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] arch 业务架构文档缺合法 frontmatter(首行须 --- ... ---)`, lineViolations: [] });
return violations;
}
const fmLines = lines.slice(fmStart + 1, fmEnd);
const bodyLines = lines.slice(fmEnd + 1);
const hasKey = (k) => fmLines.some(l => new RegExp('^' + k + '\\s*:').test(l));
const getVal = (k) => {
const l = fmLines.find(x => new RegExp('^' + k + '\\s*:').test(x));
return l ? l.replace(new RegExp('^' + k + '\\s*:\\s*'), '').trim() : null;
};
for (const key of ['title', 'layer', 'status', 'version', 'describes', 'specRefs', 'sourceOfTruth']) {
if (!hasKey(key)) {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] arch 文档 frontmatter 缺字段:${key}`, lineViolations: [] });
}
}
const layer = getVal('layer');
if (layer && layer !== 'business') {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] arch 文档 layer 必须 business(实际:${layer});框架详图归 harness-engineering.md,不进 arch/business/`, lineViolations: [] });
}
const status = getVal('status');
if (status && !['active', 'superseded', 'deprecated'].includes(status)) {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] arch 文档 status 非法:${status}(仅 active/superseded/deprecated)`, lineViolations: [] });
}
// describes 四端键(缩进子键,直到下一顶层键)
const descIdx = fmLines.findIndex(l => /^describes\s*:/.test(l));
if (descIdx !== -1) {
const sub = [];
for (let j = descIdx + 1; j < fmLines.length; j++) {
if (/^\S/.test(fmLines[j])) break;
sub.push(fmLines[j]);
}
for (const end of ['data', 'server', 'admin', 'client']) {
if (!sub.some(l => new RegExp('^\\s+' + end + '\\s*:').test(l))) {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] arch 文档 describes 缺四端键:${end}(N/A 端显式 ${end}: null)`, lineViolations: [] });
}
}
// ★值域臂(2026-09-21 对抗审查实测立)★ 非 null 端的每条 glob,其 base 目录必须真实存在。
// 病根(当时锁步靠文档头的签名):describes 指向不存在的目录 ⇒ 实算文件集为空 ⇒ 签名与声明相等 ⇒ 零违规(已实测)。
// 版本契约下同一件事照样成立:目录不存在 ⇒ 这个域认领不到任何代码 ⇒ 锁清单是空的、改哪里都不报。
// 于是被保鲜闸拦下时最省力的动作不是回看设计,而是把那一端的 glob 改成一条死路径,
// 该端从此永久绿且零告警 —— 保鲜闸唯一的输入被它自己的被检对象握着,这一臂是把输入锁住。
// 射程只到「路径存不存在」:把某端整个改成 null 仍然合法(那是 diff 里一眼可见的显式动作,
// 归提交审查),此处不引入第二本登记账。
const fsDS = require('fs');
const pathDS = require('path');
for (const l of sub) {
const mDS = l.match(/^\s+(data|server|admin|client)\s*:\s*(.*)$/);
if (!mDS) continue;
for (const raw of (mDS[2].match(/["']([^"']+)["']/g) || [])) {
const g = raw.replace(/["']/g, '');
// ★V1.11.0 写法臂★ 只接受「目录/**」:当时的代码锁步按目录走,单个文件、中段通配、.json 等写法一律静默算成「没有代码」;
// 版本契约下单个文件能认领了,但与目录认领混写,归属与重叠就判不准 —— 写法仍只许一种
// (0003 的 walk 遇到非目录直接返回、中段通配被截成上一级目录或截空),声明 null 与实算 null 恰好相等 ⇒ 永久免疫。
// 2026-09-22 菜单方案对抗检查用真判据实测:三种写法在 0003 零违规、0002 也放行。这里在入口把形态锁死。
if (!/^[^*?\[\]{}]+\/\*\*$/.test(g)) {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] describes.${mDS[1]} 写法不被支持:${g}\n\n只接受「目录/**」这一种写法(例如 x-server/admin/system/menu/**)。业务域按目录认领代码:单个文件、中段带通配的路径与目录认领混着写,归属与重叠(两个域认领同一个文件)就判不准。\n改法:改成它所在目录的「目录/**」;那个目录里还有别的域的代码、没法整目录认领,就不要写进来,在正文的诚实边界里写明它不受代码锁步管、由哪颗闸守着。`, lineViolations: [] });
continue;
}
const base = g.slice(0, -3);
// ★V1.11.1 别名臂★ 同一个目录换个写法(./ 开头、// 重复、中段 ./ 或 ../、大小写不同)在保鲜闸里照样能走进去,
// 而放置闸按字面前缀比对「谁覆盖了哪张表」—— 于是第二个域用别名认领同一张表,重叠臂看不见(对抗检查实测)。
// 这里把写法锁成唯一的规范形态:与 posix 规范化结果逐字相等、且大小写与磁盘上的真实目录逐字相等。
if (pathDS.posix.normalize(base) !== base || base.startsWith('./') || base.startsWith('/') || /(^|\/)\.\.?(\/|$)/.test(base)) {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] describes.${mDS[1]} 的路径不是规范写法:${g}\n\n同一个目录只许有一种写法:从仓库根写起、不带 ./ 或 ../、不重复斜杠(例如 x-data/customer/**)。换个写法指向同一个目录,会让「一张表只能有一个主」的检查认不出两个域认领了同一张表。`, lineViolations: [] });
continue;
}
if (fsDS.existsSync(pathDS.join(workspaceRoot, base))) {
const realRel = pathDS.relative(workspaceRoot, fsDS.realpathSync.native(pathDS.join(workspaceRoot, base))).replace(/\\/g, '/');
if (realRel !== base) {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] describes.${mDS[1]} 的路径大小写与磁盘上不一致:写的是 ${base},磁盘上是 ${realRel}\n\n照磁盘上的真实写法改(Windows 不分大小写,换个大小写也能指到同一个目录,会让重叠检查认不出来)。`, lineViolations: [] });
continue;
}
}
if (fsDS.existsSync(pathDS.join(workspaceRoot, base)) && !fsDS.statSync(pathDS.join(workspaceRoot, base)).isDirectory()) {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] describes.${mDS[1]} 指向的是文件不是目录:${g}\n\n代码锁步只会走进目录,指向文件等于该端永远算成「没有代码」。改成所在目录的「目录/**」。`, lineViolations: [] });
continue;
}
if (!fsDS.existsSync(pathDS.join(workspaceRoot, base))) {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] describes.${mDS[1]} 指向不存在的路径:${g}(base「${base}」不存在)\n\n死路径会让代码锁步静默失效:这一端锁住的文件集为空,改了真代码也不会有任何一个文件对不上,等于该端永久免疫。\n改法二选一:把 glob 改成真实路径;或该域确实与此端无关,就写 ${mDS[1]}: null(显式、可审)。`, lineViolations: [] });
}
}
}
}
// I2 句法代理:specRefs 非空 ⇒ 正文含其名(防第二真相源)
const specRefsLine = fmLines.find(l => /^specRefs\s*:/.test(l));
if (specRefsLine) {
const inside = (specRefsLine.match(/\[([^\]]*)\]/) || [null, ''])[1];
const refs = inside.split(',').map(s => s.replace(/["'\s]/g, '')).filter(Boolean);
for (const ref of refs) {
if (!bodyLines.some(l => l.indexOf(ref) !== -1)) {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] specRefs 声明 ${ref} 但正文无引用(第二真相源风险:arch 引用系统架构 rule 不复述其技术契约)`, lineViolations: [] });
}
}
// V1.2.0 约束臂:specRefs 里的名字必须是真实存在的规范(业务架构对系统四件套只经这一个通道约束)
const fsSR = require('fs');
const pathSR = require('path');
const refsDirSR = pathSR.join(workspaceRoot, pathSR.relative(workspaceRoot, filePath).replace(/\\/g, '/').split('/arch/')[0], 'skills', 'x-spec-checker', 'references');
for (const ref of refs) {
if (!fsSR.existsSync(pathSR.join(refsDirSR, ref + '-spec.md'))) {
violations.push({ level: 'error', line: 1, message: `❌ [NS-COMMON-0002] specRefs 声明的 ${ref} 不是存在的规范(references 下没有 ${ref}-spec.md):业务架构只能引用真实存在的系统规范`, lineViolations: [] });
}
}
}
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0002-arch文档头完整性-P1-X
NS-COMMON-0003:业务域代码锁步(.claude/arch/business/**/ARCH.md 文件)
适用文件:
- 包含:
.claude/arch/business/**/ARCH.md - 排除:无(同 NS-COMMON-0002,身份锚点即天然边界)
规则:业务域描述的代码(文档头 describes 四端所指目录下、按端取的文件:数据表的 datasource、云函数与移动端的 js 与 wxml、后台的 ts 与 tsx;自动生成的文件不算)与域目录里的设计文件,封版时由统一封版命令逐个文件记进域的锁清单 version-lock.json(代码原文比,注释、空白、import 顺序改了也算改;数据表比完整结构,字段、必填、唯一、选项集、长度都算)。封版之后改过、新增或删掉任何一个而没升版即红 —— 要么在变更历史最上面加新的一版、回看设计、封版,要么把改动撤回。施工中(变更历史第一节已经比锁清单新、还没封)只在带施工中开关的检测里放过(收尾、开发流 VERIFY 与封版的检测前置;引擎经 tools.versionWip 注入),全量检测与发布一律不放;施工中照样不许动已封的那一版与它下面的旧版。一个文件被两个域认领,两个都要升。本闸只是薄壳:判定住检测引擎的版本契约(tools.versionContract,三层同一份代码),闸不另写指纹算法与名册。逐个文件的报红(改动当轮在改的那个文件上报)由引擎内置的版本契约一段承担,本闸锚在 ARCH.md 上汇总成一条。诚实边界:锁步证明「描述域代码被改了、改完升了版」,不证明设计还对 —— 回看是否真做了靠人审;不改代码的变化(线上数据、控制台配置)它看不见。srcHash 退役(V2.0.0):此前四端各一个签名写在文档头,改一行代码只知道「这一端变了」,也没有地方记「这一版封的是哪份代码」;锁清单逐个文件记下,封版命令同时写出改动清单。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0003-业务域代码锁步-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const path = require('path');
const push = (msg) => violations.push({ level: 'error', line: 1, lineViolations: [], message: '❌ [NS-COMMON-0003] ' + msg });
// 判定住引擎的版本契约(三层同一份代码);没注入就判不了 —— 判不了不算过
const VC = tools.versionContract;
if (!VC || typeof VC.unitDrift !== 'function') { push('引擎没有注入版本契约(tools.versionContract),代码锁步判不了'); return violations; }
const rel = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
const unit = VC.index(workspaceRoot).units.find((u) => u.layer === 'business' && u.truthFile === rel);
if (!unit) return violations; // 不是业务域的设计文档(业务总览归 NS-COMMON-0015)
const drift = VC.unitDrift(workspaceRoot, unit, { wip: !!tools.versionWip });
if (drift) push(drift);
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0003-业务域代码锁步-P1-X
NS-COMMON-0004:域目录成套(.claude/arch/business/**/ARCH.md 文件)
适用文件:
- 包含:
.claude/arch/business/**/ARCH.md - 排除:无
规则:域目录(含 ARCH.md 的目录,身份锚点)必须同时有同级 CHANGELOG.md。版本日志自 frontmatter 迁出后,日志载体是域目录的必备构件;缺失即意味着「日志无处可去」,下一次 ARCH-SYNC 必然把 version-log 写回 ARCH.md 文档头(与 NS-COMMON-0005 臂A 构成防回流双保险)。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0004-域目录成套-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const fs = require('fs');
const path = require('path');
const dir = path.dirname(path.isAbsolute(filePath) ? filePath : path.join(workspaceRoot, filePath));
if (!fs.existsSync(path.join(dir, 'CHANGELOG.md'))) {
violations.push({
level: 'error',
line: 1,
message: `❌ [NS-COMMON-0004] 域目录缺 CHANGELOG.md(有 ARCH.md 必须成套)\n\n域目录:${path.relative(workspaceRoot, dir).replace(/\\/g, '/')}\n\n版本日志载体缺失 ⇒ 下次 ARCH-SYNC 会把 version-log 写回 ARCH.md frontmatter(回流)。补建同级 CHANGELOG.md(文档头只放 title / unit / kind,条目写成「## v主.次.补 · YYYY-MM-DD · 一句标题」;禁 describes/srcHash/sourceOfTruth,见 NS-COMMON-0005 臂B)。`,
lineViolations: [],
});
}
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0004-域目录成套-P1-X
NS-COMMON-0005:日志载体分离(.claude/arch/business/**/ARCH.md、.claude/arch/business/**/CHANGELOG.md 文件)
适用文件:
- 包含:
.claude/arch/business/**/ARCH.md、.claude/arch/business/**/CHANGELOG.md - 排除:无
规则:设计正文与版本日志物理分居、互不侵入,双臂强制。臂A(防回流):ARCH.md frontmatter 禁出现 version-log 键——日志已迁 CHANGELOG.md,写回文档头会让读设计者被迫吞下历史流水(该形态曾使 order 域 frontmatter 占全文 56.5%);也禁出现 V2.0.0 退役的 srcHash 键——代码锁步改由锁清单逐文件记,文档头里再写一份签名就是两套账,读者会以为它还在起作用。臂B(防第二真相源):CHANGELOG.md frontmatter 禁出现 describes / srcHash / sourceOfTruth——这三个键是设计真相源的身份标记,出现在日志上即制造两套账,且会诱使读者把日志当成设计。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0005-日志载体分离-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const norm = String(filePath).replace(/\\/g, '/');
const isChangelog = /\/CHANGELOG\.md$/.test(norm);
const lines = content.split(/\r?\n/);
// frontmatter 定位(基解析,避裸 content 匹配)
let fmS = -1, fmE = -1;
for (let i = 0; i < lines.length; i++) {
if (lines[i].trim() === '---') { if (fmS === -1) fmS = i; else { fmE = i; break; } }
}
if (fmS !== 0 || fmE === -1) return violations; // ARCH.md 归 NS-COMMON-0002;CHANGELOG 无 frontmatter 不设强制
const fm = lines.slice(fmS + 1, fmE);
const hit = (k) => fm.findIndex((l) => new RegExp('^' + k + '\\s*:').test(l));
if (!isChangelog) {
// 臂A:ARCH.md 禁 version-log(日志回流)与退役的 srcHash(V2.0.0:代码锁步改由锁清单逐文件记)
const i = hit('version-log');
if (i !== -1) {
violations.push({
level: 'error',
line: fmS + 2 + i,
message: `❌ [NS-COMMON-0005 臂A] ARCH.md frontmatter 禁出现 version-log 键(日志回流)\n\n版本日志的唯一载体是同级 CHANGELOG.md。写回文档头 ⇒ 读设计被迫吞历史流水。\n把该键下的全部条目迁入 CHANGELOG.md(形如 \`## v{版本} · {YYYY-MM-DD} · 一句标题\` 分节),并删除本键。`,
lineViolations: [],
});
}
const s = hit('srcHash');
if (s !== -1) {
violations.push({
level: 'error',
line: fmS + 2 + s,
message: `❌ [NS-COMMON-0005 臂A] ARCH.md frontmatter 禁出现已退役的 srcHash 键\n\n代码锁步改由域的锁清单 version-lock.json 逐个文件记(统一封版命令写),文档头里再写一份签名就是两套账,读者会以为它还在起作用。删掉这个键。`,
lineViolations: [],
});
}
} else {
// 臂B:CHANGELOG.md 禁真相源身份键
for (const k of ['describes', 'srcHash', 'sourceOfTruth']) {
const i = hit(k);
if (i !== -1) {
violations.push({
level: 'error',
line: fmS + 2 + i,
message: `❌ [NS-COMMON-0005 臂B] CHANGELOG.md frontmatter 禁出现真相源身份键:${k}\n\n该键是设计真相源(ARCH.md)的身份标记,出现在日志载体上=两套账。\nCHANGELOG.md 的文档头只放 title / unit / kind。`,
lineViolations: [],
});
}
}
}
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0005-日志载体分离-P1-X
NS-COMMON-0006:域目录白名单(.claude/arch/business/**/ARCH.md 文件)
适用文件:
- 包含:
.claude/arch/business/**/ARCH.md - 排除:无
规则:域目录下只允许穷举白名单内的条目——文件 ARCH.md(LEVEL A 设计真相源)/ CHANGELOG.md(版本日志载体)/ version-lock.json(锁清单,V2.0.0 起:统一封版命令逐个文件记下封版时的设计与代码,只由封版命令写)/ README.md(域内导读)/ ARCH.html(LEVEL A 阅读视图)/ CHANGELOG.html(日志阅读视图),子目录 parts/(架构设计模板的视图页,形态由 NS-COMMON-0012 判)/ adr/(架构决策记录)/ assets/(可视化产物与概念图素材)/ modules/(旧模板的业务模块页)/ tools/(域内构建器,如从 CHANGELOG.md 生成 assets/changelog-data.js 的那一个)。零豁免。V1.9.1 扩面登记:modules/ 是当时 NS-COMMON-0012 立的标准落点,不收它两颗闸当场自相矛盾;其余四项是客户域这个 MVP 已经长出来、且职责说得清的形态。V1.15.0 起业务架构换成《架构设计模板》的六个视图:parts/ 的含义从「分支架构」改成五个视图页的住处(此前全仓没有一个域用过它);modules/、ARCH.html、CHANGELOG.html 成为旧模板形态 —— 本闸仍允许它们存在(14 个域还没迁过来),退场由 NS-COMMON-0012 管:一个域不在那颗闸的名册里,它们就当场报红。诚实边界:ARCH.html 是手写的第二份叙述、与 ARCH.md 之间没有任何指纹锁步,这处「两套账」随迁到六视图一起消失,不在本闸射程内。防「域目录化」退化成杂物间:任何未登记形态的文件落进域目录,都是无人看管的野文件(不受任何 arch 闸保护,却坐在真相源旁边冒充真相)。新形态需求必须先扩本白名单(走 /x-meta-dev),而非直接落盘。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0006-域目录白名单-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const fs = require('fs');
const path = require('path');
const ALLOW_FILES = ['ARCH.md', 'CHANGELOG.md', 'version-lock.json', 'README.md', 'ARCH.html', 'CHANGELOG.html'];
const ALLOW_DIRS = ['parts', 'adr', 'assets', 'modules', 'tools'];
const dir = path.dirname(path.isAbsolute(filePath) ? filePath : path.join(workspaceRoot, filePath));
let entries = [];
try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return violations; }
const rel = path.relative(workspaceRoot, dir).replace(/\\/g, '/');
for (const e of entries) {
const ok = e.isDirectory() ? ALLOW_DIRS.indexOf(e.name) !== -1 : ALLOW_FILES.indexOf(e.name) !== -1;
if (!ok) {
violations.push({
level: 'error',
line: 1,
message: `❌ [NS-COMMON-0006] 域目录出现白名单外条目:${e.isDirectory() ? e.name + '/' : e.name}\n\n域目录:${rel}\n允许:文件 ARCH.md / CHANGELOG.md / version-lock.json / README.md / ARCH.html / CHANGELOG.html,子目录 parts/ / adr/ / assets/ / modules/ / tools/\n\n未登记形态=无人看管的野文件(不受任何 arch 闸保护,却坐在真相源旁边)。要新增形态先扩白名单(走 /x-meta-dev),别直接落盘。`,
lineViolations: [],
});
}
}
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0006-域目录白名单-P1-X
NS-COMMON-0007:系统四件套成套(x-arch-system.json、.claude/arch/system/** 文件)
适用文件:
- 包含:
.claude/skills/x-spec-checker/references/x-arch-system.json、.claude/arch/system/** - 排除:无
规则:系统架构层 .claude/arch/system/ 与规范文件一一对应,三臂强制。臂A(规范 → 目录,锚在系统组注册表,全局核对一次):references 下每份规范(元规范 x-standard 除外,其设计留在 harness)要么已迁 —— 有同名目录、目录里有 ARCH.html 与 CHANGELOG.md、规则书是条款书(frontmatter 声明 ruleFormat);要么登记在迁移名册 pending 里 —— 此时不得已有目录,规则书也不得已是条款书(迁了一半)。臂B(目录 → 规范,锚在目录里的文件,改目录当轮咬):arch/system/ 下每个目录名必须有同名判据文件、不得是 x-standard;目录里只允许 ARCH.html、CHANGELOG.md、锁清单 version-lock.json(V2.0.0 起,只由统一封版命令写)与 assets/,前两份文件缺一不可;arch/system/ 根下不许放文件。臂C(迁移名册,锚在注册表):pending 按名称排序、不重复、只登记存在的规范且不含 x-standard;登记数必须等于 ceiling —— 名册只减不增,迁完一份同批划掉并把 ceiling 降到登记数(抬高 ceiling 同样是改判据,走 sync 升版并记变更历史,由人审提交把关)。新建的规范直接走 /x-meta-dev 的 tetrad 建整套,不进名册。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0007-系统四件套成套-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const fs = require('fs');
const path = require('path');
const T = tools.tetradParser;
const rel = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
const push = (msg) => violations.push({ level: 'error', line: 1, lineViolations: [], message: '❌ [NS-COMMON-0007] ' + msg });
const onRegistry = /\/skills\/x-spec-checker\/references\/x-arch-system\.json$/.test('/' + rel);
const treeRel = onRegistry ? rel.split('/skills/')[0] : rel.split('/arch/system/')[0];
const refsDir = path.join(workspaceRoot, treeRel, 'skills', 'x-spec-checker', 'references');
const systemDir = path.join(workspaceRoot, treeRel, 'arch', 'system');
const rulesDir = path.join(workspaceRoot, treeRel, 'rules');
const isClauseBook = (name) => {
const rp = path.join(rulesDir, name + '-rule.md');
if (!fs.existsSync(rp)) return false;
const fm = T.parseRuleFrontmatter(fs.readFileSync(rp, 'utf-8'));
return !!(fm && fm.ruleFormat !== null);
};
if (onRegistry) {
let reg = null;
try { reg = JSON.parse(tools.filtered.codeOnly); } catch (e) { push('系统组注册表不是合法 JSON:' + e.message); return violations; }
const pending = reg && Array.isArray(reg.pending) ? reg.pending : null;
if (!pending) { push('系统组注册表缺迁移名册数组 pending'); return violations; }
if (typeof reg.ceiling !== 'number') push('系统组注册表缺数字上限 ceiling');
else if (pending.length !== reg.ceiling) push('迁移名册登记 ' + pending.length + ' 份、上限 ceiling 为 ' + reg.ceiling + ':名册只减不增,划掉一份就同批把 ceiling 降到登记数');
if (pending.slice().sort().join('\n') !== pending.join('\n')) push('迁移名册须按名称排序(增减一眼可审)');
const seen = new Set();
for (const p of pending) {
if (seen.has(p)) push('迁移名册重复登记 ' + p);
seen.add(p);
if (p === 'x-standard') push('迁移名册不得登记元规范 x-standard(其设计留在 harness,不设系统架构目录)');
else if (!fs.existsSync(path.join(refsDir, p + '-spec.md'))) push('迁移名册登记的 ' + p + ' 没有判据文件:规范已删除就从名册划掉并降 ceiling');
}
let specs = [];
try { specs = fs.readdirSync(refsDir).filter((f) => /^x-[a-z0-9-]+-spec\.md$/.test(f)).map((f) => f.replace(/-spec\.md$/, '')).sort(); } catch (e) { specs = []; }
for (const name of specs) {
if (name === 'x-standard') continue;
const dir = path.join(systemDir, name);
if (seen.has(name)) {
if (fs.existsSync(dir)) push(name + ' 已建系统架构目录却仍在迁移名册里:迁完就从名册划掉并同批降 ceiling');
if (isClauseBook(name)) push(name + ' 的规则书已是条款书却仍在迁移名册里(迁了一半):迁完就从名册划掉并同批降 ceiling');
continue;
}
if (!fs.existsSync(path.join(dir, 'ARCH.html'))) push(name + ' 不在迁移名册、却缺系统架构页 ' + treeRel + '/arch/system/' + name + '/ARCH.html → 走 /x-meta-dev tetrad 建四件套');
if (!fs.existsSync(path.join(dir, 'CHANGELOG.md'))) push(name + ' 不在迁移名册、却缺变更历史 ' + treeRel + '/arch/system/' + name + '/CHANGELOG.md → 走 /x-meta-dev tetrad 建四件套');
if (!isClauseBook(name)) push(name + ' 不在迁移名册、规则书却不是条款书:frontmatter 须声明 ruleFormat: "clauses-v1" 并按条款书固定格式改写');
}
return violations;
}
const parts = rel.split('/arch/system/')[1].split('/');
if (parts.length === 1) { push('系统架构根目录下只允许规范目录,不许放文件:' + rel); return violations; }
const name = parts[0];
const dir = path.join(systemDir, name);
// 目录级判定只从一个锚点报一次(有 ARCH.html 用它,否则 CHANGELOG.md;两者都没有则目录里每个文件各报一次)
const anchor = fs.existsSync(path.join(dir, 'ARCH.html')) ? 'ARCH.html' : (fs.existsSync(path.join(dir, 'CHANGELOG.md')) ? 'CHANGELOG.md' : null);
const reportHere = anchor === null || parts.slice(1).join('/') === anchor;
if (reportHere) {
if (name === 'x-standard') push('元规范 x-standard 的设计留在 harness,不建系统架构目录');
else if (!/^x-[a-z][a-z0-9-]*$/.test(name) || !fs.existsSync(path.join(refsDir, name + '-spec.md'))) push('系统架构目录 ' + name + ' 没有同名判据文件:每个目录必须对应 references 里的一份规范');
let entries = [];
try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { entries = []; }
for (const e of entries) {
const ok = e.isDirectory() ? e.name === 'assets' : (e.name === 'ARCH.html' || e.name === 'CHANGELOG.md' || e.name === 'version-lock.json');
if (!ok) push('系统架构目录 ' + name + ' 出现白名单外条目 ' + e.name + (e.isDirectory() ? '/' : '') + '(只允许 ARCH.html、CHANGELOG.md、version-lock.json 与 assets/)');
}
for (const must of ['ARCH.html', 'CHANGELOG.md']) {
if (!fs.existsSync(path.join(dir, must))) push('系统架构目录 ' + name + ' 缺 ' + must);
}
}
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0007-系统四件套成套-P1-X
NS-COMMON-0008:架构页派生区保鲜(.claude/arch/system/*/ARCH.html 文件)
适用文件:
- 包含:
.claude/arch/system/*/ARCH.html - 排除:无
规则:架构页的派生区(外壳样式、外壳脚本、版本与新鲜度头、条款总表、判据总表、注册表面板、普查快照)只准 x-meta-dev 的派生区引擎产出,检测端逐区核对戳记:① 区的形态合法(三种载体、不嵌套、不重名)② 引擎清单(x-meta-dev 骨架 manifest.json)要求的区一个不缺、不出现清单外的区、载体对得上 ③ data-v 等于引擎当前输出版本(引擎改了输出须升号并全量刷新)④ data-out 等于「声明属性 + 正文」的产出指纹,不等即被直接改过 ⑤ data-src 列出的每个来源文件都存在、内容指纹未变,变了即过期(普查快照不锁代码新鲜,但须带快照日期)⑥ 系统组注册表必须在场(它是成套与版本锁步两颗全局闸的锚点,删掉它两颗闸就失去锚点)。改页面当轮咬;只改条款书、判据或注册表时页面过期由全量检测报出,sync 会顺手刷新。诚实边界:戳记证「没被直接改、来源没变」,不证「引擎没写错」—— 后者由 x-meta-dev validate 第 10 项与测试床的逐字重新生成比对兜住;刻意伪造戳记靠人审提交。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0008-架构页派生区保鲜-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const fs = require('fs');
const path = require('path');
const T = tools.tetradParser;
const rel = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
const treeRel = rel.split('/arch/system/')[0];
const push = (line, msg) => violations.push({ level: 'error', line: line || 1, lineViolations: [], message: '❌ [NS-COMMON-0008] ' + msg });
if (!fs.existsSync(path.join(workspaceRoot, treeRel, 'skills', 'x-spec-checker', 'references', 'x-arch-system.json'))) {
push(1, '系统组注册表 x-arch-system.json 缺失:成套闸 NS-COMMON-0007 与版本锁步闸 NS-COMMON-0009 就此失去锚点');
}
const manifestRel = treeRel + '/skills/x-meta-dev/assets/arch-skeleton/manifest.json';
let manifest = null;
try { manifest = JSON.parse(fs.readFileSync(path.join(workspaceRoot, manifestRel), 'utf-8')); } catch (e) { push(1, '架构页引擎清单读不到:' + manifestRel + '(' + e.message + ')'); return violations; }
const required = manifest.requiredRegions || {};
const prefixes = manifest.optionalRegionPrefixes || {};
// 戳记按原文核对:派生区正文本身就含样式与脚本,任何剥离视图都会改变正文与指纹(结构核对,非业务关键词匹配)
const parsed = T.parseArchRegions(content);
for (const e of parsed.errors) push(e.line, e.message);
for (const name of Object.keys(required)) {
if (!parsed.regions.some((r) => r.name === name)) push(1, '缺必需派生区「' + name + '」(<' + required[name] + '> 载体)→ 跑 /x-meta-dev sync');
}
const hashCache = new Map();
for (const r of parsed.regions) {
let carrier = required[r.name];
let census = false;
if (!carrier) {
for (const p of Object.keys(prefixes)) {
if (r.name.indexOf(p) === 0 && r.name.length > p.length) { carrier = prefixes[p]; census = p === 'census-'; }
}
}
if (!carrier) { push(r.line, '不认识的派生区「' + r.name + '」(引擎清单只认 ' + Object.keys(required).join(' / ') + ' 与前缀 ' + Object.keys(prefixes).join(' / ') + ')'); continue; }
if (r.carrier !== carrier) push(r.line, '派生区「' + r.name + '」须用 <' + carrier + '> 载体(实为 <' + r.carrier + '>)');
if (r.attrs['data-v'] !== String(manifest.outputVersion)) push(r.line, '派生区「' + r.name + '」的输出版本 ' + (r.attrs['data-v'] || '(缺)') + ' 不是引擎当前版本 ' + manifest.outputVersion + ' → 跑 /x-meta-dev sync 全量刷新');
if (r.attrs['data-out'] !== T.regionOutHash(r)) push(r.line, '派生区「' + r.name + '」被直接改过(正文或声明与产出指纹不符,派生区禁直接改)→ 跑 /x-meta-dev sync 重新生成');
if (census && !/^\d{4}-\d{2}-\d{2}$/.test(r.attrs['data-snapshot'] || '')) push(r.line, '普查快照「' + r.name + '」缺快照日期 data-snapshot');
if (r.attrs['data-src'] === undefined) { push(r.line, '派生区「' + r.name + '」缺来源戳 data-src'); continue; }
const st = T.parseSourceStamp(r.attrs['data-src']);
for (const e of st.errors) push(r.line, '派生区「' + r.name + '」:' + e.message);
if (!census && !st.entries.length && !st.errors.length) push(r.line, '派生区「' + r.name + '」的来源戳为空');
for (const e of st.entries) {
const abs = path.join(workspaceRoot, e.path);
if (!hashCache.has(abs)) hashCache.set(abs, fs.existsSync(abs) ? T.hashText(fs.readFileSync(abs, 'utf-8')) : null);
const h = hashCache.get(abs);
if (h === null) push(r.line, '派生区「' + r.name + '」的来源文件不存在:' + e.path);
else if (h !== e.hash) push(r.line, '派生区「' + r.name + '」已过期:来源 ' + e.path + ' 变了(戳记 ' + e.hash + ',现为 ' + h + ')→ 跑 /x-meta-dev sync 刷新');
}
}
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0008-架构页派生区保鲜-P1-X
NS-COMMON-0009:四件套版本锁步(x-arch-system.json 文件)
适用文件:
- 包含:
.claude/skills/x-spec-checker/references/x-arch-system.json - 排除:无
规则:(锚在系统组注册表,对每个系统规范域全局核对一次)版本号只写在规范简介一处,变更历史与锁清单与它锁步。判定住检测引擎的版本契约(tools.versionContract,三层同一份代码),本闸只是薄壳:① 变更历史写法 —— 文档头恰为 title / unit / kind(unit 为「spec:规范名」、title 以「变更历史」结尾),每个二级标题都是「## v主.次.补 · YYYY-MM-DD · 一句标题」(契约生效之前的旧条目可以没有标题),自上而下版本严格递减、一次只升一步(升了哪一位后面的位归零)、日期不倒挂,契约生效之后的条目有标题、有说明;② 第一节等于规范简介的当前版本;③ 第一节已封版(统一封版命令写下设计指纹与内容指纹),锁清单 version-lock.json 自洽且与第一节一致、记全日期与标题说明与测试行与改动行与整段历史(这一版到文件末尾,旧版一个字不能改),x-arch 自己的锁清单另记系统规范域名册;④ 封版之后判据(正文与同前缀注册表)、条款书的条款、架构页的原件改过、新增或删掉而没升版即红(派生区与文档头不算)。施工中(第一节已加、还没封)只在带施工中开关的检测里放过(收尾、开发流 VERIFY、封版的检测前置),全量检测与发布照红。为什么锚在注册表:施工中改变更历史是常态,锁步放进全量检测(提交前必跑),逐个文件的改动由引擎内置的版本契约一段在改动当轮报。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0009-四件套版本锁步-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const push = (name, line, msg) => violations.push({ level: 'error', line: 1, lineViolations: [], message: '❌ [NS-COMMON-0009] ' + name + ' 变更历史' + (line ? '第 ' + line + ' 行' : '') + ':' + msg });
// 判定住引擎的版本契约(三层同一份代码);没注入就判不了 —— 判不了不算过
const VC = tools.versionContract;
if (!VC || typeof VC.checkUnit !== 'function') { push('(全部)', 0, '引擎没有注入版本契约(tools.versionContract),版本锁步判不了'); return violations; }
for (const u of VC.index(workspaceRoot).units.filter((x) => x.layer === 'system')) {
for (const v of VC.checkUnit(workspaceRoot, u, { wip: !!tools.versionWip })) push(u.name, v.line, v.message);
}
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0009-四件套版本锁步-P1-X
NS-COMMON-0010:架构页原件完整与测试床验真(.claude/arch/system/*/ARCH.html 文件)
适用文件:
- 包含:
.claude/arch/system/*/ARCH.html - 排除:无
规则:架构页原件区(派生区以外的正文)不得残留骨架占位符「【待写】」;测试床点名(带 data-bed 与 data-guards 的元素)逐条核对:① data-guards 里每个「规范名:规则号」真实存在,每个「规范名:ARCH-条款号」在该规范的条款书(rules/<规范名>-rule.md)里真实存在 ② 本规范的每颗闸至少出现在一条点名里 —— 有床写床,没有床写「待补床」(页面上标红,债务一眼可见)③ 点名的床必须是仓根相对、位于测试根下(测试根只认引擎常量 constants/test-roots.js,判据经 tools.isTestPath 判)的 .test.js 文件且真实存在,床的内文写着它守的每个「规范名:规则号」与「规范名:ARCH-条款号」(点名守护某颗闸或条款,床里就得写明是哪颗)④ 床的种类写实(V1.4.0):不写 data-bed-kind 的床是「跑本规范判据的床」,床文件剥掉注释后必须按调用形态出现引擎令牌之一(V1.6.0)—— 函数令牌 extractNsRuleDetector( / buildDetectorTools( / checkStandardFormat( 写成调用,check.js 作为路径段出现(前面紧挨斜杠、反斜杠或引号,后面紧挨引号、空白或行尾),X-RULE-BEGIN-SLOT(手抠 SLOT 块喂引擎的写法)出现在注释以外;写 data-bed-kind="invariant" 的床是「守不变量、不跑判据的床」,不查引擎调用;data-bed-kind 只许 invariant 一个值 ⑤ 三处「点名在、床却不算数」(V1.19.0):解析点名之前先剥掉 HTML 注释(被注释掉的点名不算数);床内文里的「规范名:编号」按完整编号认(前后都不许紧挨字母、数字、下划线或连字符);点名的床不许住在唯一运行器不收床的目录里(只看测试根里面的目录段,测试根前缀的长度经 tools.isTestPath 量;目录谓词经引擎注入的 tools.isTestSkipDir 判:夹具、依赖、以「.」或「zz」开头)。诚实边界:证得了床存在、写了完整闸号、住在唯一运行器会收的目录、床的代码里(注释以外)有调用引擎的形态,证不了那次调用真的执行了、更证不了床喂进引擎的样本有没有真测到那颗闸的判据 —— 字符串字面量里写一段调用形态同样被认作调用,反向注入质量归床自己的断言与人审。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0010-架构页原件完整与测试床验真-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const fs = require('fs');
const path = require('path');
const T = tools.tetradParser;
const rel = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
const treeRel = rel.split('/arch/system/')[0];
const name = rel.split('/arch/system/')[1].split('/')[0];
const push = (line, msg) => violations.push({ level: 'error', line: line || 1, lineViolations: [], message: '❌ [NS-COMMON-0010] ' + msg });
// 原件区占位符:派生区里的文字不算原件(按原文定位,派生区区间来自引擎原子)
const src = content.replace(/\r\n/g, '\n');
const regions = T.parseArchRegions(src).regions;
let at = src.indexOf(T.CLAUSE_PLACEHOLDER);
while (at >= 0) {
const pos = at;
if (!regions.some((r) => pos >= r.openStart && pos < r.closeEnd)) push(src.slice(0, pos).split('\n').length, '架构页原件区还有占位符「' + T.CLAUSE_PLACEHOLDER + '」,原件没有写完');
at = src.indexOf(T.CLAUSE_PLACEHOLDER, pos + 1);
}
// V1.19.0:点名先剥 HTML 注释再解析(同长度替换成空格,行号不变)—— 被注释掉的点名不算数
const cites = T.parseBedCitations(src.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' ')));
if (!cites.length) push(1, '架构页没有点名任何测试床(每颗闸都要出现在测试床点名里,没有床写 data-bed="待补床")');
const refsDir = path.join(workspaceRoot, treeRel, 'skills', 'x-spec-checker', 'references');
const gateCache = new Map();
const gatesOf = (spec) => {
if (!gateCache.has(spec)) {
const sp = path.join(refsDir, spec + '-spec.md');
gateCache.set(spec, fs.existsSync(sp) ? new Set(T.extractGateIds(fs.readFileSync(sp, 'utf-8')).map((g) => g.id)) : null);
}
return gateCache.get(spec);
};
const covered = new Set();
// V1.19.0:床内文里的「规范名:编号」按完整编号认 —— 前后都不许紧挨字母、数字、下划线或连字符(加长编号不冒充原编号)
// V1.19.1:转义用函数替换,替换串里不出现 $ —— V1.19.0 写入时替换串里的 $& 被展开成了邻行代码(编号文法不含正则元字符,未触发)
const escRe = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, (m) => '\\' + m);
const mentions = (text, token) => new RegExp('(^|[^A-Za-z0-9_-])' + escRe(token) + '(?![A-Za-z0-9_-])').test(text);
const bedText = new Map();
// 条款号点名(V1.4.0):只有条款书里真实存在的条款才能被床认领
const clauseCache = new Map();
const clausesOf = (spec) => {
if (!clauseCache.has(spec)) {
const rp = path.join(workspaceRoot, treeRel, 'rules', spec + '-rule.md');
clauseCache.set(spec, fs.existsSync(rp) ? new Set(T.parseClauseBook(fs.readFileSync(rp, 'utf-8')).clauses.map((k) => k.id)) : null);
}
return clauseCache.get(spec);
};
// 床种类写实(V1.4.0):不标 invariant 的床必须真调用引擎,否则只是一行头注在充数
// V1.5.0:手抠 SLOT 块 + buildDetectorTools 喂 tools 的床同样是真跑判据(x-mirror / x-icon 三张床实证)
// V1.6.0:在剥掉注释的床文本上按调用形态认 —— 注释里的一句 check.js、无关文件名 access-check.js 不再算数;checkStandardFormat(引擎真 STD 执行器)入表
const ENGINE_CALLS = ['extractNsRuleDetector', 'buildDetectorTools', 'checkStandardFormat'];
const callsEngine = (raw) => {
const code = tools.tsContext.stripComments(raw);
return ENGINE_CALLS.some((t) => new RegExp('(^|[^A-Za-z0-9_$])' + t + '\\s*\\(').test(code))
|| /(^|[\\/'"`])check\.js(?=$|[\s'"`)])/m.test(code)
|| code.indexOf('X-RULE-BEGIN-SLOT') >= 0;
};
for (const c of cites) {
for (const e of c.errors) push(c.line, '测试床点名:' + e);
for (const g of c.guards) {
const set = gatesOf(g.spec);
if (set === null) push(c.line, '测试床点名引用了不存在的规范 ' + g.spec);
else if (!set.has(g.id)) push(c.line, '测试床点名引用了不存在的闸 ' + g.spec + ':' + g.id);
if (g.spec === name) covered.add(g.id);
}
for (const k of c.clauses) {
const set = clausesOf(k.spec);
if (set === null) push(c.line, '测试床点名引用了条款 ' + k.spec + ':' + k.id + ',但规范 ' + k.spec + ' 没有条款书');
else if (!set.has(k.id)) push(c.line, '测试床点名引用了不存在的条款 ' + k.spec + ':' + k.id);
}
if (c.bed === '待补床') continue;
// 测试根只认引擎常量(tools.isTestPath,V1.16.0 起禁在判据里手抄);这里只管写法:仓根相对、正斜杠、不带 ./ 与 ..、.test.js 结尾
const bed = c.bed || '';
if (!tools.isTestPath(bed) || !/^[A-Za-z0-9._\/-]+\.test\.js$/.test(bed) || /^\.\//.test(bed) || /(^|\/)\.\.(\/|$)/.test(bed)) {
push(c.line, '测试床路径须是仓根相对、位于测试根下的 .test.js(测试根以引擎常量 constants/test-roots.js 为准;实为「' + c.bed + '」);没有床写 data-bed="待补床"');
continue;
}
// V1.19.0:唯一运行器不收床的目录里的床永远不会被跑到,点名它等于登记一张死床
if (typeof tools.isTestSkipDir !== 'function') { push(c.line, '引擎没有注入 tools.isTestSkipDir,判不了点名的床会不会被唯一运行器收到'); continue; }
// 只看测试根里面的目录段:测试根前缀本身(.claude/…)不算 —— 前缀的长度用引擎谓词 tools.isTestPath 量,不手抄测试根
const segs = bed.split('/');
let rootLen = 0;
for (let k = 1; k < segs.length; k += 1) if (tools.isTestPath(segs.slice(0, k).join('/') + '/')) { rootLen = k; break; }
const skipSeg = segs.slice(rootLen, -1).find((seg) => tools.isTestSkipDir(seg));
if (skipSeg) { push(c.line, '点名的测试床 ' + c.bed + ' 住在唯一运行器不收床的目录「' + skipSeg + '」里(夹具、依赖、以「.」或「zz」开头的目录),它永远不会被跑到:把床挪出来,或点名真正会被跑的那张'); continue; }
const abs = path.join(workspaceRoot, c.bed);
if (!fs.existsSync(abs)) { push(c.line, '点名的测试床不存在:' + c.bed); continue; }
if (!bedText.has(abs)) bedText.set(abs, fs.readFileSync(abs, 'utf-8'));
const text = bedText.get(abs);
for (const g of c.guards) {
if (!mentions(text, g.spec + ':' + g.id)) push(c.line, '测试床 ' + c.bed + ' 的内文没有写「' + g.spec + ':' + g.id + '」—— 点名守护某颗闸的床,必须在床里写明它守的是哪颗闸');
}
for (const k of c.clauses) {
if (!mentions(text, k.spec + ':' + k.id)) push(c.line, '测试床 ' + c.bed + ' 的内文没有写「' + k.spec + ':' + k.id + '」—— 点名承接某条条款的床,必须在床里写明它承接的是哪条');
}
if (c.kind !== 'invariant' && !callsEngine(text)) {
push(c.line, '测试床 ' + c.bed + ' 没有调用本规范的判据(剥掉注释后既无 extractNsRuleDetector( / buildDetectorTools( / checkStandardFormat( 调用,也无作为路径段的 check.js,也无 X-RULE-BEGIN-SLOT):要么让床真跑判据,要么在点名上写 data-bed-kind="invariant" 表明它只守不变量、不跑判据');
}
}
const own = gatesOf(name);
if (own) {
for (const id of own) {
if (!covered.has(id)) push(1, '闸 ' + name + ':' + id + ' 没有出现在测试床点名里(有床点名床,没有床写 data-bed="待补床")');
}
}
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0010-架构页原件完整与测试床验真-P1-X
NS-COMMON-0011:架构页遵循系统架构标准(x-arch-standard.json、.claude/arch/system/*/ARCH.html 文件)
适用文件:
- 包含:
.claude/skills/x-spec-checker/references/x-arch-standard.json、.claude/arch/system/*/ARCH.html - 排除:无
规则:系统架构页必须按《系统架构标准》的可机判面长成同一个样子,判定依据是标准名册 x-arch-standard.json(散文版住 .claude/arch/standards/system-architecture-standard.html,两者的关系与条款书↔判据相同)。四臂,全部是形态判定、零语义:臂①(节名册与顺序) 页面里的 <section id="s-…"> 必须全部取自名册、出现顺序与名册一致,名册里标 required 的节必须在场(s-census / s-ops 是条件节,不适用的域不建);臂②(节编号属性) 每个节带 data-index 与 data-kicker —— 编号与英文提示由属性给、由样式渲染,不许写进标题(标题文字是页内导航的来源,塞编号进去会把导航撑坏);臂③(表达层在场) <body> 带名册声明的页面类、<head> 引名册声明的共用样式表 —— 所有系统架构页共用一套设计语言,不许每页自创;臂④(名册自洽,锚在名册文件) pending 按名称排序、不重复、只登记真实存在的系统架构目录,ceiling 等于登记数。pending 里登记的域整条静默 —— 名册只减不增,改造完一份划掉一份并把 ceiling 降 1,否则立闸当轮全部架构页同时爆红、无法分批推进。诚实边界:只证形态 —— 节在场不证明那一节写对了内容,挂了样式表不证明视觉真的对;标准里「不许发明第二套设计语言」「整页只有一种底色」这类要求判据够不着,由写页时读标准与人审兜底。HTML 注释里的 <section id= 已被抹掉不计。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0011-架构页遵循系统架构标准-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const fs = require('fs');
const path = require('path');
const rel = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
const push = (line, msg) => violations.push({ level: 'error', line: line || 1, lineViolations: [], message: '❌ [NS-COMMON-0011] ' + msg });
const onRegistry = /x-arch-standard\.json$/.test(rel);
const treeRel = onRegistry ? rel.split('/skills/')[0] : rel.split('/arch/system/')[0];
const regPath = path.join(workspaceRoot, treeRel, 'skills', 'x-spec-checker', 'references', 'x-arch-standard.json');
if (!fs.existsSync(regPath)) { push(1, '标准名册不存在:' + treeRel + '/skills/x-spec-checker/references/x-arch-standard.json'); return violations; }
let reg = null;
try { reg = JSON.parse(fs.readFileSync(regPath, 'utf-8')); } catch (e) { push(1, '标准名册不是合法 JSON:' + e.message); return violations; }
const sections = Array.isArray(reg.sections) ? reg.sections : [];
const pending = Array.isArray(reg.pending) ? reg.pending : [];
// 臂④ 名册自洽(锚在名册文件,全局核对一次)
if (onRegistry) {
if (!sections.length) push(1, '名册缺 sections:节骨架是本闸的判定依据,不许为空');
const ids = sections.map((s) => (s && s.id) || '');
for (const id of ids) if (!/^s-[a-z][a-z-]*$/.test(id)) push(1, 'sections 里有非法节 id「' + id + '」(须形如 s-xxx)');
if (new Set(ids).size !== ids.length) push(1, 'sections 里有重复的节 id');
const sysDir = path.join(workspaceRoot, treeRel, 'arch', 'system');
const exists = fs.existsSync(sysDir) ? new Set(fs.readdirSync(sysDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)) : new Set();
const sorted = pending.slice().sort();
if (pending.join('|') !== sorted.join('|')) push(1, 'pending 名册未按名称排序');
if (new Set(pending).size !== pending.length) push(1, 'pending 名册有重复登记');
for (const n of pending) if (!exists.has(n)) push(1, 'pending 登记了不存在的系统架构目录:' + n);
if (reg.ceiling !== pending.length) push(1, 'ceiling(' + reg.ceiling + ')不等于 pending 登记数(' + pending.length + ')—— 名册只减不增,改造完一份同批把 ceiling 降到登记数');
return violations;
}
const name = rel.split('/arch/system/')[1].split('/')[0];
if (pending.indexOf(name) >= 0) return violations;
const src = content.replace(/\r\n/g, '\n').replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
const lineAt = (idx) => src.slice(0, idx).split('\n').length;
const order = sections.map((s) => s.id);
const required = sections.filter((s) => s && s.required).map((s) => s.id);
// 臂① 节名册与顺序
const seen = [];
const secRe = /<section\s+id="([^"]+)"/g;
let m = null;
while ((m = secRe.exec(src)) !== null) {
seen.push({ id: m[1], line: lineAt(m.index) });
if (order.indexOf(m[1]) < 0) push(lineAt(m.index), '自造节「' + m[1] + '」:节 id 只许取自标准名册(' + order.join(' → ') + ')');
}
const known = seen.filter((s) => order.indexOf(s.id) >= 0);
for (let i = 1; i < known.length; i++) {
if (order.indexOf(known[i].id) <= order.indexOf(known[i - 1].id)) {
push(known[i].line, '节顺序与标准名册不符:「' + known[i].id + '」排在「' + known[i - 1].id + '」之后,名册顺序是 ' + order.join(' → '));
break;
}
}
for (const id of required) if (!known.some((s) => s.id === id)) push(1, '缺必填节「' + id + '」(标准十节里的必填项;只有条件节 s-census / s-ops 允许缺席,且不建时须在诚实边界留一句显式裁定)');
// 臂② 每节带编号属性
const tagRe = /<section\s+id="([^"]+)"([^>]*)>/g;
while ((m = tagRe.exec(src)) !== null) {
if (order.indexOf(m[1]) < 0) continue;
const attrs = m[2] || '';
if (!/\bdata-index="/.test(attrs)) push(lineAt(m.index), '节「' + m[1] + '」缺 data-index:节编号由属性给、由样式渲染,不许写进标题文字');
if (!/\bdata-kicker="/.test(attrs)) push(lineAt(m.index), '节「' + m[1] + '」缺 data-kicker:节的英文提示由属性给');
}
// 臂③ 表达层在场
const pageClass = typeof reg.pageClass === 'string' ? reg.pageClass : '';
const styleHref = typeof reg.styleHref === 'string' ? reg.styleHref : '';
const bodyM = /<body([^>]*)>/.exec(src);
if (!bodyM) push(1, '架构页没有 body 开标签');
else if (pageClass && !new RegExp('class="[^"]*\\b' + pageClass + '\\b').test(bodyM[1] || '')) push(lineAt(bodyM.index), 'body 缺页面类「' + pageClass + '」:表达层靠它生效,不挂等于没套用这套设计系统');
if (styleHref && src.indexOf(styleHref) < 0) push(1, '架构页没有引共用表达层样式表(须引到 ' + styleHref + '):所有系统架构页共用一套设计语言,不许每页自创');
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0011-架构页遵循系统架构标准-P1-X
NS-COMMON-0012:业务域遵循架构设计模板(.claude/arch/business/**/ARCH.md、.claude/arch/business/**/parts/*.html、x-arch-design-template.json 文件)
适用文件:
- 包含:
.claude/arch/business/**/ARCH.md、.claude/arch/business/**/parts/*.html、.claude/skills/x-spec-checker/references/x-arch-design-template.json - 排除:无
规则:业务域遵循《架构设计模板》可机判的那一面。一个业务域 = 七个视图:架构设计、流程设计、前端设计、服务设计、数据设计、测试设计六页住域目录的 parts/(文件名 = 视图 id),第七个「变更历史」就是域的 CHANGELOG.md;有哪些视图、每页有哪些节以名册为准,判据代码不写死数目。判定依据是名册 x-arch-design-template.json,散文版住 .claude/arch/standards/architecture-design-template.html。四臂纯形态判定:① 域(锚在 ARCH.md)—— 名册里的视图页齐全;旧模板的形态(modules/、ARCH.html、CHANGELOG.html)退场,留着就是同一件事的两套账;parts/ 里只许放这些视图页。② 视图页骨架(锚在 parts/<视图>.html)—— 节只取自该视图的名册、顺序一致、必填节齐全;两类可重复的节按前缀认(流程设计的业务场景 scene-…、前端设计的逐屏高保真 screen-…),至少一节;流程设计的每个场景必须先有流程图(带 SVG 的 bv-figure)、后有分步操作(bv-step),顺序也判 —— 这是模板的核心要求「先画流程图,再演示在哪一端、哪个页面、点哪里、弹出什么」。③ 表达层 —— body 带页面类,前两份样式表依次落在共用底座 business-module.css 与视图画法 business-views.css(按落点判不按字面:各域深浅不同,同一个文件写出来的相对路径不一样)。④ 名册自洽 —— 视图与节的 id 合法不重复;pending 排序、不重复、只登记立闸当日清单里真实存在的域、登记数等于 ceiling。pending 是棘轮:立闸当日还没铺成六个视图的域,①臂整条静默;视图页本身不豁免,哪个域开始写视图页,那一页一出生就按模板判;一个域铺完且旧形态清干净,它自己的 ARCH.md 当场报「同批划掉」。V1.15.0 之前本闸判的是「业务模块页十节」(旧名册 x-arch-business-standard.json),2026-09-22 用户以菜单域为样板拍板改成六个视图,两种写法不许并存,旧名册同批退役 —— 十节的内容全部有去处,映射写在模板散文里。V1.20.0(2026-09-24)用户拍板加第七个视图「测试设计」(parts/test.html):测试全景、逐个服务的测试、测不到的地方、异常四节必填,资金与状态不变量、人工验收两节可选 —— 宪法测试闭环要求测试守不到的地方写进设计;每个视图自己的问题登在自己那一页的底部。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0012-业务域遵循架构设计模板-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const fs = require('fs');
const path = require('path');
const rel = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
const push = (line, msg) => violations.push({ level: 'error', line: line || 1, lineViolations: [], message: '❌ [NS-COMMON-0012] ' + msg });
// 立闸当日(V1.15.0 · 2026-09-22)还没铺成六个视图的域:名册只许从这份清单里登记,只减不增
// V1.17.0(2026-09-23)按四大中心换门牌:同一批 14 个域,只换名、不增不减
const FOUNDING = ['ecommerce/goods-flow', 'ecommerce/order', 'ecommerce/spu', 'marketing/coupon', 'marketing/customer', 'randd/account-cancellation', 'randd/agreement', 'randd/avatar', 'randd/company', 'randd/login', 'randd/member', 'randd/mobile', 'service/dispatch', 'service/supplier'];
const onRegistry = /x-arch-design-template\.json$/.test(rel);
const treeRel = onRegistry ? rel.split('/skills/')[0] : rel.split('/arch/business/')[0];
const regPath = path.join(workspaceRoot, treeRel, 'skills', 'x-spec-checker', 'references', 'x-arch-design-template.json');
if (!fs.existsSync(regPath)) { push(1, '架构设计模板名册不存在:' + treeRel + '/skills/x-spec-checker/references/x-arch-design-template.json'); return violations; }
let reg = null;
try { reg = JSON.parse(fs.readFileSync(regPath, 'utf-8')); } catch (e) { push(1, '架构设计模板名册不是合法 JSON:' + e.message); return violations; }
const views = Array.isArray(reg.views) ? reg.views : [];
const pending = Array.isArray(reg.pending) ? reg.pending : [];
const retired = Array.isArray(reg.retired) ? reg.retired : [];
const viewIds = views.map((v) => (v && typeof v.id === 'string' ? v.id : ''));
const viewFiles = viewIds.map((id) => id + '.html');
const bizDir = path.join(workspaceRoot, treeRel, 'arch', 'business');
// 臂④ 名册自洽(锚在名册文件,全局核对一次)
if (onRegistry) {
if (!views.length) push(1, '名册缺 views:视图清单是本闸的判定依据,不许为空');
for (const id of viewIds) if (!/^[a-z][a-z-]*$/.test(id)) push(1, 'views 里有非法视图 id「' + id + '」(须是小写英文,它就是 parts/ 里的文件名)');
if (new Set(viewIds).size !== viewIds.length) push(1, 'views 里有重复的视图 id');
for (const v of views) {
const secs = v && Array.isArray(v.sections) ? v.sections : [];
if (!secs.length) push(1, '视图「' + (v && v.id) + '」缺 sections');
const keys = [];
for (const s of secs) {
if (!s || (s.id === undefined && s.pattern === undefined)) { push(1, '视图「' + v.id + '」有一节既没有 id 也没有 pattern'); continue; }
if (s.id !== undefined && !/^[a-z][a-z-]*$/.test(s.id)) push(1, '视图「' + v.id + '」有非法节 id「' + s.id + '」(须是小写英文,与页面上的 id 同值)');
if (s.pattern !== undefined && !/^[a-z]+-$/.test(s.pattern)) push(1, '视图「' + v.id + '」有非法节前缀「' + s.pattern + '」(须形如 scene-)');
keys.push(s.id !== undefined ? s.id : s.pattern);
}
if (new Set(keys).size !== keys.length) push(1, '视图「' + (v && v.id) + '」里有重复的节');
}
const sorted = pending.slice().sort();
if (pending.join('|') !== sorted.join('|')) push(1, 'pending 名册未按域名排序');
if (new Set(pending).size !== pending.length) push(1, 'pending 名册有重复登记');
for (const d of pending) {
if (FOUNDING.indexOf(d) < 0) push(1, 'pending 登记了立闸当日清单之外的域「' + d + '」:名册只减不增,新域一出生就按模板的全部视图写,不进名册');
else if (!fs.existsSync(path.join(bizDir, d, 'ARCH.md'))) push(1, 'pending 登记了不存在的域「' + d + '」(域删掉了要同批划掉登记)');
}
if (reg.ceiling !== pending.length) push(1, 'ceiling(' + reg.ceiling + ')不等于 pending 登记数(' + pending.length + ')—— 名册只减不增,铺完一个域同批把 ceiling 降到登记数');
return violations;
}
const bizRel = rel.split('/arch/business/')[1] || '';
// 臂① 域:名册里的视图页齐全、旧形态退场、parts/ 只放视图页(锚在域的 ARCH.md)
if (/(^|\/)ARCH\.md$/.test(bizRel)) {
const domain = path.posix.dirname(bizRel);
const domAbs = path.dirname(filePath);
const partsAbs = path.join(domAbs, 'parts');
const files = fs.existsSync(partsAbs) ? fs.readdirSync(partsAbs) : [];
for (const f of files) if (viewFiles.indexOf(f) < 0) push(1, 'parts/ 里只许放架构设计模板的视图页(' + viewFiles.join(' / ') + '),出现了「' + f + '」');
const missing = views.filter((v) => files.indexOf(v.id + '.html') < 0);
const left = retired.filter((r) => fs.existsSync(path.join(domAbs, String(r).replace(/\/$/, ''))));
if (pending.indexOf(domain) >= 0) {
if (!missing.length && !left.length) push(1, '「' + domain + '」已经按架构设计模板铺齐全部视图、旧形态也清干净了,却还登记在名册 pending 里 —— 同批从 x-arch-design-template.json 划掉并把 ceiling 降到登记数,再跑 /x-meta-dev sync');
return violations;
}
const all = views.map((x) => x.title).join(' / ') + ' / ' + ((reg.history && reg.history.title) || '变更历史');
for (const v of missing) push(1, '缺视图「' + v.title + '」(parts/' + v.id + '.html):一个业务域按架构设计模板必须有 ' + (views.length + 1) + ' 个视图 —— ' + all);
for (const r of left) push(1, '旧形态「' + r + '」还在:它与这些视图讲的是同一件事,留着就是两套账 —— 内容搬进对应视图后同批删掉');
return violations;
}
// 臂② 视图页骨架 + 臂③ 表达层(锚在 parts/<视图>.html;不是视图名的文件由臂① 在域上报)
const view = views.find((v) => path.basename(filePath) === v.id + '.html');
if (!view) return violations;
const src = content.replace(/\r\n/g, '\n').replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
const lineAt = (idx) => src.slice(0, idx).split('\n').length;
const secs = Array.isArray(view.sections) ? view.sections : [];
const orderText = secs.map((s) => (s.id !== undefined ? s.id : s.pattern + '…')).join(' → ');
const slotOf = (id) => secs.findIndex((s) => (s.id !== undefined ? s.id === id : id.indexOf(s.pattern) === 0 && /^[a-z0-9][a-z0-9-]*$/.test(id.slice(s.pattern.length))));
const starts = [];
const found = [];
const secRe = /<section\b([^>]*)>/g;
let m = null;
while ((m = secRe.exec(src)) !== null) {
starts.push(m.index);
const idM = /\bid="([^"]+)"/.exec(m[1] || '');
if (!idM) continue;
const slot = slotOf(idM[1]);
if (slot < 0) { push(lineAt(m.index), '「' + view.title + '」视图里出现自造节「' + idM[1] + '」:节只许取自模板(' + orderText + ')'); continue; }
found.push({ id: idM[1], slot: slot, index: m.index, line: lineAt(m.index) });
}
for (let i = 1; i < found.length; i++) {
const a = found[i - 1];
const b = found[i];
if (b.slot < a.slot || (b.slot === a.slot && secs[b.slot].id !== undefined)) {
push(b.line, '「' + view.title + '」的节顺序与模板不符:「' + b.id + '」排在「' + a.id + '」之后,模板顺序是 ' + orderText);
break;
}
}
secs.forEach((s, i) => {
const n = found.filter((f) => f.slot === i).length;
if (s.id !== undefined && s.required && !n) push(1, '「' + view.title + '」缺必填节「' + s.id + '」(' + s.title + '):模板顺序是 ' + orderText);
if (s.pattern !== undefined && n < (s.min || 0)) push(1, '「' + view.title + '」至少要有 ' + s.min + ' 个「' + s.title + '」节(id 以 ' + s.pattern + ' 开头),现在有 ' + n + ' 个');
});
// 流程设计的核心:每个场景先画流程图(带 SVG 的 bv-figure),再演示怎么操作(bv-step)
for (const f of found) {
const need = Array.isArray(secs[f.slot].requires) ? secs[f.slot].requires : [];
if (!need.length) continue;
const next = starts.find((s) => s > f.index);
const body = src.slice(f.index, next === undefined ? src.length : next);
const fig = body.search(/class="bv-figure"[\s\S]*?<svg\b/);
const step = body.search(/class="bv-step"/);
if (need.indexOf('flowchart') >= 0 && fig < 0) push(f.line, '场景「' + f.id + '」缺流程图:流程设计的每个场景先画流程图(一张带 SVG 的 bv-figure),再演示怎么操作');
if (need.indexOf('steps') >= 0 && step < 0) push(f.line, '场景「' + f.id + '」缺分步操作:流程图之后要一步一步演示在哪一端、哪个页面、点哪里、弹出什么(bv-step)');
if (fig >= 0 && step >= 0 && step < fig) push(f.line, '场景「' + f.id + '」的分步操作排在流程图前面:先画流程图,再演示怎么操作');
}
// 臂③ 表达层:body 带页面类 + 前两份样式表依次落在共用底座与视图画法(按落点判,不按字面)
const pageClass = typeof reg.pageClass === 'string' ? reg.pageClass : '';
const bodyM = /<body([^>]*)>/.exec(src);
if (!bodyM) push(1, '视图页没有 body 开标签');
else if (pageClass && !new RegExp('class="[^"]*\\b' + pageClass + '\\b').test(bodyM[1] || '')) push(lineAt(bodyM.index), 'body 缺页面类「' + pageClass + '」:视图页的版式靠它生效,不挂等于没套用这套设计系统');
const styles = Array.isArray(reg.styles) ? reg.styles : [];
const links = [];
const linkRe = /<link\b[^>]*>/g;
let lm = null;
while ((lm = linkRe.exec(src)) !== null) {
if (!/\brel="stylesheet"/.test(lm[0])) continue;
const hm = /\bhref="([^"]+)"/.exec(lm[0]);
if (hm) links.push({ href: hm[1], line: lineAt(lm.index), abs: /^[a-z]+:|^\//i.test(hm[1]) ? '' : path.resolve(path.dirname(filePath), hm[1]) });
}
styles.forEach((s, i) => {
const want = path.join(workspaceRoot, treeRel, s);
const wantRel = path.relative(path.dirname(filePath), want).replace(/\\/g, '/');
if (!links[i] || links[i].abs !== want) push(links[i] ? links[i].line : 1, '第 ' + (i + 1) + ' 份样式表必须是共用层 ' + treeRel + '/' + s + '(从本页写作 ' + wantRel + ')' + (links[i] ? ',现在是 ' + links[i].href : ',现在没有') + ' —— 底座在前、视图画法在后,域内私有样式只能接在两者之后,不许把共用层复制进自己的域');
});
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0012-业务域遵循架构设计模板-P1-X
NS-COMMON-0013:业务结构放置(x-data/**/*_{base,node,leaf,relation,log,dict}.md、.claude/arch/business/**/ARCH.md、x-arch-business-structure.json 文件)
适用文件:
- 包含:
x-data/**/*_base.md、x-data/**/*_node.md、x-data/**/*_leaf.md、x-data/**/*_relation.md、x-data/**/*_log.md、x-data/**/*_dict.md、.claude/arch/business/**/ARCH.md、.claude/skills/x-spec-checker/references/x-arch-business-structure.json - 排除:无
规则:每张表按《架构设计模板》的放置规则落位。三种业务只看上级个数:主(_base / _dict,没有上级)、子(_node / _leaf / _log,一个上级)、关(_relation,两端)。上级不靠猜,由表文档「上游/下游关系」段的一行声明给出 —— 子表写 - 上级:(反引号包住一张表名;标签可加粗、半角冒号、表名写在下一级缩进 bullet 里都认;只认带六种后缀的表名,别的反引号注释不算),关系表写 - 两端:(两张以上的表,自己跟自己的关系写同一张表两遍);_relation 表只有一端是表的(另一端是代码里定义的东西)写 - 上级:,这时字段里只许关联这一张表。读之前先剥掉 HTML 注释与围栏代码块:写在注释、代码块里的声明与关联一律不算。「关联」只认字段设计段里表格行的说明,写成「关联 表.字段」—— 「关联」二字紧挨着「表.字段」,中间只许空白、冒号与反引号;多态外键每个去向各写一次「关联」(「关联 甲.x 或关联 乙.y」);同一格里「快照自 / 同 / 取 / 引用 / 等于 表.字段」这类提及不算关联 —— 而且那个字段必须真实存在于那张表。四臂:① 归属唯一:表文档恰好被一个域的 describes.data 覆盖(无主、重叠都红;覆盖口径与 NS-COMMON-0003 逐字同款);② 上级写明:子表与关系表必须有声明,声明的表必须存在、只有一份文档、并在字段里被真实关联(上级是关系表时,那张关系表必须已写两端,而且它的两端都要在字段里关联到,或直接关联它);关系表的两端必须恰好是字段里关联的全部表;主表不许有声明;上级链往上追必须挂到一张主表或关系表上,成环即红;③ 放对一层:子表与上级同域;关系两端同域则与两端同域,两端跨域则必须归一个关系域 —— 它的 ARCH.md 头写 kind: relation、relates: 恰好列出两端所在的那几个域,关系域不许拥有主表;上级或某一端还没有唯一的主,放置判不了,直接报红(豁免不外溢);④ 名册自洽(锚在名册文件):pending.unowned 与 pending.undeclared 各自排序、不重复、只登记存在的表、登记项必须仍然违规、登记数等于各自的 ceiling,而且只许是判据里冻结的立闸当日存量的子集 —— 往名册里加一张新表即红;同名多份表文档、住在引擎忽略目录里的表文档在这里一并报。另有两处兜底:表文档名不合法(有大写等)时本闸直接报红而不是放行;登记在册的表一旦改好,它自己的表文档锚当场报「同批从名册划掉」,改的那一轮就逼着划,不等下一个改名册的人。锚在表文档上,所以改表的当场增量检测就看得见、自动只算本会话的改动;锚在 ARCH.md 上的那一面只查由 describes 决定的两件事 —— 本域覆盖的表有没有被重叠认领、有没有放错层(上级写没写归表文档自己的锚,这里不转报,免得别的会话在本域里新建、还没写完的表拦住只改了域文档的会话)。射程到此为止:检测器跑在引擎沙箱里,拿不到上一版,所以把某个域的 describes 改窄或删掉一个域的 ARCH.md、让一张表变成无主,以及挪动、改名上级表让子表失配,都要等全量检测扫到那张子表时才报;主业务编进哪个域是业务判断,本闸不判对错,只判一张表只有一个主。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0013-业务结构放置-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const fs = require('fs');
const path = require('path');
const rel = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
const push = (line, msg) => violations.push({ level: 'error', line: line || 1, lineViolations: [], message: '❌ [NS-COMMON-0013] ' + msg });
const SUFFIX = '(base|node|leaf|relation|log|dict)';
const TABLE_RE = new RegExp('^x-data\\/(?:.+\\/)?([a-z][a-z0-9_]*_' + SUFFIX + ')\\.md$');
const LOOSE_TABLE_RE = new RegExp('^x-data\\/.+_' + SUFFIX + '\\.md$', 'i');
const NAME_RE = new RegExp('^[a-z][a-z0-9_]*_' + SUFFIX + '$');
// ★立闸当日(2026-09-22)的存量基线(冻结)★ 名册 pending 只许是它的子集:往名册里加一张新表 = 越过基线 = 红。
// 只准删、不准加(与 x-governance 的 ADR 重号冻结名单同一个做法);两份名单由真判据对真仓库跑出来,不是手数的。
const FOUNDING = {
unowned: ['category_base', 'customer_cart_relation', 'customer_favorite_relation', 'customer_footprint_relation', 'menu_base', 'sop_step_archive_summary_leaf', 'sop_step_client_confirm_leaf', 'sop_step_consumable_leaf', 'sop_step_contingency_leaf', 'sop_step_data_collection_leaf', 'sop_step_execution_note_leaf', 'sop_step_feedback_leaf', 'sop_step_followup_schedule_leaf', 'sop_step_greeting_leaf', 'sop_step_node', 'sop_step_operation_leaf', 'sop_step_photo_leaf', 'sop_step_safety_leaf', 'sop_step_self_check_leaf', 'sop_step_tool_leaf', 'sop_step_triggered_service_leaf', 'system_config_base', 'technician_base'],
undeclared: ['coupon_customer_node', 'customer_cart_relation', 'customer_favorite_relation', 'customer_footprint_relation', 'dispatch_item_node', 'dispatch_status_log', 'dispatch_visit_node', 'order_item_node', 'order_refund_node', 'order_review_node', 'order_status_log', 'order_transaction_log', 'refund_item_relation', 'role_resource_relation', 'role_user_relation', 'sku_maintenance_node', 'sku_maintenance_param_leaf', 'sku_maintenance_pricing_leaf', 'sku_maintenance_spec_leaf', 'sku_maintenance_tag_leaf', 'sop_step_archive_summary_leaf', 'sop_step_client_confirm_leaf', 'sop_step_consumable_leaf', 'sop_step_contingency_leaf', 'sop_step_data_collection_leaf', 'sop_step_execution_note_leaf', 'sop_step_feedback_leaf', 'sop_step_followup_schedule_leaf', 'sop_step_greeting_leaf', 'sop_step_node', 'sop_step_operation_leaf', 'sop_step_photo_leaf', 'sop_step_safety_leaf', 'sop_step_self_check_leaf', 'sop_step_tool_leaf', 'sop_step_triggered_service_leaf', 'spu_sku_node', 'spu_supplier_relation', 'supplier_brand_relation', 'supplier_certificate_node', 'supplier_contact_node'],
};
const onRegistry = /x-arch-business-structure\.json$/.test(rel);
const onArch = /\/arch\/business\/.+\/ARCH\.md$/.test(rel);
const tableM = TABLE_RE.exec(rel);
const onData = /^x-data\//.test(rel);
if (!onRegistry && !onArch && !tableM) {
if (onData && LOOSE_TABLE_RE.test(rel)) push(1, '表文档名不合法:' + rel + '。表名只许小写字母、数字与下划线,并以 _base / _node / _leaf / _relation / _log / _dict 结尾 —— 名字不合法,本闸认不出它是一张表,归属与上级全都没法判。改成合法的表名。');
return violations;
}
if (!tools || !Array.isArray(tools.ignoredDirs)) { push(1, '引擎没有注入 tools.ignoredDirs:本闸走 x-data 目录树时要用它识别引擎看不见的目录,缺了就不扫'); return violations; }
const IGNORED = new Set(tools.ignoredDirs);
const treeRel = onRegistry ? rel.split('/skills/')[0] : (onArch ? rel.split('/arch/business/')[0] : '.claude');
// ── 名册 ──
const regPath = path.join(workspaceRoot, treeRel, 'skills', 'x-spec-checker', 'references', 'x-arch-business-structure.json');
if (!fs.existsSync(regPath)) { push(1, '业务结构名册不存在:' + treeRel + '/skills/x-spec-checker/references/x-arch-business-structure.json'); return violations; }
let reg = null;
try { reg = JSON.parse(fs.readFileSync(regPath, 'utf-8')); } catch (e) { push(1, '业务结构名册不是合法 JSON:' + e.message); return violations; }
const P = (reg && reg.pending) || {};
const C = (reg && reg.ceiling) || {};
const pendUnowned = Array.isArray(P.unowned) ? P.unowned : [];
const pendUndeclared = Array.isArray(P.undeclared) ? P.undeclared : [];
// ── frontmatter 小工具(行尾 # 注释剥掉)──
const fmOf = (text) => {
const L = text.replace(/\r\n/g, '\n').split('\n');
let a = -1, b = -1;
for (let i = 0; i < L.length; i++) { if (L[i].trim() === '---') { if (a < 0) a = i; else { b = i; break; } } }
return a === 0 && b > 0 ? L.slice(a + 1, b).map((l) => l.replace(/\s+#.*$/, '')) : null;
};
const dataBasesOf = (fm) => {
const di = fm.findIndex((l) => /^describes\s*:/.test(l));
let globs = [];
if (di >= 0) for (let j = di + 1; j < fm.length; j++) {
if (/^\S/.test(fm[j])) break;
const m = fm[j].match(/^\s+data\s*:\s*(.*)$/);
if (m) globs = (m[1].match(/["']([^"']+)["']/g) || []).map((x) => x.replace(/["']/g, ''));
}
return globs.map((g) => g.replace(/\/\*\*.*$/, '').replace(/\/\*[^/]*$/, '')).filter(Boolean);
};
// ── 域:各 ARCH.md 的 describes.data 目录前缀 + kind / relates(覆盖口径与 NS-COMMON-0003 同款)──
const bizRoot = path.join(workspaceRoot, treeRel, 'arch', 'business');
const domains = [];
if (fs.existsSync(bizRoot)) (function rec(d) {
for (const e of fs.readdirSync(d, { withFileTypes: true })) {
const p = path.join(d, e.name);
if (e.isDirectory()) { rec(p); continue; }
if (e.name !== 'ARCH.md') continue;
const fm = fmOf(fs.readFileSync(p, 'utf-8'));
if (!fm) continue;
const kindL = fm.find((l) => /^kind\s*:/.test(l));
const relL = fm.find((l) => /^relates\s*:/.test(l));
domains.push({
name: path.relative(bizRoot, d).replace(/\\/g, '/'),
archRel: path.relative(workspaceRoot, p).replace(/\\/g, '/'),
bases: dataBasesOf(fm),
kind: kindL ? kindL.replace(/^kind\s*:\s*/, '').replace(/["']/g, '').trim() : '',
relates: relL ? ((relL.match(/\[([^\]]*)\]/) || [null, ''])[1]).split(',').map((s) => s.replace(/["'\s]/g, '')).filter(Boolean) : null,
});
}
})(bizRoot);
const covers = (bases, tRel) => bases.some((b) => tRel.startsWith(b + '/'));
const ownersOf = (tRel) => domains.filter((d) => covers(d.bases, tRel));
// ── 表:按路径建索引;同名多份单独记下;引擎忽略目录里的表文档单独记下 ──
const byPath = new Map();
const byName = new Map();
const hidden = [];
const dataRoot = path.join(workspaceRoot, 'x-data');
if (fs.existsSync(dataRoot)) (function rec(d, inIgnored) {
for (const e of fs.readdirSync(d, { withFileTypes: true })) {
const p = path.join(d, e.name);
if (e.isDirectory()) { if (e.name === 'node_modules' || e.name === '.git') continue; rec(p, inIgnored || IGNORED.has(e.name)); continue; }
const r = path.relative(workspaceRoot, p).replace(/\\/g, '/');
const m = TABLE_RE.exec(r);
if (!m) continue;
if (inIgnored) { hidden.push(r); continue; }
byPath.set(r, { name: m[1], suffix: m[2], rel: r });
if (!byName.has(m[1])) byName.set(m[1], []);
byName.get(m[1]).push(r);
}
})(dataRoot, false);
const one = (name) => { const ps = byName.get(name) || []; return ps.length === 1 ? byPath.get(ps[0]) : null; };
// ── 读一张表:先剥 HTML 注释与围栏代码块(保留行数),再切段;字段只认字段段里的表格行 ──
const parsed = new Map();
const strip = (text) => text.replace(/\r\n/g, '\n').replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' ')).replace(/^(```|~~~)[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, (m) => m.replace(/[^\n]/g, ' '));
const parseRel = (tRel) => {
if (parsed.has(tRel)) return parsed.get(tRel);
const t = byPath.get(tRel);
const lines = strip(fs.readFileSync(path.join(workspaceRoot, tRel), 'utf-8')).split('\n');
const sec = (re) => { const i = lines.findIndex((l) => re.test(l)); if (i < 0) return { start: -1, body: [] }; let j = i + 1; while (j < lines.length && !/^##\s/.test(lines[j])) j++; return { start: i, body: lines.slice(i + 1, j) }; };
const relSec = sec(/^##\s*上游\s*\/\s*下游关系|^##\s*上下游关系/);
const fieldSec = sec(/^##\s*字段设计/);
const decl = { parent: [], ends: [], endsRaw: 0, parentLine: 0, endsLine: 0, parentCount: 0, endsCount: 0, dotted: [] };
const tokens = (s) => {
const out = [];
for (const x of s.matchAll(/`([^`\s]+)`/g)) {
if (/^[a-z][a-z0-9_]*\.[A-Za-z]/.test(x[1])) { decl.dotted.push(x[1]); continue; }
if (NAME_RE.test(x[1])) out.push(x[1]);
}
return out;
};
const body = relSec.body;
for (let k = 0; k < body.length; k++) {
const lineNo = relSec.start + 2 + k;
const pm = body[k].match(/^\s*-\s*(?:\*\*)?上级(?:\*\*)?\s*[::]\s*(.*)$/);
const em = body[k].match(/^\s*-\s*(?:\*\*)?两端(?:\*\*)?\s*[::]\s*(.*)$/);
if (!pm && !em) continue;
let text = (pm || em)[1];
for (let q = k + 1; q < body.length && /^\s{2,}-\s/.test(body[q]); q++) text += ' ' + body[q]; // 写在下一级缩进 bullet 里的也认
const names = tokens(text);
if (pm) { decl.parentCount++; decl.parent = names; decl.parentLine = lineNo; }
if (em) { decl.endsCount++; decl.endsRaw = names.length; decl.ends = [...new Set(names)]; decl.endsLine = lineNo; }
}
const fields = new Set();
const refs = new Map(); // 表 → Set(字段)
for (const l of fieldSec.body) {
if (!/^\s*\|/.test(l)) continue;
const cells = l.split('|').slice(1, -1).map((c) => c.trim());
if (!cells.length || /^-+$/.test(cells[0].replace(/:/g, '')) || cells[0] === '字段名') continue;
fields.add(cells[0].replace(/`/g, ''));
// 只认紧挨着「表.字段」的「关联」二字(中间只许空白、冒号与反引号):「同 / 取 / 引用 `表.字段`」是提及不是关联 ——
// 宽口径会把快照来源算成关系的一端(V1.18.0 收紧到条款原意);多态外键每个去向各写一次「关联」
for (const c of cells.slice(1)) for (const x of c.matchAll(/关联[\s::`]*([a-z][a-z0-9_]*_(?:base|node|leaf|relation|log|dict))\.([A-Za-z][A-Za-z0-9]*)/g)) {
if (!refs.has(x[1])) refs.set(x[1], new Set());
refs.get(x[1]).add(x[2]);
}
}
if (t) refs.delete(t.name);
const out = { t, decl, refs, fields, hasDecl: decl.parentCount + decl.endsCount > 0 };
parsed.set(tRel, out);
return out;
};
const kindOf = (t) => {
if (t.suffix === 'base' || t.suffix === 'dict') return '主';
if (t.suffix === 'relation') { const d = parseRel(t.rel).decl; return d.parentCount && !d.endsCount ? '子' : '关'; }
return '子';
};
// 引用证据:字段里写的「表.字段」必须指向那张表真实存在的字段
const refOk = (pt, target) => {
const fs2 = pt.refs.get(target.name);
if (!fs2) return false;
const tf = parseRel(target.rel).fields;
return [...fs2].some((f) => tf.has(f));
};
// ── 一张表的全部判定(返回 [行号, 文字])──
const judge = (t) => {
const out = [];
const dup = byName.get(t.name) || [];
if (dup.length > 1) { out.push([1, '表名「' + t.name + '」有 ' + dup.length + ' 份文档(' + dup.join('、') + '):一张表只能有一份文档,同名的另一份会让检测判错对象。删掉多余的那一份。']); return out; }
const own = ownersOf(t.rel);
const inPU = pendUnowned.indexOf(t.name) >= 0, inPD = pendUndeclared.indexOf(t.name) >= 0;
// 臂① 归属唯一
if (own.length === 0 && !inPU) out.push([1, '表「' + t.name + '」不属于任何域:没有一个域的 describes.data 覆盖 ' + t.rel + '。\n\n每张表都必须恰好归一个域。要你做的:打开该归的那个域的 ARCH.md,在 describes.data 里加上 "' + t.rel.split('/').slice(0, -1).join('/') + '/**"(那个域随之回看、升版、封版);还没有合适的域,就先建一个(ARCH.md + CHANGELOG.md)再认领。']);
if (own.length > 1) out.push([1, '表「' + t.name + '」同时被 ' + own.length + ' 个域认领(' + own.map((d) => d.name).join('、') + '):一张表只能有一个主。打开多余的那个域的 ARCH.md,把 describes.data 改窄,别再覆盖 ' + t.rel + '。']);
if (own.length >= 1 && inPU) out.push([1, '「' + t.name + '」已经有主了,却还登记在业务结构名册的 pending.unowned 里:同一轮从名册划掉这一行、把 ceiling.unowned 降一,再跑 /x-meta-dev sync。']);
const pt = parseRel(t.rel), d = pt.decl, kind = kindOf(t);
if (pt.hasDecl && inPD) out.push([d.parentLine || d.endsLine || 1, '「' + t.name + '」已经写明了上级,却还登记在业务结构名册的 pending.undeclared 里:同一轮从名册划掉这一行、把 ceiling.undeclared 降一,再跑 /x-meta-dev sync。']);
if (d.dotted.length) out.push([d.parentLine || d.endsLine, '「' + t.name + '」的声明里写了「' + d.dotted.join('、') + '」:声明里只写表名,不带「.字段」(字段写在字段设计段的说明里)。']);
// 臂② 上级写明
if (kind === '主') {
if (pt.hasDecl) out.push([d.parentLine || d.endsLine || 1, '「' + t.name + '」是主业务(' + t.suffix + ' 表),主业务没有上级:删掉上游/下游关系段里的「上级」或「两端」那一行。']);
return out.concat(place(t, own, kind, pt));
}
if (!pt.hasDecl) {
if (!inPD) out.push([1, '「' + t.name + '」没有写明上级:打开 ' + t.rel + ',在「上游/下游关系」段写一行 ' + (t.suffix === 'relation' ? '「- 两端:`表A` × `表B`」(两张被关联的表)' : '「- 上级:`上级表`」') + '。\n\n上级不靠猜:同一张表往往引用好几张别的表,只有写出来,放在哪一层才是确定的。']);
return out;
}
if (d.parentCount > 1 || d.endsCount > 1) { out.push([d.parentLine || d.endsLine, '「' + t.name + '」写了不止一行「上级」或「两端」:只留一行。']); return out; }
if (d.parentCount && d.endsCount) { out.push([d.parentLine, '「' + t.name + '」同时写了「上级」和「两端」:子业务写上级,关系业务写两端,删掉其中一行。']); return out; }
const refNames = [...pt.refs.keys()].sort();
if (d.parentCount) {
if (d.parent.length !== 1) { out.push([d.parentLine, '「' + t.name + '」的上级要恰好写一张表(反引号包住表名),现在认出 ' + d.parent.length + ' 张' + (d.parent.length ? '(' + d.parent.join('、') + ')' : '') + '。']); return out; }
const parName = d.parent[0];
if (parName === t.name) { out.push([d.parentLine, '「' + t.name + '」把自己写成了上级:改成它真正挂靠的那张表。']); return out; }
const parDocs = byName.get(parName) || [];
if (!parDocs.length) { out.push([d.parentLine, '「' + t.name + '」声明的上级「' + parName + '」不存在:x-data 里没有这张表。检查表名拼写;那张表还没建的话先建它。']); return out; }
if (parDocs.length > 1) { out.push([d.parentLine, '「' + t.name + '」声明的上级「' + parName + '」有 ' + parDocs.length + ' 份文档,判不了是哪一张:先删掉多余的那一份。']); return out; }
const par = byPath.get(parDocs[0]);
if (t.suffix === 'relation' && refNames.some((n) => n !== parName)) { out.push([d.parentLine, '「' + t.name + '」写了「上级」,但字段里关联了不止一张表(' + refNames.join('、') + '):两端都是表的就是关系,写「- 两端:」并列出全部被关联的表。只有另一端是代码里定义的东西时,关系表才写「上级」。']); return out; }
const pk = kindOf(par);
if (pk === '关' && par.suffix === 'relation') {
const pd = parseRel(par.rel).decl;
if (!pd.endsCount || pd.ends.length < 1) { out.push([d.parentLine, '「' + t.name + '」挂在关系表「' + parName + '」下面,而「' + parName + '」自己还没写两端:先打开 ' + par.rel + ',在「上游/下游关系」段写「- 两端:…」,这张子表才判得了。']); return out; }
const endTabs = pd.ends.map(one);
const ok = refOk(pt, par) || (endTabs.every(Boolean) && endTabs.every((e) => refOk(pt, e)));
if (!ok) { out.push([d.parentLine, '「' + t.name + '」声明的上级是关系表「' + parName + '」,但字段里没有关联到它:要么关联 `' + parName + '.字段`,要么把它的两端(' + pd.ends.join('、') + ')都在字段说明里写成「关联 `表.字段`」,而且字段要真实存在。']); return out; }
} else {
let ok = refOk(pt, par);
if (!ok && par.suffix === 'relation' && pk === '子') { const pp = parseRel(par.rel).decl.parent[0]; const ppt = pp ? one(pp) : null; ok = !!ppt && refOk(pt, ppt); }
if (!ok) { out.push([d.parentLine, '「' + t.name + '」声明的上级「' + parName + '」在字段里没有关联:在指向它的那个外键字段的说明里写「关联 `' + parName + '.字段名`」,而且那个字段要真实存在于 ' + parName + '。']); return out; }
}
// 上级链不许成环
const seen = new Set([t.name]);
let cur = par;
for (let step = 0; step < 32 && cur; step++) {
if (seen.has(cur.name)) { out.push([d.parentLine, '「' + t.name + '」的上级链成环了(' + [...seen].join(' → ') + ' → ' + cur.name + '):子业务往上追,最后必须挂到一张主表或一张关系表上。']); return out; }
seen.add(cur.name);
if (kindOf(cur) !== '子') break;
const cd = parseRel(cur.rel).decl;
if (!cd.parentCount || cd.parent.length !== 1) break;
cur = one(cd.parent[0]);
}
}
if (d.endsCount) {
if (t.suffix !== 'relation') { out.push([d.endsLine, '「' + t.name + '」不是关系表(' + t.suffix + '),不能写「两端」:写「- 上级:`上级表`」。']); return out; }
if (d.endsRaw < 2) { out.push([d.endsLine, '「' + t.name + '」的两端要写两张表(同一张表自己跟自己的关系就把它写两遍),现在认出 ' + d.endsRaw + ' 张' + (d.ends.length ? '(' + d.ends.join('、') + ')' : '') + '。另一端若是代码里定义的东西、不是表,把这一行改成「- 上级:`那一张表`」,并确认字段里只关联了这一张表。']); return out; }
for (const e of d.ends) {
const eds = byName.get(e) || [];
if (!eds.length) { out.push([d.endsLine, '「' + t.name + '」声明的一端「' + e + '」不存在:x-data 里没有这张表。检查表名拼写;另一端若是代码里定义的东西,改成「- 上级:`那一张表`」。']); return out; }
if (eds.length > 1) { out.push([d.endsLine, '「' + t.name + '」声明的一端「' + e + '」有 ' + eds.length + ' 份文档,判不了是哪一张:先删掉多余的那一份。']); return out; }
if (!refOk(pt, byPath.get(eds[0]))) { out.push([d.endsLine, '「' + t.name + '」声明的一端「' + e + '」在字段里没有关联:在对应外键字段的说明里写「关联 `' + e + '.字段名`」,而且字段要真实存在。']); return out; }
}
const extra = refNames.filter((n) => d.ends.indexOf(n) < 0);
if (extra.length) { out.push([d.endsLine, '「' + t.name + '」的字段还关联了 ' + extra.join('、') + ',却没写进两端:关系表字段里关联的每一张表都是它的一端,全部列进「两端」。']); return out; }
}
return out.concat(place(t, own, kind, pt));
};
// 臂③ 放对一层(归属唯一、声明有效时才判;上级或一端还没有主就判不了 → 直接报,不静默)
const place = (t, own, kind, pt) => {
const out = [];
const me = own.length === 1 ? own[0] : null;
if (!me) return out;
const d = pt.decl;
if (kind === '主') {
if (me.kind === 'relation') out.push([1, '「' + t.name + '」是主业务,却归在关系域「' + me.name + '」:关系域只放关系与挂在关系下面的子业务。把它挪到普通的域(改两个域的 describes.data)。']);
return out;
}
if (kind === '子' && d.parentCount === 1 && d.parent.length === 1) {
const par = one(d.parent[0]);
if (!par) return out;
const po = ownersOf(par.rel);
if (po.length !== 1) out.push([d.parentLine, '「' + t.name + '」的上级「' + par.name + '」' + (po.length ? '被 ' + po.length + ' 个域同时认领' : '还没有主') + ',放在哪一层判不了:先让「' + par.name + '」恰好归一个域。']);
else if (po[0].name !== me.name) out.push([d.parentLine, '子业务必须和上级在同一个域:「' + t.name + '」归「' + me.name + '」域,它的上级「' + par.name + '」归「' + po[0].name + '」域。把它挪到上级所在的域(改 describes.data),或者重新确认上级写得对不对。']);
return out;
}
if (kind === '关' && d.endsCount === 1 && d.endsRaw >= 2) {
const ets = d.ends.map(one);
if (!ets.every(Boolean)) return out;
const eo = ets.map((e) => ownersOf(e.rel));
const bad = ets.filter((e, i) => eo[i].length !== 1);
if (bad.length) { out.push([d.endsLine, '关系「' + t.name + '」的一端「' + bad.map((e) => e.name).join('、') + '」还没有唯一的主,放在哪一层判不了:先让它恰好归一个域。']); return out; }
const ed = [...new Set(eo.map((o) => o[0].name))].sort();
if (ed.length === 1) {
if (ed[0] !== me.name) out.push([d.endsLine, '关系「' + t.name + '」的两端都在「' + ed[0] + '」域,它就必须在「' + ed[0] + '」域,现在归「' + me.name + '」。把它挪过去(改两个域的 describes.data)。']);
} else {
const rs = (me.relates || []).slice().sort();
if (me.kind !== 'relation') out.push([d.endsLine, '关系「' + t.name + '」的两端分属 ' + ed.join('、') + ',跨域的关系不属于其中任何一个域,必须归一个关系域:建一个域目录,ARCH.md 头写 kind: relation 与 relates: [' + ed.join(', ') + '],再把它挪进去。现在它归普通域「' + me.name + '」。']);
else if (rs.join('|') !== ed.join('|')) out.push([d.endsLine, '关系「' + t.name + '」的两端分属 ' + ed.join('、') + ',而它所在的关系域「' + me.name + '」的 relates 写的是 [' + rs.join(', ') + ']:把 relates 改成 [' + ed.join(', ') + ']。']);
}
}
return out;
};
// ── 锚:名册 ──
if (onRegistry) {
const chk = (key, list, stillBad, what) => {
const sorted = list.slice().sort();
if (list.join('|') !== sorted.join('|')) push(1, 'pending.' + key + ' 未按表名排序');
if (new Set(list).size !== list.length) push(1, 'pending.' + key + ' 有重复登记');
for (const n of list) {
if (FOUNDING[key].indexOf(n) < 0) { push(1, 'pending.' + key + ' 登记了立闸当日不在册的表「' + n + '」:名册只减不增,新表一出生就受管,不许登记豁免。把这一行删掉,按报错把那张表改对。'); continue; }
const ps = byName.get(n) || [];
if (!ps.length) { push(1, 'pending.' + key + ' 登记了不存在的表:' + n + '(表删了要同批划掉)'); continue; }
if (!stillBad(byPath.get(ps[0]))) push(1, 'pending.' + key + ' 登记的「' + n + '」已经' + what + ':从名册划掉,把 ceiling.' + key + ' 降到登记数,再跑 /x-meta-dev sync');
}
if (C[key] !== list.length) push(1, 'ceiling.' + key + '(' + C[key] + ')不等于 pending.' + key + ' 登记数(' + list.length + ')—— 名册只减不增,改好一张同批降 ceiling');
};
chk('unowned', pendUnowned, (t) => ownersOf(t.rel).length === 0, '有主了');
chk('undeclared', pendUndeclared, (t) => kindOf(t) !== '主' && !parseRel(t.rel).hasDecl, '写明了上级(或它是主业务,本来就不用写)');
for (const h of hidden) push(1, '表文档住在检测引擎看不见的目录里:' + h + '。这类目录(' + [...IGNORED].filter((x) => h.split('/').indexOf(x) >= 0).join('、') + ')里的文件任何规范都不扫,表在这里等于隐身。挪到正常目录。');
for (const [n, ps] of byName) if (ps.length > 1) push(1, '表名「' + n + '」有 ' + ps.length + ' 份文档(' + ps.join('、') + '):删掉多余的那一份。');
return violations;
}
// ── 锚:ARCH.md(本域形态 + 本域覆盖的表里「由 describes 决定」的那两件:重叠认领、放错层)──
// 上级写没写、写得对不对归表文档自己的锚,这里不转报 —— 否则别的会话在本域里新建、还没写完的表,
// 会拦住只改了域文档的本会话(宪法 §六.6)。检测器跑在引擎沙箱里(只给 fs / path),拿不到 git 上一版,
// 所以「这次新认领了哪些」算不出来;describes 改窄致无主要等全量检测扫到那张表才报(写进条款的射程)。
if (onArch) {
const me = domains.find((d) => d.archRel === rel);
if (!me) return violations;
if (me.kind && me.kind !== 'relation') push(1, 'kind 只能写 relation(关系域);普通的域不写 kind,删掉这一行。');
if (me.kind === 'relation' && (!me.relates || me.relates.length < 2)) push(1, '关系域必须用 relates: [域A, 域B] 写明它连接哪几个域(至少两个)。');
if (me.relates) for (const r of me.relates) if (!domains.some((d) => d.name === r)) push(1, 'relates 里的「' + r + '」不是已有的域(写域目录名,如 customer、ecommerce/spu)。');
if (me.relates && me.kind !== 'relation') push(1, '写了 relates 却没写 kind: relation:只有关系域才写 relates。');
for (const [r, t] of byPath) {
if (!covers(me.bases, r)) continue;
if ((byName.get(t.name) || []).length > 1) continue;
const own = ownersOf(r);
if (own.length > 1) { push(1, '本域 describes.data 覆盖的表「' + t.name + '」(' + r + ')同时被 ' + own.length + ' 个域认领(' + own.map((d) => d.name).join('、') + '):一张表只能有一个主,把多余的那个域的 describes.data 改窄。'); continue; }
const pt = parseRel(r);
if (kindOf(t) !== '主' && !pt.hasDecl) continue;
for (const [, msg] of place(t, own, kindOf(t), pt)) push(1, '本域 describes.data 覆盖的表「' + t.name + '」(' + r + '):' + msg);
}
return violations;
}
// ── 锚:表文档 ──
const self = byPath.get(rel);
if (!self) return violations;
for (const [line, msg] of judge(self)) push(line, msg);
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0013-业务结构放置-P1-X
NS-COMMON-0014:业务域版本锁步(.claude/arch/business/**/ARCH.md、.claude/arch/business/**/CHANGELOG.md 文件)
适用文件:
- 包含:
.claude/arch/business/**/ARCH.md、.claude/arch/business/**/CHANGELOG.md - 排除:无
规则:业务域的版本号只有一个真值 —— ARCH.md 文档头的 version —— 变更历史是它的账,锁清单是它封下的那一份。判定住检测引擎的版本契约(tools.versionContract,三层同一份代码),本闸是薄壳、只判整单元的「账」这一半(逐个文件的「封版后改过」归 NS-COMMON-0003):① 变更历史写法 —— 文档头恰为 title / unit / kind(unit 为「domain:中心/域」、title 以「变更历史」结尾),每个二级标题都是「## v主.次.补 · YYYY-MM-DD · 一句标题」(契约生效之前的旧条目可以没有标题),版本严格从新到旧、一次只升一步、日期不倒挂,围栏代码块里的标题不算,契约生效之后的条目有标题、有说明;② ARCH.md 的 version 等于第一节(ARCH.md 与 CHANGELOG.md 两个锚都报,只改了其中一份的会话增量检测也看得见);③ 第一节已封版、锁清单自洽且与第一节一致、记全各项与整段历史(旧版一个字不能改)。施工中只在带施工中开关的检测里放过(收尾、开发流 VERIFY、封版的检测前置)。业务总览(.claude/arch/business/CHANGELOG.md)不归本闸,归 NS-COMMON-0015。V2.0.0:迁入统一写法后二十一个域全部锁步,存量豁免名册 x-arch-business-lockstep.json 同批退役。射程:只判写法、相等与封版,判不了条目写得是否属实、回看是否真做过 —— 那一半由统一封版命令逼着先写标题与说明、检测零红、测试全过才写指纹。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0014-业务域版本锁步-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const path = require('path');
const push = (line, msg) => violations.push({ level: 'error', line: line || 1, lineViolations: [], message: '❌ [NS-COMMON-0014] ' + msg });
// 判定住引擎的版本契约(三层同一份代码);没注入就判不了 —— 判不了不算过
const VC = tools.versionContract;
if (!VC || typeof VC.checkUnit !== 'function') { push(1, '引擎没有注入版本契约(tools.versionContract),版本锁步判不了'); return violations; }
const rel = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
const unit = VC.index(workspaceRoot).units.find((u) => u.layer === 'business' && u.id !== 'business:overview' && (u.truthFile === rel || u.changelog === rel));
if (!unit) return violations;
const onLog = unit.changelog === rel;
for (const v of VC.checkUnit(workspaceRoot, unit, { wip: !!tools.versionWip, files: false })) {
// 设计文档那个锚只报「两处版本对不上」这一类(其余都是变更历史自己的事,报在变更历史上)
if (onLog) push(v.line, v.message);
else if (/版本两处对不上|找不到这个单元的版本号/.test(v.message)) push(1, v.message);
}
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0014-业务域版本锁步-P1-X
NS-COMMON-0015:业务总览版本锁步与无主业务代码只减不增(.claude/arch/business/CHANGELOG.md、.claude/arch/business/_context-map.md 文件)
适用文件:
- 包含:
.claude/arch/business/CHANGELOG.md、.claude/arch/business/_context-map.md - 排除:无
规则:业务总览是一个单元 —— 跨域关系图 _context-map.md(版本号写在它的文档头)与业务架构注册表 _index.md,变更历史是 .claude/arch/business/CHANGELOG.md(此前日志写在关系图文档头的 version-log 里,V2.0.0 逐条搬出)。判定住检测引擎的版本契约(tools.versionContract),本闸是薄壳:① 与业务域同样的写法、版本相等、封版与锁清单一致、封版之后改过没升版(关系图锚只报版本对不上);② 无主业务代码只减不增(锚在变更历史)—— 业务代码(四端与内核母本顶层目录下、按端取的文件;依赖、构建与装配产物、自动生成的文件、测试根与部署门登记过的床不算)不归任何业务域的,第一次封业务总览时冻结进它的锁清单;③ 业务总览的锁清单另记业务域名册(HARNESS v4.2.0),新增、删掉一个业务域即报,要业务总览升版封版;此后新出现一个不归任何域的业务代码文件即红:写进某个域设计文档头的 describes(那个域随之升版),或挪进已被描述的目录。已归位或已删掉的在下一次封业务总览时自动划掉;封版命令拒绝把本会话新添的无主代码冻进基线。为什么冻结而不是一次归位:立闸当日约一千个业务代码文件不归任何域(后台公共组件、语言包、各端系统层、内核),一次归位就是一次全仓重新分域,而「新的必须有主」今天就能守住;存量在逐域回归时一个个归位。射程:只判「有没有域认领」,判不了认领得对不对。
检测逻辑代码:
// X-RULE-BEGIN-SLOT-x-arch-NS-COMMON-0015-业务总览版本锁步与无主业务代码只减不增-P1-X
(function(filePath, content, workspaceRoot, tools) {
const violations = [];
const path = require('path');
const push = (line, msg) => violations.push({ level: 'error', line: line || 1, lineViolations: [], message: '❌ [NS-COMMON-0015] ' + msg });
// 判定住引擎的版本契约(三层同一份代码);没注入就判不了 —— 判不了不算过
const VC = tools.versionContract;
if (!VC || typeof VC.checkUnit !== 'function') { push(1, '引擎没有注入版本契约(tools.versionContract),业务总览判不了'); return violations; }
const rel = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
const unit = VC.index(workspaceRoot).units.find((u) => u.id === 'business:overview');
if (!unit || (rel !== unit.changelog && rel !== unit.truthFile)) return violations;
const onLog = rel === unit.changelog;
// 变更历史那个锚整单元判(含逐文件汇总与无主业务代码,整仓扫一遍);关系图那个锚只判版本对不上,不重复扫
for (const v of VC.checkUnit(workspaceRoot, unit, { wip: !!tools.versionWip, files: onLog })) {
if (onLog) push(v.line, v.message);
else if (/版本两处对不上|找不到这个单元的版本号/.test(v.message)) push(1, v.message);
}
return violations;
})
// X-RULE-END-SLOT-x-arch-NS-COMMON-0015-业务总览版本锁步与无主业务代码只减不增-P1-X
组成要素(强制要求):
- ✅ 每个NS规则必须包含"检测逻辑代码"代码块(SLOT-X标记包裹的检测函数)
- ✅ 检测代码必须是JavaScript函数格式
- ✅ 每个NS规则必须包含"适用文件"声明
// X-RULE-MULTILINE-END-x-standard-STD-COMMON-0003-NS规则定义-X
// X-RULE-END-STANDARD-x-standard-STD-COMMON-0003-STD和NS章节结构-P1-X
🔧 检测工具
检测命令:node .claude/skills/x-spec-checker/scripts/check-spec/check.js
退出码:0 = 通过,1 = 失败
可用参数:
-t spec/x-arch-spec:规范自测(检测 STANDARD-X 是否符合 SLOT-X)-v spec/x-arch-spec:规范验证(用元规范检测 x-arch-spec 结构)-m spec/x-arch-spec .claude/arch/business:规范扫描(用 x-arch-spec 检测业务架构文档)-m spec/x-arch-spec .claude:规范扫描(业务组 + 系统组,含系统组注册表与系统架构目录)