create-yss-spec 3.4.1 → 3.4.4

package/template/.agents/skills/mapstruct/references/annotation-examples.md

@@ -0,0 +1,300 @@
+# mapstruct 条件参考
+
+仅在需要具体注解或配置示例时定位对应章节。示例业务名与版本不是工程基线；按批准合同替换，禁止直接复制成业务实现。
+
+## Basic Mapper
+
+```java
+@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.ERROR)
+public interface UserMapper {
+
+    UserResponse toResponse(User user);
+
+    List<UserResponse> toResponseList(List<User> users);
+
+    @Mapping(target = "id", ignore = true)
+    @Mapping(target = "createdAt", ignore = true)
+    @Mapping(target = "updatedAt", ignore = true)
+    @Mapping(target = "password", ignore = true)
+    User toEntity(CreateUserRequest dto);
+}
+```
+
+## Update Mapping
+
+```java
+@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.ERROR)
+public interface UserMapper {
+
+    // Partial update - ignores null values
+    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
+    void updateEntity(UpdateUserRequest dto, @MappingTarget User user);
+
+    // Full update - sets all fields including nulls
+    void updateEntityFull(UpdateUserRequest dto, @MappingTarget User user);
+}
+```
+
+## Field Mapping
+
+```java
+@Mapper(componentModel = "spring")
+public interface OrderMapper {
+
+    // Different field names
+    @Mapping(source = "customer.name", target = "customerName")
+    @Mapping(source = "customer.email", target = "customerEmail")
+    @Mapping(source = "items", target = "orderItems")
+    OrderResponse toResponse(Order order);
+
+    // Constant values
+    @Mapping(target = "status", constant = "PENDING")
+    @Mapping(target = "createdAt", expression = "java(java.time.LocalDateTime.now())")
+    Order toEntity(CreateOrderRequest dto);
+
+    // Expression
+    @Mapping(target = "fullName", expression = "java(user.getFirstName() + \" \" + user.getLastName())")
+    UserResponse toResponse(User user);
+
+    // Date formatting
+    @Mapping(source = "createdAt", target = "createdDate", dateFormat = "yyyy-MM-dd")
+    OrderResponse toResponse(Order order);
+}
+```
+
+## Nested Objects
+
+```java
+@Mapper(componentModel = "spring", uses = {AddressMapper.class, ItemMapper.class})
+public interface OrderMapper {
+
+    // Uses AddressMapper for address field
+    // Uses ItemMapper for items collection
+    OrderResponse toResponse(Order order);
+}
+
+@Mapper(componentModel = "spring")
+public interface AddressMapper {
+    AddressResponse toResponse(Address address);
+}
+
+@Mapper(componentModel = "spring")
+public interface ItemMapper {
+    ItemResponse toResponse(Item item);
+}
+```
+
+## Enum Mapping
+
+```java
+@Mapper(componentModel = "spring")
+public interface StatusMapper {
+
+    @ValueMappings({
+        @ValueMapping(source = "ACTIVE", target = "ENABLED"),
+        @ValueMapping(source = "INACTIVE", target = "DISABLED"),
+        @ValueMapping(source = MappingConstants.ANY_REMAINING, target = "UNKNOWN")
+    })
+    ExternalStatus toExternalStatus(InternalStatus status);
+}
+```
+
+## Custom Methods
+
+```java
+@Mapper(componentModel = "spring")
+public abstract class UserMapper {
+
+    @Autowired
+    protected RoleRepository roleRepository;
+
+    public abstract UserResponse toResponse(User user);
+
+    @Mapping(target = "roles", source = "roleIds")
+    public abstract User toEntity(CreateUserRequest dto);
+
+    // Custom mapping method
+    protected Set<Role> mapRoles(Set<Long> roleIds) {
+        if (roleIds == null) return new HashSet<>();
+        return roleIds.stream()
+            .map(id -> roleRepository.findById(id)
+                .orElseThrow(() -> new ResourceNotFoundException("Role", "id", id)))
+            .collect(Collectors.toSet());
+    }
+}
+```
+
+## Collection Mapping
+
+```java
+@Mapper(componentModel = "spring")
+public interface ProductMapper {
+
+    ProductResponse toResponse(Product product);
+
+    List<ProductResponse> toResponseList(List<Product> products);
+
+    Set<ProductResponse> toResponseSet(Set<Product> products);
+
+    // Page mapping
+    default Page<ProductResponse> toResponsePage(Page<Product> products) {
+        return products.map(this::toResponse);
+    }
+}
+```
+
+## After/Before Mapping
+
+```java
+@Mapper(componentModel = "spring")
+public abstract class UserMapper {
+
+    @AfterMapping
+    protected void afterMapping(@MappingTarget UserResponse response, User user) {
+        response.setDisplayName(user.getFirstName() + " " + user.getLastName().charAt(0) + ".");
+    }
+
+    @BeforeMapping
+    protected void beforeMapping(CreateUserRequest dto) {
+        if (dto.getEmail() != null) {
+            dto.setEmail(dto.getEmail().toLowerCase().trim());
+        }
+    }
+}
+```
+
+## Conditional Mapping
+
+```java
+@Mapper(componentModel = "spring")
+public abstract class UserMapper {
+
+    @Condition
+    public boolean isNotEmpty(String value) {
+        return value != null && !value.trim().isEmpty();
+    }
+
+    // Only maps non-empty strings
+    UserResponse toResponse(User user);
+}
+```
+
+## Maven Configuration
+
+```xml
+<properties>
+    <mapstruct.version>1.6.2</mapstruct.version>
+    <lombok.version>1.18.30</lombok.version>
+</properties>
+
+<dependencies>
+    <dependency>
+        <groupId>org.mapstruct</groupId>
+        <artifactId>mapstruct</artifactId>
+        <version>${mapstruct.version}</version>
+    </dependency>
+
+    <dependency>
+        <groupId>org.projectlombok</groupId>
+        <artifactId>lombok</artifactId>
+        <version>${lombok.version}</version>
+        <optional>true</optional>
+    </dependency>
+</dependencies>
+
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <version>3.13.0</version>
+            <configuration>
+                <source>${maven.compiler.source}</source>
+                <target>${maven.compiler.target}</target>
+                <annotationProcessorPaths>
+                    <!-- Use the approved processor configuration, including Lombok binding -->
+                    <path>
+                        <groupId>org.projectlombok</groupId>
+                        <artifactId>lombok</artifactId>
+                        <version>${lombok.version}</version>
+                    </path>
+                    <path>
+                        <groupId>org.mapstruct</groupId>
+                        <artifactId>mapstruct-processor</artifactId>
+                        <version>${mapstruct.version}</version>
+                    </path>
+                    <path>
+                        <groupId>org.projectlombok</groupId>
+                        <artifactId>lombok-mapstruct-binding</artifactId>
+                        <version>0.2.0</version>
+                    </path>
+                </annotationProcessorPaths>
+                <compilerArgs>
+                    <arg>-Amapstruct.defaultComponentModel=spring</arg>
+                </compilerArgs>
+            </configuration>
+        </plugin>
+    </plugins>
+</build>
+```
+
+## Key Annotations
+
+| Annotation | Purpose |
+|------------|---------|
+| `@Mapper` | Define mapper interface/abstract class |
+| `@Mapping` | Field-level mapping configuration |
+| `@MappingTarget` | Update existing object |
+| `@BeanMapping` | Bean-level mapping settings |
+| `@AfterMapping` | Post-processing method |
+| `@BeforeMapping` | Pre-processing method |
+| `@Condition` | Conditional mapping |
+| `@ValueMapping` | Enum value mapping |
+
+## Best Practices
+
+1. Use `componentModel = "spring"` for Spring injection
+2. Keep unmapped targets visible with `ReportingPolicy.ERROR`; explicitly ignore only fields excluded by the contract
+3. Map or explicitly exclude identity and audit fields according to ownership in the contract
+4. Use `@MappingTarget` for partial updates
+5. Configure Lombok, MapStruct and the required binding processor from the engineering baseline
+6. Use abstract classes instead of interfaces for custom logic
+7. Use `@Condition` for conditional mapping logic
+
+---
+
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Correct Approach |
+|--------------|--------------|------------------|
+| Mapping entities to entities | Breaks change tracking | Map DTO to entity |
+| Not using @MappingTarget | Inefficient updates | Use for partial updates |
+| Complex logic in expressions | Hard to test | Use custom methods |
+| Ignoring all unmapped | Misses fields silently | Use ERROR and explicit field mappings |
+| Not excluding audit fields | Overwrites metadata | Exclude id, timestamps |
+| Circular references | StackOverflowError | Break cycles with custom mapping |
+| Using interfaces for custom logic | Can't inject dependencies | Use abstract classes |
+| Not testing mappers | Runtime mapping errors | Write mapper tests |
+
+---
+
+## Quick Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| "Cannot find implementation" | Annotation processing failed | Check processor configuration |
+| Lombok fields not found | Missing processor or binding | Check annotationProcessorPaths and Lombok binding |
+| Mapper not autowired | Wrong componentModel | Use componentModel = "spring" |
+| Circular dependency | Mappers reference each other | Review mapper dependencies and remove cycles |
+| UnmappedTargetProperty warning | Missing mapping | Add an explicit mapping or a contract-approved field ignore |
+| NullPointerException in mapping | Null source | Add null checks or NullValuePropertyMappingStrategy |
+| Custom method not called | Wrong signature | Match method parameters exactly |
+| Generated code not updated | IDE cache | Clean and rebuild project |
+
+---
+
+## Reference Documentation
+- [MapStruct Reference](https://mapstruct.org/documentation/stable/reference/html/)
+- [Spring Integration](https://mapstruct.org/documentation/stable/reference/html/#spring)
+- [Lombok Integration](https://mapstruct.org/faq/#can-i-use-mapstruct-together-with-project-lombok)

package/template/.agents/skills/page-form-module/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: page-form-module
-description: 指导实现 YSS UI 新增、编辑和查看表单模块，覆盖 YFormily Schema、mode 0/1/2、详情渲染、数据回显与回填、表单值被意外清空排查、校验、提交 loading、弹窗销毁和列表刷新；当页面包含表单页、Modal 或 Drawer 表单，或编辑时回显丢失、提交后表单未重置时使用。
+description: "实现 YSS UI 新增、编辑、查看表单模块及弹窗闭环；排查回显丢失、重置、提交与列表刷新。"
 ---
 
 # Page Form Module Skill

package/template/.agents/skills/page-skeleton/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: page-skeleton
-description: 指导搭建 Vue3 YSS UI 列表、表单、详情和弹窗页面模块骨架，统一 index.vue、constant.ts、style.less、hooks 与私有组件职责；当新建页面或需要拆分超过 150 行的业务组件时使用。
+description: "创建或拆分 Vue3 YSS UI 页面模块骨架，明确页面、配置、hooks 与私有组件职责。"
 ---
 
 # Page Skeleton Skill

package/template/.agents/skills/theme-token-usage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: theme-token-usage
-description: 指导 Vue3 YSS UI 微应用业务页面、公共组件、原型还原和主题修复使用可动态换肤的 CSS/Ant Design Token，覆盖主色、hover/active/selected/focus、状态色、中性色、透明色派生和暗色模式；当新增或修改 .vue、style.less、内联样式、TS 渲染配置、SVG 色值，或审查硬编码 #hex/rgb/渐变时使用。
+description: "实现或修复 Vue3 YSS UI 主题、交互状态色与动态换肤；用于 token 映射和硬编码色值审查。"
 ---
 
 # YSS UI 主题 Token 使用 Skill

package/template/.agents/skills/to-tickets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: to-tickets
-description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker — edges as text in one file per ticket locally, or native blocking links on a real tracker.
+description: "显式调用时，将已确认的 Plan 或 Spec 拆成带依赖的垂直切片 Ticket，并按配置的 tracker 持久化。"
 disable-model-invocation: true
 ---
 

package/template/.agents/skills/using-git-worktrees/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-git-worktrees
-description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
+description: "Set up Git worktree isolation when requested or when concurrent work needs a separate checkout."
 ---
 
 # Using Git Worktrees

package/template/.agents/skills/wayfinder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wayfinder
-description: Plan a huge chunk of work — more than one agent session can hold — as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
+description: "显式调用时，为跨多个会话的大型工作建立决策地图，逐项收敛后交回主流程。"
 disable-model-invocation: true
 ---
 

package/template/.agents/skills/yedit-table-usage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yedit-table-usage
-description: 指导 YSS UI 业务页面使用 @yss-ui/components 的 YEditTable 实现可编辑表格、行内编辑、添加/删除行、下拉多选与可创建 tags、行级候选联动、表头筛选、校验和查看态；当需求出现编辑表格、明细行、扩展属性、可编辑列或 YEditTableColumn 时使用。
+description: "配置或修复 YSS UI YEditTable 的行内编辑、候选联动、增删行、校验与查看态。"
 ---
 
 # YEditTable 使用

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

@@ -1,6 +1,6 @@
 ---
 name: yss-api-integration
-description: 指导在 Vue3 业务列表、表单、详情和操作 Hook 中集成 Orval API，覆盖真实生成产物选择、mutator 响应契约、错误提示、加载状态、请求选项和长整型精度；当页面对接查询、新增、编辑、删除、详情或文件流接口时使用。
+description: "在 Vue3 YSS UI 中对接 Orval API；核验生成方法、mutator、错误反馈、loading 与长整型精度。"
 ---
 
 # API 集成 Skill

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

@@ -1,6 +1,6 @@
 ---
 name: yss-audit-log
-description: Use when YSS `AuditLog`, `EnableAuditLog`, audit SpEL summaries, async publication, subscriber registration, queue loss, or audit delivery failures are involved.
+description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订阅注册与审计投递。"
 ---
 
 # yss-audit-log

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

@@ -1,6 +1,6 @@
 ---
 name: yss-cache
-description: 用于 YSS 缓存框架的接入、配置、代码修改和故障诊断。Use when tasks involve QueryCache、UpdateCache、ClearCache、TTL、SpEL key、事务提交后缓存操作、Redis/Caffeine/Hazelcast 后端切换、Redis Standalone/Sentinel/Cluster、Jedis 连接池、Redis fallback、JetCache、多级缓存、序列化兼容、缓存不命中或失效不一致。
+description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、缓存后端与一致性问题。"
 ---
 
 # yss-cache

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

@@ -21,9 +21,22 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 - 只补持久层时，优先 `yss-repository`。
 - 只补 Web 层时，优先 `yss-web-controller`。
 
+## Spring Boot / Java 平台选择
+
+调用本技能前由生命周期编排器展示 `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；候选不等于可生成。
+- 独立子项目可继承主项目组合或覆盖，必须逐项目确认（允许一次确认明确列出的项目）；同一 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。
+- 平台候选维护验证产物标记 `platform_verification=candidate`，不能交给业务生成、升级完成等级或进入首切片验证。测试夹具不证明 YSS 兼容。
+
+版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+
 ## 优先流程
 
-1. 确认服务级 `scaffold_request_id`、已由用户确认且生命周期批准的 `domain-driven` 架构选择及 digest、项目名、基础包名、Maven 项目坐标、父 POM GAV、YSS Components BOM 版本、输出目录和批准 Profile。Java `base_package` 与 Maven `group_id` 是两个独立输入，不得相互推导；脚手架发生在 Ticket 正式化前，不使用 `slice_id` 伪造切片身份。
+1. 确认服务级 `scaffold_request_id`、已通过 `gate.backend-architecture-platform-approved` 的 `domain-driven` 架构与精确 Spring Boot 版本选择及 digest、项目名、基础包名、Maven 项目坐标、父 POM GAV、YSS Components BOM 版本、输出目录和批准 Profile。Java `base_package` 与 Maven `group_id` 是两个独立输入，不得相互推导；脚手架发生在 Ticket 正式化前，不使用 `slice_id` 伪造切片身份。
    Harness 内输出目录必须是 `apps/backend/` 容器，生成器再以 `project_name` 创建 `apps/backend/<project>/`；禁止使用 `app/backend/`、`app/frontend/` 或把 `apps/backend/` 之外的容器根当作后端项目根。
 2. 优先运行 `node scripts/generate_and_verify_scaffold.mjs`，在同一个受控工作流中生成骨架并执行真实 Maven 验证。`generate_scaffold.mjs` 只是底层生成原语，单独返回 0 不代表脚手架完成。
 3. 检查生成的模块名、POM、机械启动入口、基础配置文件和包路径。
@@ -84,12 +97,12 @@ node scripts/run_first_slice_verification.mjs \
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
 - 生成时的静态依赖由技能注册表与 实现合同编译器 共同约束为 `yss-backend-scaffold-parent`、`alibaba-java-code-style`。生成后必须回到 实现合同编译器，并按批准切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller`、`yss-dto`、`yss-exception`、`yss-validation`、`mapstruct`、`lombok`、`alibaba-java-code-style` 等实际命中的行为 skill。
-- 当前脚手架第一阶段仅支持经过验证的 `mysql`；未提供完整模板和验证的数据库类型不得伪装成已支持。
+- 验证数据库固定 H2，生产数据库 `not-bound`；后续存储接入按批准的切片合同执行。
 - 生成后的后端工程必须使用项目根目录 `./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 对账后的恢复审计，不用于新生成。
-- 合同 `profiles` 只支持 `target-domain-model`、`mybatis-plus`、`mysql`、`spring-boot-2.7-jdk8`、`javax`、`web`、`yss-internal`。普通 MyBatis、Boot 3、独立 client module、client-in-domain 和其他旧架构均为 `unsupported`，不提供回退分支。
+- 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、下游完整 skill tree digest、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 实现合同编译器。
 - `first-slice-verified` 只能由 `run_first_slice_verification.mjs` 写入。手工改 Manifest、只生成 Controller、只通过局部模块测试或仅有结构扫描都不能升级完成等级。

package/template/.agents/skills/yss-ddd-scaffold-generator/assets/templates/pom/application-pom.xml.template

@@ -27,7 +27,7 @@
         </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-aop</artifactId>
+            <artifactId>{{aop_starter}}</artifactId>
         </dependency>
         <dependency>
             <groupId>org.springframework</groupId>

package/template/.agents/skills/yss-ddd-scaffold-generator/assets/templates/pom/parent-pom.xml.template

@@ -20,16 +20,18 @@
 
     <properties>
         <yss-components.version>{{yss_components_version}}</yss-components.version>
-        <maven.compiler.source>1.8</maven.compiler.source>
-        <maven.compiler.target>1.8</maven.compiler.target>
+        <java.version>{{java_version}}</java.version>
+        <spring-boot.version>{{boot_version}}</spring-boot.version>
+        <maven.compiler.source>{{java_version}}</maven.compiler.source>
+        <maven.compiler.target>{{java_version}}</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <mapstruct.version>1.5.5.Final</mapstruct.version>
-        <lombok.version>1.18.30</lombok.version>
-        <lombok-mapstruct-binding.version>0.2.0</lombok-mapstruct-binding.version>
-        <swagger-annotations-v3.version>2.2.22</swagger-annotations-v3.version>
-        <archunit.version>1.2.1</archunit.version>
-        <maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>
-        <maven-enforcer-plugin.version>3.5.0</maven-enforcer-plugin.version>
+        <mapstruct.version>{{mapstruct_version}}</mapstruct.version>
+        <lombok.version>{{lombok_version}}</lombok.version>
+        <lombok-mapstruct-binding.version>{{lombok_mapstruct_binding_version}}</lombok-mapstruct-binding.version>
+        <swagger-annotations-v3.version>{{swagger_version}}</swagger-annotations-v3.version>
+        <archunit.version>{{archunit_version}}</archunit.version>
+        <maven-compiler-plugin.version>{{compiler_version}}</maven-compiler-plugin.version>
+        <maven-enforcer-plugin.version>{{enforcer_version}}</maven-enforcer-plugin.version>
     </properties>
 
     <modules>
@@ -42,6 +44,7 @@
 
     <dependencyManagement>
         <dependencies>
+            <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-dependencies</artifactId><version>{{boot_version}}</version><type>pom</type><scope>import</scope></dependency>
             <dependency>
                 <groupId>com.yss.cloud</groupId>
                 <artifactId>yss-components-bom</artifactId>
@@ -94,6 +97,8 @@
 
     <build>
         <plugins>
+            <plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>{{boot_version}}</version></plugin>
+            <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>{{surefire_version}}</version></plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
@@ -129,7 +134,7 @@
                         <goals><goal>enforce</goal></goals>
                         <configuration>
                             <rules>
-                                <requireJavaVersion><version>[1.8,1.9)</version></requireJavaVersion>
+                                <requireJavaVersion><version>{{java_range}}</version></requireJavaVersion>
                                 <requireMavenVersion><version>[3.6.3,)</version></requireMavenVersion>
                                 <reactorModuleConvergence/>
                                 <dependencyConvergence/>

package/template/.agents/skills/yss-ddd-scaffold-generator/assets/templates/pom/web-pom.xml.template

@@ -19,7 +19,7 @@
         </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-web</artifactId>
+            <artifactId>{{web_starter}}</artifactId>
         </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
@@ -45,13 +45,13 @@
         </dependency>
         <dependency>
             <groupId>io.swagger.core.v3</groupId>
-            <artifactId>swagger-annotations</artifactId>
+            <artifactId>{{swagger_artifact}}</artifactId>
             <version>${swagger-annotations-v3.version}</version>
             <scope>compile</scope>
         </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-test</artifactId>
+            <artifactId>{{web_test_starter}}</artifactId>
             <scope>test</scope>
         </dependency>
     </dependencies>

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

@@ -11,9 +11,9 @@ description: YSS DDD scaffold Engineering Baseline entry for profile, module, de
 
 - Architecture: `target-domain-model`
 - Persistence: `mybatis-plus`
-- Database: `mysql`
-- Platform: `spring-boot-2.7-jdk8`
-- Validation namespace: `javax`
+- Verification database: `h2`; production database: `not-bound`
+- Platform: approved `platform_configuration` v2 from the shared backend platform catalog
+- Validation namespace: derived from that platform (`javax` for Boot 2.7; `jakarta` for Boot 3.5/4.1)
 - DTO placement: `web`
 - Repository: `yss-internal`
 

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/first-slice-compatibility.test.mjs

@@ -80,13 +80,17 @@ async function prepareGoldenProject(t) {
   attachDesignPrerequisites(root, contract);
   await writeFile(contractFile, `${JSON.stringify(contract, null, 2)}\n`);
   const args = ["--project-name", "golden-service", "--base-package", "com.yss.golden", "--output-dir", output, "--contract-id", "golden-scaffold-1", "--contract-version", "1", "--approval-ref", contract.lifecycle_approval_ref, "--compiler-draft-ref", "compiler-golden-1", "--persisted-ref", "persisted-golden-1", "--contract-file", contractFile, "--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"];
-  const generated = await execute(process.execPath, [generator, ...args]);
+  const generated = await execute(process.execPath, [path.resolve(scripts, "../../../../scripts/fixtures/backend-scaffold/generate-candidate.mjs"), generator, ...args]);
   assert.equal(generated.code, 0, generated.stderr);
   const project = path.join(output, "golden-service");
   const manifestPath = path.join(project, ".yss", "scaffold-generation.json");
   const emptyVerificationPath = path.join(root, "empty-scaffold-verification.json");
   await writeFile(emptyVerificationPath, JSON.stringify({ status: "passed", completion_level: "empty-scaffold-verified", commands: ["./mvnw validate", "./mvnw test", "./mvnw package"] }));
   const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  // Legacy Manifest compatibility fixture only; this does not qualify a new platform.
+  delete manifest.platform_configuration;
+  delete manifest.platform_verification;
+  delete manifest.architecture_identity.platform_configuration;
   manifest.completion_level = "empty-scaffold-verified";
   manifest.empty_scaffold_verification_ref = emptyVerificationPath;
   await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/first-slice-verification.test.mjs

@@ -54,7 +54,9 @@ async function fixture({ omitGatewayImpl = false, omitReadiness = false } = {})
   const manifestPath = path.join(project, ".yss", "scaffold-generation.json");
   const contractPath = path.join(root, "slice-contract.json");
   await mkdir(path.dirname(manifestPath), { recursive: true });
+  const architectureIdentity = { architecture_family: "domain-driven", architecture_profile: "target-domain-model", generator_skill: "yss-ddd-scaffold-generator", requested_capabilities: [], resolved_modules: ["domain", "application", "infrastructure", "adapter", "bootstrap"], contract_digest: "a".repeat(64), verification_database: "h2", production_database: "not-bound" };
   await writeFile(manifestPath, JSON.stringify({
+    architecture_identity: architectureIdentity,
     schema_version: 2,
     contract_id: "scaffold-1",
     contract_version: 1,
@@ -79,7 +81,8 @@ async function fixture({ omitGatewayImpl = false, omitReadiness = false } = {})
     maven_coordinates_source: "approved-contract"
   }));
   await writeFile(contractPath, JSON.stringify({
-    schema_version: 1,
+    architecture_identity: architectureIdentity,
+    schema_version: 2,
     contract_id: "slice-1",
     contract_version: 1,
     slice_id: "quality-rule-first-slice",
@@ -87,7 +90,7 @@ async function fixture({ omitGatewayImpl = false, omitReadiness = false } = {})
     readiness: { blockers: [], stale_inputs: [] },
     common: { required_skills: requiredSkills },
     backend: { status: "required", affected_layers: ["domain", "application", "infrastructure", "web"], required_skills: requiredSkills },
-    work_units: [{ id: "slice-backend", contract_id: "slice-1", contract_version: 1, work_unit: { primary_skill: "yss-domain" } }]
+    work_units: [{ architecture_identity: architectureIdentity, id: "slice-backend", contract_id: "slice-1", contract_version: 1, work_unit: { primary_skill: "yss-domain" } }]
   }));
   await write(project, "mvnw", "#!/bin/sh\nexit 0\n");
   await chmod(path.join(project, "mvnw"), 0o755);