create-yss-spec 3.4.8 → 3.4.10

package/template/.pi/skills/yss-api-integration/SKILL.md

@@ -43,7 +43,7 @@ description: "在 Vue3 YSS UI 中对接 Orval API；核验生成方法、mutator
 1. 读取 `yss-openapi-governance` 产出的 OpenAPI Freeze 记录和 `docs/.scratch/<feature>/api/<feature>-json-export.md`；确认 YAML SHA-256、JSON SHA-256、Redocly CLI 版本、lockfile 引用和 JSON 校验均通过。治理 JSON 的唯一产物路径是 `docs/.scratch/<feature>/api/<feature>.json`。
 2. JSON 导出由 `yss-openapi-governance` 负责。`api-integration` 只接受该 skill 留下的派生记录；记录中的锁定 `redocly bundle` 命令是治理导出证据，不是前端集成任意重跑的入口。
 3. **受控交接**：若前端实现仓库需要本地输入，批准的 Cross-repo 子合同或项目脚本只能将上述治理 JSON 原样物化为 `<frontend>/openapi/openapi.json`；物化后的 SHA-256 必须与派生记录一致。禁止从 URL、Draft YAML、后端运行时或任意本地文件临时替换输入。
-4. `api-integration` 只核对 JSON 派生记录、交接路径和 SHA-256，并把原始 JSON 交给既有前端代码生成流程；本 Harness 不读取或修改目标前端的生成器配置，不在此仓库执行生成，也不建立生成 CI 门禁。若 JSON SHA 与派生记录不一致，停止交接并回到治理流程。
+4. `api-integration` 只核对 JSON 派生记录、交接路径和 SHA-256，并把原始 JSON 交给既有前端代码生成流程；本 Harness 可只读核对目标前端的生成器配置与真实导出，但不修改该配置，不在此仓库执行生成，也不建立生成 CI 门禁。若 JSON SHA 与派生记录不一致，停止交接并回到治理流程。
 5. 目标前端项目在需要时手动运行其既有生成命令、类型检查和受影响组件 / API 测试；将实际命令、结果、生成输入 SHA 和偏离写入 `YSS Skill Execution Result`。
 
 ## 真实 mutator 响应契约
@@ -174,7 +174,7 @@ await pageQualityRule(query, { signal: controller.signal, timeout: 120000 });
 
 ## 失败兜底策略
 
-- 生成导出与 skill 示例不同时，以生成文件为准并更新生成脚本，禁止绕过类型检查猜名调用。
+- 生成导出与 skill 示例不同时，以生成文件为准；仅在已授权的生成链维护范围内更新生成脚本，禁止绕过类型检查猜名调用。
 - 接口字段不稳定时，在 Hook API 边界做最小映射，不把兼容逻辑散落到模板。
 - HTTP 200 Blob 业务错误时，先修复后端状态码或 mutator 统一解析，禁止在业务 Hook 重复实现。
 

package/template/.pi/skills/yss-application/SKILL.md

@@ -29,7 +29,11 @@ Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事
 
 1. 按 `architecture_identity.architecture_profile` 选择且只选择对应 Profile reference；Profile 未登记、与 Manifest 不一致或成熟度不满足当前任务时返回 `blocked`。
 2. `target-domain-model` 才执行 Domain Service / Gateway、跨聚合编排和下述 DDD 产物规则；`layered-mvc-service` 与 `mvc-data-analysis-v1` 分别按其 service/core Profile 承载用例、规则和事务，不加载 DDD Gateway。
+<a id="application.use-case"></a>
+<!-- yss-rule {"id":"application.use-case","when":"application","level":"mandatory","evidence":"code-and-verification"} -->
 3. 确认 Use Case、Application/service/core 边界与事务边界已在批准合同中写明。
+<a id="application.mapping"></a>
+<!-- yss-rule {"id":"application.mapping","when":"application","level":"mandatory","evidence":"code-and-verification"} -->
 4. Web DTO 到内部 Command/Result 的转换归 Web 边界，持久化转换归 Repository/Infrastructure；用例层确有独立模型转换时才加载 `mapstruct`，并统一 Spring Bean 与构造器注入。
 5. DDD 的详细包结构、注解、示例和旧架构阻断边界见 `references/application-layer-guide.md`；MVC 不读取该 guide。
 
@@ -53,10 +57,18 @@ Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事
 ## 阶段 7 合同
 
 - 只消费批准后的 `Slice Implementation Contract` 和当前 `work_unit`。
+<a id="application.behavior-tests"></a>
+<!-- yss-rule {"id":"application.behavior-tests","when":"application","level":"mandatory","evidence":"code-and-verification"} -->
 - AppService 骨架可 `controlled-generation`；用例编排、事务、幂等、权限和失败行为必须 `behavior-tdd`。
 - 按 `yss-implementation-contract-compiler/references/yss-skill-execution-result.md` 返回统一 `YSS Skill Execution Result`。
+<a id="application.impacts"></a>
+<!-- yss-rule {"id":"application.impacts","when":"application","level":"mandatory","evidence":"code-and-verification"} -->
 - 发现新 API、权限、状态机或跨上下文影响时填入 `new_impacts` 并暂停。
 
 ## 按需读取
 
 - 分层开发规范：`references/application-layer-guide.md`
+
+## 既有工程与条件适用
+
+只读审计不要求先补批准 Slice；业务 Spec 缺失须记录。整改消费批准 Slice、已确认行为 seam 与登记的 Application/service/core 映射，不要求生成 Manifest。事务、幂等、提交后副作用按实际用例评估；未命中不创建空事务、空端口或空恢复实现。DDD 的领域规则归 Domain，MVC 规则允许留在已登记 service/core。

package/template/.pi/skills/yss-audit-log/SKILL.md

@@ -19,7 +19,7 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 2. 涉及真实类名、配置项、订阅器或排障时，先读 `references/source-index.md`，再定位源码或文档。
 3. 优先检查项目里是否已有注解、配置项和订阅器实现，再决定改法。
 4. 只给出与当前问题直接相关的接入点：注解、配置、切面链路、`CurrentUserProvider` 和订阅器扩展。
-5. 需要看实现细节时，再读取 `assets/` 下源码，不要先讲整套组件原理。
+5. 实现细节以所选平台线的当前源码为准。`assets/` 是 Boot 2 / Java 8 历史快照，仅在旧工程比对或迁移诊断时读取；不能作为 Boot 3 的实现模板或 freshness 证据。
 
 ## 源码索引
 
@@ -62,6 +62,8 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 
 ## 按需读取
 
+以下 `assets/*.java` 均为 `boot2-java8` 历史资料，含 javax 与旧中文 SpEL key。Boot 3 使用其平台索引定位当前 jakarta / args / result 源码；不要修改历史资料来冒充新平台源码。
+
 - 源码索引：`references/source-index.md`
 - 审计切面与 SpEL 解析：`assets/AuditLogAspect.java`
 - 异步发布链路：`assets/YssAuditPublishService.java`

package/template/.pi/skills/yss-audit-log/assets/AuditLogAspect.java

@@ -1,3 +1,4 @@
+// Historical boot2-java8 reference only; not a boot3-java17 implementation template.
 package com.yss.cloud.audit.configuration;
 
 import cn.hutool.jwt.JWT;

package/template/.pi/skills/yss-audit-log/assets/YssAuditLogPrintSubscriberImpl.java

@@ -1,3 +1,4 @@
+// Historical boot2-java8 reference only; not a boot3-java17 implementation template.
 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with

package/template/.pi/skills/yss-audit-log/assets/YssAuditLogSysManagerSubscriberImpl.java

@@ -1,3 +1,4 @@
+// Historical boot2-java8 reference only; not a boot3-java17 implementation template.
 package com.yss.cloud.audit.subscriber.impl;
 
 import com.yss.cloud.audit.subscriber.YssAuditSubscriber;

package/template/.pi/skills/yss-audit-log/assets/YssAuditPublishService.java

@@ -1,3 +1,4 @@
+// Historical boot2-java8 reference only; not a boot3-java17 implementation template.
 package com.yss.cloud.audit.subscriber;
 
 import com.yss.cloud.audit.configuration.AuditConfigurationProperties;

package/template/.pi/skills/yss-backend-spec-review/SKILL.md

@@ -36,3 +36,9 @@ description: 审计既有 Java 后端工程对 YSS 技能规范和已批准业
 ## 输出与完成依据
 
 复用 `docs/templates/review-report-template.md`、当前 Slice 的 YSS Skill Execution Result 和 [审计与整改流程中的记录要求](references/remediation-workflow.md#证据与交接)。报告列明审查覆盖、Standards / Spec 分轴结论、修复前后 finding、候选/规则摘要、实际验证、独立 Reviewer 身份和剩余阻塞。只对本次覆盖且有证据的范围声明符合规范，不自动证明平台已认证或允许发布。
+
+## 必须评估、适用必审
+
+每次显式评估 Web、DTO、Domain、Application、Repository、MyBatis 六类职责；MVC 不套用 DDD，MyBatis 仅在实际使用时适用。使用 `scripts/backend-standards-coverage` 编译实际范围，合同漏列不能抵消真实影响。Java 规范通用，Validation/Exception/映射/注解处理及组件技能按事实追加。
+
+逐条消费 canonical 中 `yss-rule` 声明并返回稳定 `constraint_id`；未结构化条款仍由独立 Reviewer 全文核对。不能只写“本技能通过”。日常后端开发和存量整改共用该检查，详见 [覆盖协议](references/standards-coverage.md)。

package/template/.pi/skills/yss-backend-spec-review/references/check-inputs.md

@@ -7,14 +7,14 @@
 | 每个后端范围 | `alibaba-java-code-style`、工程基线、实际模块/包/类型 | Java 规范、敏感日志、实际依赖方向；测试对象必须存在 |
 | DDD 核心领域 | `yss-domain`、批准战术设计 | 创建/重建、不变量、领域错误、值对象及行为测试；领域规则不依赖框架 |
 | DDD Application 或 MVC service/core | `yss-application`、所选架构 Profile | 用例边界、事务、提交后副作用、幂等和失败恢复；不要求无事务需要的用例套空事务 |
-| 持久化 | `yss-repository`、`yss-mybatis` 及选定 Repository Profile | 聚合加载与展示查询、PO/Mapper/XML/SQL、主键/审计、分页/批量、绑定/参数化和映射完整性；基类按能力选择 |
+| 持久化 | `yss-repository` 及选定 Repository Profile；MyBatis 命中时加载 `yss-mybatis` | 聚合加载与展示查询、PO/Mapper/XML/SQL、主键/审计、分页/批量、绑定/参数化和映射完整性；基类按能力选择 |
 | HTTP 入口 | `yss-web-controller`、冻结 API | CRUD 与认证/回调/Cookie 等手工入口；Controller 不能绕过应用用例；异常翻译允许引用领域错误 |
 | wire / 参数 / 错误 | `yss-dto`、`yss-validation`、`yss-exception` | 真实响应/分页/错误协议、Bean Validation、命名空间、敏感字段与冻结 OpenAPI 一致 |
 | 映射 / 注解处理 | `mapstruct`、`lombok` | 显式字段策略、处理器版本、领域工厂重建；不强迫聚合开放 setter |
 | 实际组件调用 | Registry 中对应组件 Skill 与精确平台源码索引 | cache、userinfo、audit、ID、Excel、resilience 等按能力加载；不因“审查全面”要求安装不用的组件 |
 | 工程和平台 | `docs/engineering/backend-platforms.json`、当前工程基线、effective POM、依赖树 | 精确 JDK/Boot、父/BOM、starter、javax/jakarta 和源码索引；源码可编译不等于兼容认证 |
 
-每个后端范围显式评估 `yss-repository` / `yss-mybatis`。无持久化或 MyBatis 影响时分别说明原因；不可跳过适用项，也不可为了填表增加实现。MVC 不强制构造 DDD 聚合/Gateway；没有展示分页需求就不要求分页类。
+每个后端范围显式评估 `yss-web-controller` / `yss-dto` / `yss-domain` / `yss-application` / `yss-repository` / `yss-mybatis`。无持久化或 MyBatis 影响时分别说明原因；不可跳过适用项，也不可为了填表增加实现。MVC 不强制构造 DDD 聚合/Gateway；没有展示分页需求就不要求分页类。
 
 架构检查按已登记模块、包和实际注解/类型职责识别，不能只搜索 `rest`、`*Controller` 或某固定后缀。已有 ArchUnit 检查若命中零类，记录覆盖缺口；只运行空测试不能证明存量工程合规。
 

package/template/.pi/skills/yss-backend-spec-review/references/standards-coverage.md

@@ -0,0 +1,39 @@
+# 后端规范覆盖协议
+
+日常开发与既有整改使用同一 `scripts/backend-standards-coverage` 和 `backend-review.mjs`。本协议只派生检查输入，规范正文由工程锁定的 canonical Skill 唯一拥有，路由仍由技能注册表管理。不得浮动使用最新 Skill 替换工程锁定版本。
+
+## 输入与只读命令
+
+治理 root 必须提供工程实际锁定的 canonical 技能；平台、身份与职责来自登记的工程基线。`review_input.scope_kind` 明确区分 `baseline` / `change`，不与候选 `review_mode=worktree|committed` 混用。
+
+```sh
+scripts/backend-standards-coverage --root /governance --input /evidence/review-state.json
+scripts/backend-standards-coverage --root /governance --input /evidence/review-state.json --verify
+```
+
+第一条只输出派生 JSON，不写工程、不执行其构建命令、不批准合同；保存输出并绑定 `standards_coverage_ref` 与 SHA-256 `standards_coverage_digest`。第二条读取 `review_result_ref`，重算覆盖并核对已有独立审查。所有证据引用相对治理 root；`code_ref` 相对被审工程。证据放在工程源码范围外，避免报告把自身纳入摘要。
+
+- `baseline`：输入 `project_root`、`baseline_binding: {ref,digest}`，基线复用 `architecture_identity/source.roots/build_units.role_paths`；可以无 Slice、无 diff。未登记时可输出诊断，但未知身份、未解析类型和空业务范围不能声称合规。
+- `change`：保留批准 Slice、执行预检、工作单元与既有候选字段。`worktree` 从不可变候选读取 merge_base；`committed` 另给 40 位 `review_base_ref`。合同漏掉实际影响返回 drift/new_impacts，不能仅补审查输入掩盖合同缺口。
+- 基线盘点包括授权工程源根中的源码、测试、XML、配置和构建文件。变更模式轻量盘点完整源码，语义审查针对变更类型与依赖闭包；配置变化扩展影响。未触及的既有证据须明确复用依赖和摘要，不能只搬历史“通过”。
+- 源码扫描识别已知注解、局部组合注解和接口继承，并结合角色映射与依赖配置。它不是完整 Java 编译器：不确定的外部注解/父类型必须补 `responsibility_evidence: [{ref,digest}]`，记录 `source_ref/source_digest/roles/reason/evidence_ref/evidence_digest`。roles 使用工程角色或 `data`；证据来自真实类型、编译态 ArchUnit/运行时映射或独立核实，不能借此取消扫描已发现的职责。
+
+`skill_assessments` 必须显式评估六类职责；`issues` 与明确结构 `findings` 均保留，不能移除后伪造派生清单。输出绑定源码 HEAD、文件摘要/mode、规则文件摘要及 Skill lock 摘要；重算不一致则旧覆盖失效。`limitations` 必须随报告保留。源码和合成夹具通过不证明 HTTP wire、数据库方言或 Java 平台认证。
+
+## 规则所有权与结果
+
+强制条款使用同文件内 `<a id="稳定ID"></a>` 和 `<!-- yss-rule {"id":"稳定ID","when":"适用事实","level":"mandatory","evidence":"code-and-verification"} -->` 标记原文，不复制规则正文。允许条件由工具校验；新增条件先增加检测/保守处置和反例。历史 ID 不复用为另一种语义。
+
+继续使用 `constraint_results`，每项增加 `constraint_id` 和与派生结果一致的 `applicability_basis`，并保留 `axis/skill/constraint/status/rule_ref/rule_digest/code_ref/evidence_ref/evidence_digest`。机器重新读取所有标记，拒绝漏项、重复项、未知 ID、规则归属错误、漂移和虚假不适用。
+
+每个适用技能额外有 `<skill>.full-text` 项：Reviewer 阅读该技能和适用 references，使用 `review_notes` 记录具体判断及证据；尚未结构化的条款在原报告列出 findings。不允许把文本长度检查当作语义合规证明。结构化规则目前只是可检查的覆盖基线，全文审查仍强制。
+
+规则级不适用不同于技能级不适用。比如 Repository 适用而分页未命中时，相关条件规则允许 `not-applicable`，必须有理由、实际代码范围及可读证据；扫描已命中的强制规则不得豁免。无分页、事务、批量或特定组件需求时不建空实现。
+
+## 基线报告与完成边界
+
+独立 Reviewer 始终使用 `code-review`；baseline 结果也核对 reviewer/implementer 的不同 actor 与执行 instance，以及当前覆盖摘要。`candidate_digest` 为完整派生 inventory 的 SHA-256。机器验证含 command、exit_code、executed_at、candidate_digest 和日志摘要。
+
+`axes.Standards=passed` 必须覆盖所有适用规则。缺业务 Spec 则 `axes.Spec=missing_evidence`；要声明 Spec passed，另提供 `spec_binding.ref/digest/approval_ref`，批准必须绑定当前 Spec，并逐验收项给证据。基线成功仅返回 `status=audited, execution_allowed=false`，绝不关闭实现到交付的流转。
+
+历史报告可以阅读，新完成门禁要求覆盖字段；不批量伪造或升级历史审查。变更报告仍只消费已批准且当前的 Slice，并使用原候选协议。只读盘点发现违规后形成 finding 与整改计划，取得必要批准后才修改；旧 finding 不能因为重编译覆盖而被抹去。

package/template/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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.