create-yss-spec 3.4.8 → 3.4.9

package/template/.agents/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -25,11 +25,11 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 
 调用本技能前由生命周期编排器展示 `scripts/backend-platforms` 的精确版本清单及兼容状态，并通过 `gate.backend-architecture-platform-approved` 把架构、Spring Boot、Java 和 YSS 父 POM/BOM 合并展示、取得真实用户确认；生成器不提问、不猜版本、不使用 `x` 或 `latest`。已有批准且当前的选择展示摘要后复用；既有工程核验并复用登记值，不触发该门禁。
 
-- 候选平台：Boot 2.7.18 / Java 8，Boot 3.5.16 / Java 17 或 21，Boot 4.1.1 / Java 17 或 21。新 Boot 默认推荐 Java 17；候选不等于可生成。
+- 精确候选版本与可选状态只读取 `scripts/backend-platforms` 和共享平台清单，不在此复制版本表；候选不等于可生成。
 - 独立子项目可继承主项目组合或覆盖，必须逐项目确认（允许一次确认明确列出的项目）；同一 Maven Reactor 使用一个平台。
 - 只开放共享兼容清单中已有真实 YSS 构建、依赖和启动证据的组合。缺少兼容父 POM、BOM、starter 或相应能力证据即 `blocked`；不替换官方组件、不降级回退。
 - 新生成合同必须有 `platform_configuration` v2，与架构决策、Maven 坐标及兼容条目摘要一致。Boot、Java、YSS 坐标或依赖配方变化时回生命周期重新确认并编译合同；仅追加同配置验证记录不重复确认，仍核验证据有效性。
-- Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Boot 3.5 / 4.1 拒绝 Java 8/11。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
+- Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Java 下限和允许组合由当前平台条目决定。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
 - 平台候选维护验证产物标记 `platform_verification=candidate`，不能交给业务生成、升级完成等级或进入首切片验证。测试夹具不证明 YSS 兼容。
 
 版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `docs/engineering/backend-platforms.md`。
@@ -47,36 +47,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 
 ## 推荐命令
 
-```bash
-node scripts/generate_and_verify_scaffold.mjs \
-  --project-name my-service \
-  --base-package com.yss.myservice \
-  --group-id com.yss.datamiddle \
-  --project-version 1.0.0-SNAPSHOT \
-  --parent-group-id com.yss.datamiddle \
-  --parent-artifact-id yss-datamiddle-parent \
-  --parent-version 2.0.0-SNAPSHOT \
-  --yss-components-version 2.0.0-SNAPSHOT \
-  --output-dir /path/to/implementation-repo \
-  --contract-id <approved-scaffold-contract-id> \
-  --contract-version <current-version> \
-  --approval-ref <lifecycle-approval-ref> \
-  --compiler-draft-ref <compiler-draft-ref> \
-  --persisted-ref <persisted-contract-ref> \
-  --contract-file /path/to/persisted-scaffold-contract.json \
-  --evidence-dir /path/to/evidence/scaffold
-```
-
-完成批准的 golden first slice 后运行：
-
-```bash
-node scripts/run_first_slice_verification.mjs \
-  --project-root /path/to/implementation-repo/my-service \
-  --slice-contract-file /path/to/approved-slice-contract.yaml \
-  --contract-root /path/to/contract-repository \
-  --approval-ref docs/approved-checkpoint.yaml \
-  --evidence-dir /path/to/evidence/first-slice
-```
+输入和合同已核验后，按 [受控生成命令示例](references/command-examples.md) 组装当前参数；示例值不授予生成或覆盖权限。
 
 ## 生成结果应包含
 
@@ -95,7 +66,7 @@ node scripts/run_first_slice_verification.mjs \
 - 永不生成 `User CRUD` 示例；`--with-example` 已禁用，业务代码必须按批准的 Slice Implementation Contract 逐切片实现。
 - 若目标工程已经存在，直接返回 `unsupported`。旧项目继续按原工程维护；需要现代化时单独立项、先评估再逐切片迁移，不属于本 skill。
 - 输出目录必须显式指定；目标工程目录必须不存在，`--force` 永久拒绝。
-- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。`git-submodule` gitlink、空挂载点、detached HEAD 工作树不得覆盖生成，即使传入 `--force` 也不得当成普通目录，且不得走「请显式传入 `--force`」普通目录覆盖 / rename 路径。`--output-dir` 指向 detached HEAD 子仓时不得 mkdir、staging 或生成工程。先 `git submodule update --init` 并在子仓附加分支工作树内生成。生成器必须先调用 `gitSubmoduleScaffoldViolation`，再在 exists / `--force` / rename 之前调用 `refuseGitlinkAsRegularDirectory`。
+- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。`git-submodule` gitlink、空挂载点、detached HEAD 工作树不得覆盖生成，即使传入 `--force` 也不得当成普通目录，且不得走「请显式传入 `--force`」普通目录覆盖 / rename 路径。`--output-dir` 指向 detached HEAD 子仓时不得 mkdir、staging 或生成工程。先 `git submodule update --init` 并在子仓附加分支工作树内生成。维护生成器时按 [守卫顺序](references/generator-maintenance.md) 检查，不能将 gitlink 当普通目录。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
 - 生成时的工程基线由本 skill 的 `references/engineering-baseline.md` 持有并绑定摘要；它不是独立 Skill。生成后必须回到 实现合同编译器，并按批准切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller`、`yss-dto`、`yss-exception`、`yss-validation`、`mapstruct`、`lombok`、`alibaba-java-code-style` 等实际命中的行为 skill。
@@ -103,7 +74,7 @@ node scripts/run_first_slice_verification.mjs \
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
 - 脚手架合同必须携带 `contract_id`、`contract_version`、实现合同编译器 draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
-- 新脚手架只接受统一 Project Scaffold Contract schema v4，并必须以原始字节摘要绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 必须闭包绑定同一 OpenAPI YAML 字节的 Validation、独立 Review、Freeze 与工程批准；`not-applicable` 必须绑定评估、明确原因和证据且禁止空占位资产。历史 schema v3/v2 仅用于 Manifest 只读验证和补齐 API 对账后的恢复审计，不用于新生成。
+- 新脚手架只接受统一 Project Scaffold Contract schema v4，并必须以原始字节摘要绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 必须闭包绑定同一 OpenAPI YAML 字节的 Validation、独立 Review、Freeze 与工程批准；`not-applicable` 必须绑定评估、明确原因和证据且禁止空占位资产。历史 Manifest 只读审计见 [历史兼容边界](references/generator-maintenance.md)，不得用于新生成。
 - DDD 固定 `target-domain-model`、`mybatis-plus`、H2 验证、`web` DTO、`yss-internal`；平台与 Validation 命名空间由共享清单约束。普通 MyBatis、独立 client module、client-in-domain 和其他旧架构仍为 `unsupported`。
 - 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation`、实际输出路径和固定三条验证命令，不接受仅凭任意字符串引用的放行。
 - 生成项目必须写入 Manifest v4 `.yss/scaffold-generation.json`，记录技术、数据与 API 设计门禁、架构选择及 digest、生成器、合同 digest、Target Profile、模块闭包、模板 digest、下游完整 当前合同 freshness、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 实现合同编译器。

package/template/.agents/skills/yss-ddd-scaffold-generator/references/command-examples.md

@@ -0,0 +1,32 @@
+## 推荐命令
+
+```bash
+node scripts/generate_and_verify_scaffold.mjs \
+  --project-name my-service \
+  --base-package com.yss.myservice \
+  --group-id com.yss.datamiddle \
+  --project-version 1.0.0-SNAPSHOT \
+  --parent-group-id com.yss.datamiddle \
+  --parent-artifact-id yss-datamiddle-parent \
+  --parent-version 2.0.0-SNAPSHOT \
+  --yss-components-version 2.0.0-SNAPSHOT \
+  --output-dir /path/to/implementation-repo \
+  --contract-id <approved-scaffold-contract-id> \
+  --contract-version <current-version> \
+  --approval-ref <lifecycle-approval-ref> \
+  --compiler-draft-ref <compiler-draft-ref> \
+  --persisted-ref <persisted-contract-ref> \
+  --contract-file /path/to/persisted-scaffold-contract.json \
+  --evidence-dir /path/to/evidence/scaffold
+```
+
+完成批准的 golden first slice 后运行：
+
+```bash
+node scripts/run_first_slice_verification.mjs \
+  --project-root /path/to/implementation-repo/my-service \
+  --slice-contract-file /path/to/approved-slice-contract.yaml \
+  --contract-root /path/to/contract-repository \
+  --approval-ref docs/approved-checkpoint.yaml \
+  --evidence-dir /path/to/evidence/first-slice
+```

package/template/.agents/skills/yss-ddd-scaffold-generator/references/generator-maintenance.md

@@ -0,0 +1,7 @@
+# 生成器维护与历史审计
+
+仅维护生成器或审计历史 Manifest 时读取；正常新生成继续消费入口中的批准合同与当前 schema。
+
+生成器必须先调用 `gitSubmoduleScaffoldViolation`，再在 exists / `--force` / rename 之前调用 `refuseGitlinkAsRegularDirectory`。
+
+历史 schema v3/v2 仅用于 Manifest 只读验证和补齐 API 对账后的恢复审计，不用于新生成。

package/template/.agents/skills/yss-design-system/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-design-system
-description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格基线。涉及页面设计、原型评审、UI 实现、组件选型、主题 token、颜色排版间距、响应式验收、Ant Design/YSS UI 风格一致性、docs/design/design.md 更新或从外部设计系统引入规范时必须使用。
+description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一致性；用于设计规范变更、原型评审及按当前设计基线验收。
 ---
 
 # YSS Design System
@@ -18,7 +18,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 - Codex `$design-qa` 项目对照：`references/design-qa-theme.md`，不替代官方 `design-qa` 流程，也不改上游插件正文。
 - 原型阶段合同：`yss-prototype-stage`，用于统一 H1/H2 原型资产和浏览器验证证据。H1/H2 默认使用项目 Token 驱动的 HTML/CSS/JavaScript 离线原型。
 
-如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 Token，必须按 `DESIGN.md` → `docs/design/design.md` → `docs/design/tokens/*` 顺序读取；若要执行评审或实现检查，再读 `references/design-system.md`。
+如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 Token，必须按 `DESIGN.md` → `docs/design/design.md` 顺序读取，再按当前主题、密度与输出表面选择对应 Token 文件，不全量预读所有主题；若要执行评审或实现检查，再读 `references/design-system.md`。
 
 ## 使用流程
 

package/template/.agents/skills/yss-domain/SKILL.md

@@ -1,19 +1,21 @@
 ---
 name: yss-domain
-description: 用于构建或重构 YSS 领域层代码。当用户要求设计聚合、Entity、Domain Gateway、领域规则、状态流转或先做领域建模再补持久层时调用。
+description: 按已批准的 DDD 技术设计实现或重构领域行为、不变量、状态机与 Gateway；不负责起草领域设计。
 ---
 
 # yss-domain
 
 这是一个领域实现 skill。核心目标是消费已批准的战术模型，将领域行为落实为代码；`yss-technical-design` 组织 DDD 分支，由 `yss-tactical-design` 设计、`yss-product-lifecycle` 维护批准。
 
+既有工程先读取 `references/existing-project.md`，按登记的职责和批准边界审计或整改；只读审计不要求批准 Slice。
+
 本 skill 在新脚手架链路只支持 `domain-driven` / `target-domain-model`。`layered-mvc-service` 与 `mvc-data-analysis-v1` 是独立 MVC Profile，不是失败的 DDD 工程；它们不加载本 skill，也不生成 Domain Gateway。既有旧架构不在本链路内迁移。
 
 ## 何时使用
 
-- 用户要求先做 Domain、先抽象实体或聚合。
-- 用户要补 `Entity`、`Gateway`、领域规则或状态机。
-- 用户给出页面流程、业务规则、DDL，希望先沉淀领域模型。
+- 当前已批准的 DDD Slice Contract 要求实现或修复领域行为、不变量或状态机。
+- 在既有已确认领域边界内重构 Entity、Value Object、Domain Event 或 Gateway。
+- 需要从需求、页面或 DDL 决定聚合及领域边界时，回交 `yss-technical-design` / `yss-tactical-design`，不先写领域代码。
 
 ## 不适用
 
@@ -36,17 +38,27 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 ## 建模约束
 
+<a id="domain.dependencies"></a>
+<!-- yss-rule {"id":"domain.dependencies","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - Domain 层不依赖 Repository、Mapper、Controller。
+<a id="domain.behavior"></a>
+<!-- yss-rule {"id":"domain.behavior","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - 领域行为放在模型方法，不要放在 Web 层。
+<a id="domain.gateway"></a>
+<!-- yss-rule {"id":"domain.gateway","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - Gateway 只暴露领域能力，不暴露持久化细节。
 - 对关键状态流转给出明确方法，如 `publish()`、`cancel()`、`terminate()`。
+<a id="domain.invariants"></a>
+<!-- yss-rule {"id":"domain.invariants","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - 明确 Aggregate Root、Entity identity、Value Object、不变量、Domain Event 和一致性边界；没有业务行为时不要伪造富领域模型。
-- 发现旧架构时停止套用新脚手架合同并返回 `unsupported`；旧项目继续按原工程维护，现代化改造单独立项。
+- `unsupported` 只阻断不支持的生成方式。既有 DDD 按登记边界整改；目录差异不是领域违规。架构身份转换或公开契约迁移单独立项，MVC 不套用 DDD 规则。
 
 ## 质量要求
 
 - 命名体现业务语义，不照抄表名缩写。
 - 生成代码应可编译，且没有跨层依赖泄漏。
+<a id="domain.gateway-owner"></a>
+<!-- yss-rule {"id":"domain.gateway-owner","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - Domain Gateway interface 由本 skill 唯一拥有；Infrastructure 只能实现，不得由 `yss-repository` 反向创建或改写其签名。
 - 对不确定规则返回 `new_impacts` / `drift` 并暂停；不要把未批准假设或 TODO 写进实现冒充已确认事实。
 

package/template/.agents/skills/yss-domain/references/domain-layer-guide.md

@@ -1,6 +1,6 @@
 # YSS Domain Target Profile 指南
 
-本指南只定义新 DDD `target-domain-model`。历史 DTO/VO 型 Gateway、`core/client/repository` 和贫血对象均为 `unsupported`，不存在旧架构 Profile 或迁移分支。
+本指南的目录和生成布局只定义新 DDD `target-domain-model`。既有 DDD 通过 [既有工程边界](existing-project.md) 应用领域语义规则；历史目录或贫血对象不能单凭名称判违规。HTTP DTO/VO 穿入领域端口仍须按登记职责检查。架构迁移不属于生成器。
 
 ## 1. Domain 所有权
 
@@ -98,7 +98,7 @@ Web Exception Translator 再将它映射为批准的状态码、错误码和消
 - 消费批准且当前的 Tactical Design 与 Slice Implementation Contract。
 - 返回 YSS Skill Execution Result，包含 Domain 文件、行为测试、ArchUnit 结果及实际 `./mvnw ...` 证据。
 - 新聚合、不变量、状态机或跨上下文影响进入 `new_impacts` 并暂停。
-- 检测到旧架构时返回 `unsupported`；如需现代化，退出 scaffold 工作流并单独立项评估。
+- 旧布局不走 scaffold 生成分支；既有 DDD 按登记整改。需改变架构或公开契约时单独评估并批准。
 
 ## 聚合创建与重建
 

package/template/.agents/skills/yss-domain/references/existing-project.md

@@ -0,0 +1,5 @@
+# 既有领域工程
+
+只对 `existing-domain-driven-maven` 或登记为 DDD 的只读盘点范围应用领域语义。读取实际 build unit、role_paths、source roots 与工程基线；不要求 target 模块名、Entity 后缀或生成 Manifest。创建/重建、不变量、端口所有权和技术依赖边界仍按 domain-layer-guide 检查。MVC 不创建聚合或 Gateway。
+
+只读审计允许缺设计资产，但记录 missing_evidence。修改消费当前批准 Slice 和已确认行为 seam；不得从历史代码伪造业务规则批准。新增聚合、改变一致性或架构身份回设计与合同编译器。

package/template/.agents/skills/yss-dto/SKILL.md

@@ -44,6 +44,8 @@ description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO
 
 - 写操作参数优先继承 `CommandDTO`。
 - Application/Infrastructure 内部读参数可按项目 Profile 使用 `QueryDTO` 或 `PageQuery`。
+<a id="dto.page-input"></a>
+<!-- yss-rule {"id":"dto.page-input","when":"pagination","level":"mandatory","evidence":"code-and-verification"} -->
 - 公开 HTTP Page Request 默认不继承 `PageQuery`，只复制冻结 OpenAPI 允许的分页字段，再由 WebConvertor 转为 Application Query；避免继承的 `offset`、`needTotalCount`、`tempTotalCount` 进入绑定面。
 - Controller 返回优先使用项目既有的 `Result` 或派生结果对象。
 - 单对象返回优先 `SingleResult`，列表返回优先 `MultiResult`，分页返回优先 `PageResult`，前提是当前项目已采用这套体系。
@@ -54,27 +56,24 @@ description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO
 - `PageResult` 当前稳定公共字段为 `totalCount/pageSize/pageIndex/data[]`；`totalPages` 是计算 getter，只有目标 HTTP mapper / contract fixture 证明后才能进入具体契约。
 - `PageQuery` 客户端输入只允许 `pageIndex/pageSize/orderBy/orderDirection/groupBy`（后四项按 profile 的 optional / whitelist 规则）；`orderDirection` 只能是 `ASC|DESC`。`offset`、`needTotalCount`、`tempTotalCount` 是计算或内部协作字段，禁止成为客户端输入。
 - `buildSuccess(...)` 各重载设置 code 的行为并不一致；冻结契约必须测试 `success/code/message/tips/dataType`、nullability 和三种 data shape，不能只测试 data。
+<a id="dto.wire-evidence"></a>
+<!-- yss-rule {"id":"dto.wire-evidence","when":"wire","level":"mandatory","evidence":"code-and-verification"} -->
 - Java getter、Lombok、`@JsonIgnore` 或默认 Jackson 结果都不是目标 HTTP wire fact；冻结前必须记录 mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP 证据。
+<a id="dto.boundary"></a>
+<!-- yss-rule {"id":"dto.boundary","when":"wire","level":"mandatory","evidence":"code-and-verification"} -->
 - DTO 只表达接口契约，不承载 Repository PO 或领域对象的持久化细节。
 
 ## 检查清单
 
-- 分页字段名是否和框架约定一致。
-- `orderBy` / `groupBy` 是否经过 Repository 白名单映射，禁止直接拼接 SQL。
-- Application Query Port / Infrastructure 是否收到批准的分页语义；Domain Gateway 不接收 `PageQuery`。
-- 新增 DTO 是否与现有序列化和校验方式兼容。
-- 返回结构是否和前端或上游调用方契约一致。
-- 是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。
-- wrapper extension、`YssResultMeta`、`allOf`、具体 data schema 和方向性是否逐 endpoint 对齐。
-- 是否有针对 `offset` / `needTotalCount` / `tempTotalCount` 的负向断言，以及对 `totalPages` 的目标 mapper 证据。
-- Controller、Application Service、Domain、Repository 之间是否存在 DTO/VO/DO/PO 混穿。
-- 前端 Orval 或调用方是否依赖当前返回包装结构。
+仅在 DTO/OpenAPI wire shape 受影响时读取 [wire 验收清单](references/wire-validation-checklist.md)，按当前平台和请求/响应方向执行；权威字段形状继续由 `references/openapi-wire-profile.yaml` 持有。
 
 ## 修改约束
 
 - 不要在一个项目里混用多套返回包装类。
 - 不要新建与 `PageQuery` 含义重叠的分页基类。
 - 不要把 `com.yss.cloud.dto.response` 作为新 API 的 canonical 包，也不要从 Java getter 机械生成 wire schema。
+<a id="dto.no-leak"></a>
+<!-- yss-rule {"id":"dto.no-leak","when":"pagination","level":"mandatory","evidence":"code-and-verification"} -->
 - 不要把 `offset`、`needTotalCount`、`tempTotalCount` 作为客户端分页输入；不要无证据把 `totalPages` 写入所有分页响应。
 - 若项目已有 `SingleResult`、`PageResult`、`MultiResult` 体系，优先保持一致。
 
@@ -95,3 +94,7 @@ description: "实现或核验 YSS Result、PageResult、PageQuery、CommandDTO
 ## 平台与源码门禁
 
 接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-dto --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
+
+## 既有契约与特殊协议
+
+只读审计先辨认已锁定的 wire 契约。下载、流式和第三方回调按批准协议检查媒体类型、状态、Header、错误与权限边界；不强套 Result，也不因声称“特殊接口”豁免契约证据。普通已采用 YSS wrapper 的接口继续按 wire profile 检查。旧包/旧协议差距单列迁移，不静默改锁或改公开响应。

package/template/.agents/skills/yss-dto/references/wire-validation-checklist.md

@@ -0,0 +1,14 @@
+## 检查清单
+
+- 分页字段名是否和框架约定一致。
+<a id="dto.sort"></a>
+<!-- yss-rule {"id":"dto.sort","when":"pagination","level":"mandatory","evidence":"code-and-verification"} -->
+- `orderBy` / `groupBy` 是否经过 Repository 白名单映射，禁止直接拼接 SQL。
+- Application Query Port / Infrastructure 是否收到批准的分页语义；Domain Gateway 不接收 `PageQuery`。
+- 新增 DTO 是否与现有序列化和校验方式兼容。
+- 返回结构是否和前端或上游调用方契约一致。
+- 是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。
+- wrapper extension、`YssResultMeta`、`allOf`、具体 data schema 和方向性是否逐 endpoint 对齐。
+- 是否有针对 `offset` / `needTotalCount` / `tempTotalCount` 的负向断言，以及对 `totalPages` 的目标 mapper 证据。
+- Controller、Application Service、Domain、Repository 之间是否存在 DTO/VO/DO/PO 混穿。
+- 前端 Orval 或调用方是否依赖当前返回包装结构。

package/template/.agents/skills/yss-exception/SKILL.md

@@ -47,12 +47,12 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 - Required dependency or starter module is present.
 - Error code/message are meaningful to API consumers.
 - Response messages are sanitized and do not expose raw RuntimeException or localized exception details.
-- HTTP assertions cover business 4xx, unknown/runtime 5xx, upload 413, and `X-Trace-Id`.
+- For affected boot3-java17 HTTP seams, assert the documented business 4xx, unknown/runtime 5xx and trace header behavior. Assert upload 413 only for upload-limit impact. Boot 2 assertions follow its own source and frozen contract; do not import Boot 3 behavior into it.
 - Business validation failures are not reported as unknown system errors.
 - Stack traces are preserved in structured logger output for unknown/system failures, never printed directly to stderr or serialized to clients.
 - Retry guidance matches exception type.
 - Known system failures use `ExceptionFactory.sysException(..., cause)`; Application code does not replace them with ad-hoc `RuntimeException`.
-- Endpoint contract tests cover business, known-system, unknown/runtime, and upload-limit failures; unknown public messages never expose `getLocalizedMessage()`.
+- Endpoint tests cover the failure types actually affected by this change; upload-limit tests apply only to upload endpoints or changed upload handling. Public messages must follow the selected platform contract and never leak protected exception details.
 
 ## Do Not
 

package/template/.agents/skills/yss-formily-schema-generator/SKILL.md

@@ -3,9 +3,9 @@ name: yss-formily-schema-generator
 description: "从需求或设计图生成 YFormily JSON Schema 与表单代码；仅用于生产表单实现。"
 ---
 
-# YssFormily Schema Generator
+# YFormily Schema Generator
 
-Use this skill to turn upstream input into downstream YssFormily form artifacts.
+Use this skill to turn upstream input into downstream YFormily form artifacts.
 
 Supported input forms:
 
@@ -16,13 +16,13 @@ Supported input forms:
 
 Expected output forms:
 
-- a YssFormily JSON Schema or `ISchema`
+- a YFormily JSON Schema or `ISchema`
 - a recommended `v-model` data shape
 - optional `scope`, `effects`, and slot plan
-- optional Vue render snippet showing how to mount `YssFormily`
+- optional Vue render snippet showing how to mount `YFormily`
 
 This skill designs the schema.
-For implementation rules and exact YssFormily behavior, also read:
+For implementation rules and exact YFormily behavior, also read:
 
 - [yss-formily](../yss-formily/SKILL.md)
 
@@ -35,10 +35,10 @@ For conversion workflow and field mapping, read:
 Use this skill when the request is any of the following:
 
 - “根据需求描述生成表单 schema”
-- “根据原型图生成 YssFormily”
+- “根据原型图生成 YFormily”
 - “根据图片/截图还原表单”
 - “根据 Figma 生成表单 JSON Schema”
-- “把业务字段整理成 YssFormily schema”
+- “把业务字段整理成 YFormily schema”
 - “输出 schema 和渲染代码”
 
 ## Core principle
@@ -50,7 +50,7 @@ Translate the input into a stable form model:
 2. field semantics
 3. validation and dependency rules
 4. layout grouping
-5. YssFormily schema
+5. YFormily schema
 
 The schema must reflect business meaning, not just pixel arrangement.
 
@@ -88,7 +88,7 @@ If the image contains only visual cues and no validation semantics, generate a s
 
 ### Figma input
 
-When a Figma link or node is provided, use the Figma workflow to inspect the design first.
+When a Figma link or node is provided, discover an available design-inspection capability first. If unavailable, use supplied design exports or screenshots; report the missing access when those cannot establish a required detail. Do not invent a tool name or claim inspection succeeded.
 Extract:
 
 - field labels
@@ -99,7 +99,7 @@ Extract:
 - readonly versus editable patterns
 - footer actions
 
-Then convert that structure to YssFormily, following local YSS conventions instead of raw design-tool naming.
+Then convert that structure to YFormily, following local YSS conventions instead of raw design-tool naming.
 
 ## Required outputs
 
@@ -120,7 +120,7 @@ If the user asks for code generation, also produce:
 
 Always align with `yss-formily`:
 
-- wrapper component is `YssFormily` or `YFormily`
+- wrapper component for new code is `YFormily`; the historical `YssFormily` alias is accepted only when an existing installed export is verified
 - schema is `FormLayout -> FormGrid -> fields`
 - use `FormItem` for ordinary fields
 - prefer one shared schema for create/edit/detail when feasible
@@ -151,7 +151,7 @@ Follow this sequence every time:
 4. Decide field types and components.
 5. Decide sections and layout spans.
 6. Identify validation, enum, and linkage requirements.
-7. Produce YssFormily schema.
+7. Produce YFormily schema.
 8. Produce render snippet if requested.
 9. Call out assumptions and uncertain inferences.
 

package/template/.agents/skills/yss-hook/SKILL.md

@@ -43,7 +43,7 @@ description: Use when YSS Vue 页面涉及 vue-hooks-plus/useRequest、分页、
 ```ts
 export function useReportTable() {
   const tableData = ref<any[]>([]);
-  const currentParams = ref({ page: 1, pageSize: 20 });
+  const currentParams = ref({ pageIndex: 1, pageSize: 20 });
   const pagination = reactive({
     current: 1, pageSize: 20, total: 0,
     showSizeChanger: true, showQuickJumper: true,
@@ -52,8 +52,8 @@ export function useReportTable() {
   const { loading, run: fetchList } = useRequest(apiFn, {
     manual: true,
     onSuccess: (res) => {
-      tableData.value = res?.data?.list || [];
-      pagination.total = res?.data?.total || 0;
+      tableData.value = res?.data || [];
+      pagination.total = res?.totalCount || 0;
     },
     onError: () => {
       tableData.value = [];
@@ -64,60 +64,24 @@ export function useReportTable() {
     currentParams.value = { ...currentParams.value, ...params };
     return fetchList(currentParams.value);
   };
-  const handlePageChange = (current: number, pageSize: number) => {
+  // YTable emits one object; adapt it at this boundary.
+  const handlePageChange = ({ current, pageSize }: { current: number; pageSize: number }) => {
     pagination.current = current;
     pagination.pageSize = pageSize;
-    return query({ page: current, pageSize });
+    return query({ pageIndex: current, pageSize });
   };
   return { loading, tableData, currentParams, pagination, query, handlePageChange };
 }
 ```
 
 - 仅当项目已批准的请求库支持时使用 `useRequest`；通常使用 `manual: true`，除非需求明确要求挂载即请求。
-- `currentParams` 是唯一参数源。筛选变化重置 `page: 1`；翻页只改 `page/pageSize`；刷新、导出和编辑后重载复用它。
+- `currentParams` 是唯一参数源。筛选变化重置 `pageIndex: 1`；翻页只改 `pageIndex/pageSize`；刷新、导出和编辑后重载复用它。
 - 在 Hook 内处理成功、失败、空数据和响应映射；旧列表会误导时才在失败时清空。
 - 树数据同样由 Hook 暴露 `treeData`、`treeLoading`、`selectedKey`、`handleSelect`，并在其中处理会触发加载的选中副作用。
 
 ## 3. `vue-hooks-plus/useRequest`（项目已批准时）
 
-`useRequest` 接收返回 `Promise<TData>` 的 service，并以插件组合管理 `loading`、`data`、`error`、`params`。自动模式默认在组件初始化时执行；`manual: true` 时用 `run` 或 `runAsync` 发起请求。
-
-```ts
-import { useRequest } from 'vue-hooks-plus';
-
-const { data, error, loading, params, run, runAsync, refresh, mutate, cancel } = useRequest(
-  searchReports,
-  {
-    manual: true,
-    debounceWait: 300,
-    onSuccess: (result, requestParams) => {
-      tableData.value = result.list;
-      pagination.total = result.total;
-    },
-    onError: (cause) => { requestError.value = cause; },
-  },
-);
-```
-
-- `run` 会捕获异常并交给 `onError`；`runAsync` 返回 `Promise`，调用处必须自行 `catch`。`refresh` / `refreshAsync` 使用上一次 `params` 重发请求；不要在页面重拼参数。
-- `mutate(nextData | updater)` 用于乐观更新；启用 `rollbackOnError` 时，远端失败会恢复更新前数据。先保存局部错误 / 刷新策略，不能只依赖乐观 UI。
-- `cancel()` 会忽略当前 Promise 的结果和错误，并会取消仍在等待执行的防抖调用；它**不会**终止底层 Promise。若 transport 支持真正中止，service 才能额外使用其已验证的 `AbortSignal` 支持。
-- 搜索场景优先 `debounceWait`（毫秒），并按需要配置 `debounceLeading`、`debounceTrailing`、`debounceMaxWait`。组件卸载与后一次请求的竞态响应会被库忽略；需要提前停止时调用 `cancel()`。不要再叠加自定义 timer / 序号，除非已验证当前版本或 transport 存在库无法覆盖的缺口。
-- `useRequest` 的并发语义在文档版本间出现差异：页面说明从 v2.4.0 起手动调用可独立执行，而 Options 表仍列出 `concurrent`（默认 `false`）控制新旧请求关系。启用并发前，必须以项目锁定版本的类型、测试与行为为准；搜索和同一资源写入默认采用单一最新请求策略。
-
-### 3.1 缓存、刷新与重试
-
-- `cacheKey` 成功后会全局共享 data 和 params：同 key 的并发实例共用 Promise、数据同步。因此 key 必须包含稳定的业务身份与影响结果的参数；不同租户、用户、筛选条件或权限视图不能共用 key。副作用、实时性强或权限敏感结果默认不启用共享缓存。
-- `staleTime` 内数据视为新鲜，不重新请求；`cacheTime` 到期清除缓存。没有 `staleTime` 时，重新挂载会先展示缓存、再后台请求（SWR）。编辑 / 提交成功后的显式 `refresh` 优先于等待 SWR。
-- `refreshOnWindowFocus: true` 在 `visibilitychange` / `focus` 后刷新，使用 `focusTimespan`（默认 5000ms）限频。只给允许后台重取的读模型开启；编辑中的表单、一次性动作和高成本查询默认关闭。
-- `retryCount` 控制失败后的重试次数，`-1` 为无限重试；未设 `retryInterval` 时按 2s、4s…且最高 30s 的指数退避。仅对暂时性网络 / 可恢复服务错误设置有限重试；认证授权、参数校验、业务拒绝、显式取消和非幂等写操作禁止自动重试。`cancel()` 可停止正在等待的重试。
-- `loadingDelay` 可延迟 loading 变为 `true`，避免短请求闪烁；它不延迟请求，也不能作为防抖替代。
-
-### 3.2 请求轮询与依赖刷新
-
-- `pollingInterval > 0` 启用请求轮询；每次请求完成后等待间隔再发下一次。`manual: true` 时，先 `run/runAsync` 才启动。`pollingWhenHidden` 默认 `true`；仅在业务允许后台继续请求时保留，需暂停则显式设为 `false`。`pollingErrorRetryCount` 默认 `-1`，必须为生产读模型配置有限值或明确停止条件。
-- 同一数据源只能选择 `useRequest` 轮询或 YSS `usePollingTask` 之一，禁止嵌套或同时运行。手动刷新前 `cancel()` 当前请求 / 轮询，执行带 loading 的 `refresh`，再依据明确业务规则恢复轮询。
-- `refreshDeps` 仅在非 manual 自动模式生效；传入 `WatchSource[]` 精确声明依赖，或在理解捕获范围后用 `true` 自动收集。筛选列表通常使用显式 `query` 并在筛选变化时重置页码，不以 `refreshDeps` 隐式驱动复杂参数。
+仅项目已批准且当前任务使用该库时，读取 [useRequest 实现细则](references/use-request.md)，覆盖返回值、错误处理、取消、缓存、刷新、重试和轮询。不得因技能示例引入未批准依赖；调用 `runAsync` 必须捕获拒绝，业务失败提示遵循 mutator 的唯一所有权。
 
 ## 4. 单一异步动作：`useLoading`
 

package/template/.agents/skills/yss-hook/references/use-request.md

@@ -0,0 +1,42 @@
+# 已批准的 useRequest 实现细则
+
+仅项目已批准 `vue-hooks-plus/useRequest` 且当前任务使用它时读取。版本事实以项目锁定依赖为准。
+
+`useRequest` 接收返回 `Promise<TData>` 的 service，并以插件组合管理 `loading`、`data`、`error`、`params`。自动模式默认在组件初始化时执行；`manual: true` 时用 `run` 或 `runAsync` 发起请求。
+
+```ts
+import { useRequest } from 'vue-hooks-plus';
+
+const { data, error, loading, params, run, runAsync, refresh, mutate, cancel } = useRequest(
+  searchReports,
+  {
+    manual: true,
+    debounceWait: 300,
+    onSuccess: (result, requestParams) => {
+      tableData.value = result.list;
+      pagination.total = result.total;
+    },
+    onError: (cause) => { requestError.value = cause; },
+  },
+);
+```
+
+- `run` 会捕获异常并交给 `onError`；`runAsync` 返回 `Promise`，调用处必须自行 `catch`。`refresh` / `refreshAsync` 使用上一次 `params` 重发请求；不要在页面重拼参数。
+- `mutate(nextData | updater)` 用于乐观更新；启用 `rollbackOnError` 时，远端失败会恢复更新前数据。先保存局部错误 / 刷新策略，不能只依赖乐观 UI。
+- `cancel()` 会忽略当前 Promise 的结果和错误，并会取消仍在等待执行的防抖调用；它**不会**终止底层 Promise。若 transport 支持真正中止，service 才能额外使用其已验证的 `AbortSignal` 支持。
+- 搜索场景优先 `debounceWait`（毫秒），并按需要配置 `debounceLeading`、`debounceTrailing`、`debounceMaxWait`。组件卸载与后一次请求的竞态响应会被库忽略；需要提前停止时调用 `cancel()`。不要再叠加自定义 timer / 序号，除非已验证当前版本或 transport 存在库无法覆盖的缺口。
+- `useRequest` 的并发语义在文档版本间出现差异：页面说明从 v2.4.0 起手动调用可独立执行，而 Options 表仍列出 `concurrent`（默认 `false`）控制新旧请求关系。启用并发前，必须以项目锁定版本的类型、测试与行为为准；搜索和同一资源写入默认采用单一最新请求策略。
+
+### 3.1 缓存、刷新与重试
+
+- `cacheKey` 成功后会全局共享 data 和 params：同 key 的并发实例共用 Promise、数据同步。因此 key 必须包含稳定的业务身份与影响结果的参数；不同租户、用户、筛选条件或权限视图不能共用 key。副作用、实时性强或权限敏感结果默认不启用共享缓存。
+- `staleTime` 内数据视为新鲜，不重新请求；`cacheTime` 到期清除缓存。没有 `staleTime` 时，重新挂载会先展示缓存、再后台请求（SWR）。编辑 / 提交成功后的显式 `refresh` 优先于等待 SWR。
+- `refreshOnWindowFocus: true` 在 `visibilitychange` / `focus` 后刷新，使用 `focusTimespan`（默认 5000ms）限频。只给允许后台重取的读模型开启；编辑中的表单、一次性动作和高成本查询默认关闭。
+- `retryCount` 控制失败后的重试次数，`-1` 为无限重试；未设 `retryInterval` 时按 2s、4s…且最高 30s 的指数退避。仅对暂时性网络 / 可恢复服务错误设置有限重试；认证授权、参数校验、业务拒绝、显式取消和非幂等写操作禁止自动重试。`cancel()` 可停止正在等待的重试。
+- `loadingDelay` 可延迟 loading 变为 `true`，避免短请求闪烁；它不延迟请求，也不能作为防抖替代。
+
+### 3.2 请求轮询与依赖刷新
+
+- `pollingInterval > 0` 启用请求轮询；每次请求完成后等待间隔再发下一次。`manual: true` 时，先 `run/runAsync` 才启动。`pollingWhenHidden` 默认 `true`；仅在业务允许后台继续请求时保留，需暂停则显式设为 `false`。`pollingErrorRetryCount` 默认 `-1`，必须为生产读模型配置有限值或明确停止条件。
+- 同一数据源只能选择 `useRequest` 轮询或 YSS `usePollingTask` 之一，禁止嵌套或同时运行。手动刷新前 `cancel()` 当前请求 / 轮询，执行带 loading 的 `refresh`，再依据明确业务规则恢复轮询。
+- `refreshDeps` 仅在非 manual 自动模式生效；传入 `WatchSource[]` 精确声明依赖，或在理解捕获范围后用 `true` 自动收集。筛选列表通常使用显式 `query` 并在筛选变化时重置页码，不以 `refreshDeps` 隐式驱动复杂参数。

package/template/.agents/skills/yss-implementation-contract-compiler/SKILL.md

@@ -66,11 +66,7 @@ description: "编译或重验 YSS Slice Implementation Contract、最小 Skill
 
 ## 战略交接快照包
 
-跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。
-
-来自战略交接包的技术设计合同（DDD / MVC）必须绑定 `strategic_handoff` 导入收据、包摘要、正式目标对账及逐条承接 rows。来自导入包时禁止仅填 `upstream_current: true`。批准前执行 `scripts/verify-strategic-handoff-consumption --root <target> <tactical>`；存在受控延期时按切片执行 `--slice <slice-id>`，实际核验通过且合同批准后才可继续相关切片。最新源规则、关键场景或资产变化使依赖项 stale；未知依赖扩大阻断，业务冲突回交战略方。结果绑定当前包与战术摘要，不能复用旧输出宣布 ready-for-agent。
-
-Slice v3 的任务进度、缺口和实时就绪结果不回写合同。源事实集中在 basis，Skill 闭包只在 resolution 保存，工作单元继承共同约束；独立工程审查与已有用户确认共同交生命周期批准。详见合同引用。
+消费战略包时必须绑定导入收据、包摘要、目标对账和逐条承接。按 [跨仓承接核验](references/strategic-handoff-routing.md) 执行；源变化使依赖项 stale，未知依赖扩大阻断，编译器不能补字段后沿用旧批准。
 
 ## 后端脚手架平台承接
 

package/template/.agents/skills/yss-implementation-contract-compiler/references/strategic-handoff-routing.md

@@ -0,0 +1,7 @@
+## 战略交接快照包
+
+跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。
+
+来自战略交接包的技术设计合同（DDD / MVC）必须绑定 `strategic_handoff` 导入收据、包摘要、正式目标对账及逐条承接 rows。来自导入包时禁止仅填 `upstream_current: true`。批准前执行 `scripts/verify-strategic-handoff-consumption --root <target> <tactical>`；存在受控延期时按切片执行 `--slice <slice-id>`，实际核验通过且合同批准后才可继续相关切片。最新源规则、关键场景或资产变化使依赖项 stale；未知依赖扩大阻断，业务冲突回交战略方。结果绑定当前包与战术摘要，不能复用旧输出宣布 ready-for-agent。
+
+Slice v3 的任务进度、缺口和实时就绪结果不回写合同。源事实集中在 basis，Skill 闭包只在 resolution 保存，工作单元继承共同约束；独立工程审查与已有用户确认共同交生命周期批准。详见合同引用。

package/template/.agents/skills/yss-implementation-contract-compiler/references/yss-skill-execution-result.md

@@ -32,7 +32,9 @@ execution_result:
       result:
       executed_at:
   constraint_results:
-    - constraint:
+    - constraint_id: # 后端审查时为 canonical 稳定 ID
+      applicability_basis: [] # 后端覆盖工具派生依据
+      constraint:
       status: passed | failed | not-applicable
       evidence_ref:
   doubt_driven_review:
@@ -70,3 +72,5 @@ execution_result:
 专项 skill 自报 `implemented` 不等于最终通过，生命周期编排器和独立 Reviewer 必须复核。
 
 `verification_results` 不得为空，每项必须包含非空 `command`、`result` 和 `executed_at`。路径校验按完整目录边界判断，`apps/backend/project1-escape` 不属于 `apps/backend/project1/`；Harness 内路径还必须通过项目路径策略。完整重路由时旧合同必须标记 `stale`，新合同版本递增并保留旧合同引用、失效原因和触发器。
+
+后端独立审查在既有 constraint_results 中消费稳定规则 ID、规则/代码/证据摘要与完整适用性集合；输入增加 scope_kind 与 standards_coverage_ref/digest。见 yss-backend-spec-review/references/standards-coverage.md。实现者结果不代替独立 code-review；历史未携带新字段的报告只读兼容。

package/template/.agents/skills/yss-layered-mvc-scaffold-generator/SKILL.md

@@ -20,11 +20,11 @@ description: 在生命周期已批准的脚手架合同下生成通用 YSS 分
 
 调用本技能前由生命周期编排器展示 `scripts/backend-platforms` 的精确版本清单及兼容状态，并通过 `gate.backend-architecture-platform-approved` 把架构、Spring Boot、Java 和 YSS 父 POM/BOM 合并展示、取得真实用户确认；生成器不提问、不猜版本、不使用 `x` 或 `latest`。已有批准且当前的选择展示摘要后复用；既有工程核验并复用登记值，不触发该门禁。
 
-- 候选平台：Boot 2.7.18 / Java 8，Boot 3.5.16 / Java 17 或 21，Boot 4.1.1 / Java 17 或 21。新 Boot 默认推荐 Java 17；候选不等于可生成。
+- 精确候选版本与可选状态只读取 `scripts/backend-platforms` 和共享平台清单，不在此复制版本表；候选不等于可生成。
 - 独立子项目可继承主项目组合或覆盖，必须逐项目确认（允许一次确认明确列出的项目）；同一 Maven Reactor 使用一个平台。
 - 只开放共享兼容清单中已有真实 YSS 构建、依赖和启动证据的组合。缺少兼容父 POM、BOM、starter 或相应能力证据即 `blocked`；不替换官方组件、不降级回退。
 - 新生成合同必须有 `platform_configuration` v2，与架构决策、Maven 坐标及兼容条目摘要一致。Boot、Java、YSS 坐标或依赖配方变化时回生命周期重新确认并编译合同；仅追加同配置验证记录不重复确认，仍核验证据有效性。
-- Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Boot 3.5 / 4.1 拒绝 Java 8/11。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
+- Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Java 下限和允许组合由当前平台条目决定。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
 - 平台候选维护验证产物标记 `platform_verification=candidate`，不能交给业务生成、升级完成等级或进入首切片验证。测试夹具不证明 YSS 兼容。
 
 版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `docs/engineering/backend-platforms.md`。

package/template/.agents/skills/yss-mybatis/SKILL.md

@@ -16,11 +16,21 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 
 ## 稳定决策规则
 
+<a id="mybatis.binding"></a>
+<!-- yss-rule {"id":"mybatis.binding","when":"mybatis","level":"mandatory","evidence":"code-and-verification"} -->
 - 基类、Mapper 注解、XML 位置和扫描范围以批准 Profile、当前工程基线及当前组件源码共同决定；不得在既有体系外再造 Mapper 抽象。
+<a id="mybatis.pagination"></a>
+<!-- yss-rule {"id":"mybatis.pagination","when":"pagination","level":"mandatory","evidence":"code-and-verification"} -->
 - 一条查询 seam 只能有一个分页责任模型。核对实际插件/切面开关、拦截范围、参数绑定条件和返回 total 的责任，不以“依赖已引入”代替行为验证。
+<a id="mybatis.batch"></a>
+<!-- yss-rule {"id":"mybatis.batch","when":"batch","level":"mandatory","evidence":"code-and-verification"} -->
 - 批量写入必须证明是组件当前支持的 SQL 级批量能力，并验证分批大小、字段填充、主键和数据库方言；循环单条写入不能冒充批量 SQL。
 - 多数据源实例创建不等于动态路由、线程上下文切换或事务传播。先做 capability check；组件未提供的路由能力必须由批准的上层适配承担。
+<a id="mybatis.mapping"></a>
+<!-- yss-rule {"id":"mybatis.mapping","when":"mybatis","level":"mandatory","evidence":"code-and-verification"} -->
 - Mapper/XML、逻辑删除、审计字段、主键策略、动态排序/分组白名单和参数绑定必须与数据合同一致；任何 SQL/DDL/索引新影响返回 `new_impacts`。
+<a id="mybatis.transaction"></a>
+<!-- yss-rule {"id":"mybatis.transaction","when":"mybatis","level":"mandatory","evidence":"code-and-verification"} -->
 - 事务边界归批准的 Application 用例或 MVC service/core；Repository 不临时声明新的业务事务。
 
 ## 任务分流