create-yss-spec 3.4.7 → 3.4.8

package/template/.pi/skills/yss-implementation-contract-compiler/references/boundaries.md

@@ -18,6 +18,7 @@
 
 | Capability | Primary skill | Task modes |
 | --- | --- | --- |
+| `governance.backend-spec-conformance` | `yss-backend-spec-review` | `guidance`, `troubleshooting`, `review-input` |
 | `writing.lifecycle-document` | `i-have-adhd` | `guidance` |
 | `architecture.technical-design` | `yss-technical-design` | `guidance`, `integration`, `review-input` |
 | `architecture.mvc-design` | `yss-technical-design` | `guidance`, `integration`, `review-input` |
@@ -57,6 +58,7 @@
 
 | Recipe | Capabilities |
 | --- | --- |
+| `backend.spec-conformance` | `governance.backend-spec-conformance`, `quality.java-code-style` |
 | `backend.ddd-domain-behavior` | `layer.domain`, `layer.application`, `quality.java-code-style` |
 | `backend.ddd-persistence-mybatis` | `layer.persistence`, `framework.mybatis`, `codegen.mapstruct`, `codegen.lombok`, `quality.java-code-style` |
 | `backend.ddd-http-api` | `layer.web-adapter`, `contract.dto-wire`, `contract.request-validation`, `contract.error-mapping`, `codegen.mapstruct`, `codegen.lombok`, `quality.java-code-style` |
@@ -106,6 +108,9 @@
 
 | Skill | Dependency | Type | Condition |
 | --- | --- | --- | --- |
+| `yss-backend-spec-review` | `alibaba-java-code-style` | `context-required` | — |
+| `yss-backend-spec-review` | `yss-implementation-contract-compiler` | `coordination-only` | — |
+| `yss-backend-spec-review` | `code-review` | `review-only` | — |
 | `prototype-review` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-implementation-contract-compiler` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-openapi-governance` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/assets/templates/architecture-rules-test.java.template

@@ -0,0 +1,66 @@
+package {{base_package}}.architecture;
+
+import com.tngtech.archunit.core.domain.JavaClass;
+import com.tngtech.archunit.core.domain.JavaClasses;
+import com.tngtech.archunit.core.domain.Dependency;
+import com.tngtech.archunit.core.importer.ImportOption;
+import com.tngtech.archunit.junit.AnalyzeClasses;
+import com.tngtech.archunit.junit.ArchTest;
+
+/** 空骨架可无业务类型；首切片由批准合同传入职责包和必须加载的实际类型。 */
+@AnalyzeClasses(packages = "{{base_package}}", importOptions = ImportOption.DoNotIncludeTests.class)
+class LayeredMvcArchitectureTest {
+    private static boolean inPackage(JavaClass type, String prefixes) {
+        for (String prefix : prefixes.split(",")) {
+            if (!prefix.isEmpty() && (type.getPackageName().equals(prefix)
+                    || type.getPackageName().startsWith(prefix + "."))) return true;
+        }
+        return false;
+    }
+
+    private static boolean role(JavaClass type, String name, String defaults) {
+        return inPackage(type, defaults) || inPackage(type, System.getProperty("yss.arch." + name, ""));
+    }
+
+    private static boolean controller(JavaClass type) {
+        return type.isAnnotatedWith("org.springframework.web.bind.annotation.RestController")
+                || type.isAnnotatedWith("org.springframework.stereotype.Controller")
+                || type.isMetaAnnotatedWith("org.springframework.stereotype.Controller");
+    }
+
+    private static void reject(boolean forbidden, Dependency dependency) {
+        if (forbidden) throw new AssertionError(dependency.getDescription());
+    }
+
+    @ArchTest
+    static void boundaries(JavaClasses classes) {
+        for (JavaClass origin : classes) {
+            boolean application = role(origin, "application", "{{base_package}}.service,{{base_package}}.core");
+            boolean infrastructure = role(origin, "infrastructure", "{{base_package}}.repository");
+            for (Dependency dependency : origin.getDirectDependenciesFromSelf()) {
+                JavaClass target = dependency.getTargetClass();
+                boolean targetWeb = controller(target) || role(target, "web",
+                        "{{base_package}}.server,{{base_package}}.rest,{{base_package}}.adapter.web");
+                boolean targetInfrastructure = role(target, "infrastructure", "{{base_package}}.repository");
+                reject(application && targetWeb, dependency);
+                reject(infrastructure && (targetWeb || role(target, "application",
+                        "{{base_package}}.service,{{base_package}}.core")), dependency);
+                reject(controller(origin) && targetInfrastructure, dependency);
+            }
+        }
+        if (Boolean.getBoolean("yss.firstSlice")) {
+            if (Boolean.getBoolean("yss.arch.requireController")) {
+                boolean foundController = false;
+                for (JavaClass type : classes) if (controller(type)) foundController = true;
+                if (!foundController) throw new AssertionError("Web slice did not load an actual Controller");
+            }
+            String required = System.getProperty("yss.arch.requiredTypes", "");
+            if (required.isEmpty()) throw new AssertionError("first slice requires contract-bound types");
+            for (String name : required.split(",")) {
+                boolean found = false;
+                for (JavaClass type : classes) if (type.getName().equals(name)) found = true;
+                if (!found) throw new AssertionError("architecture scope did not load " + name);
+            }
+        }
+    }
+}

package/template/.pi/skills/yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs

@@ -120,7 +120,7 @@ function parentPom(contract, modules, platform) {
   <properties><java.version>${v.java_version}</java.version><spring-boot.version>${v.boot_version}</spring-boot.version><maven.compiler.source>${v.java_version}</maven.compiler.source><maven.compiler.target>${v.java_version}</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><yss-components.version>${xml(c.yss_components_version)}</yss-components.version></properties>
   <modules>${modules.map((module) => `<module>${contract.project_name}-${module}</module>`).join("")}</modules>
   <dependencyManagement><dependencies>${dependency("org.springframework.boot", "spring-boot-dependencies", v.boot_version, "import").replace("</dependency>", "<type>pom</type></dependency>")}${dependency("com.yss.cloud", "yss-components-bom", "${yss-components.version}", "import").replace("</dependency>", "<type>pom</type></dependency>")}</dependencies></dependencyManagement>
-  <build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-enforcer-plugin</artifactId><version>${v.enforcer_version}</version><executions><execution><id>enforce-platform</id><goals><goal>enforce</goal></goals><configuration><rules><requireJavaVersion><version>${v.java_range}</version></requireJavaVersion><requireMavenVersion><version>[3.6.3,)</version></requireMavenVersion><dependencyConvergence/></rules></configuration></execution></executions></plugin></plugins><pluginManagement><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>${v.boot_version}</version><executions><execution><goals><goal>repackage</goal></goals></execution></executions></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>${v.surefire_version}</version></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>${v.compiler_version}</version><configuration><source>${v.java_version}</source><target>${v.java_version}</target><parameters>true</parameters><annotationProcessorPaths><path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>${v.lombok_version}</version></path><path><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>${v.mapstruct_version}</version></path><path><groupId>org.projectlombok</groupId><artifactId>lombok-mapstruct-binding</artifactId><version>0.2.0</version></path></annotationProcessorPaths></configuration></plugin></plugins></pluginManagement></build>
+  <build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-enforcer-plugin</artifactId><version>${v.enforcer_version}</version><executions><execution><id>enforce-platform</id><goals><goal>enforce</goal></goals><configuration><rules><requireJavaVersion><version>${v.java_range}</version></requireJavaVersion><requireMavenVersion><version>[3.6.3,)</version></requireMavenVersion><dependencyConvergence/></rules></configuration></execution></executions></plugin></plugins><pluginManagement><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>${v.boot_version}</version><executions><execution><goals><goal>repackage</goal></goals></execution></executions></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>${v.surefire_version}</version></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>${v.compiler_version}</version><configuration><source>${v.java_version}</source><target>${v.java_version}</target><parameters>true</parameters><annotationProcessorPaths><path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>${v.lombok_version}</version></path><path><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>${v.mapstruct_version}</version></path><path><groupId>org.projectlombok</groupId><artifactId>lombok-mapstruct-binding</artifactId><version>${v.lombok_mapstruct_binding_version}</version></path></annotationProcessorPaths></configuration></plugin></plugins></pluginManagement></build>
 </project>`;
 }
 
@@ -130,6 +130,7 @@ function modulePom(contract, module, modules, platform) {
   const dependencies = [];
   if (module === "server") {
     dependencies.push(own(applicationModule), dependency("org.springframework.boot", platform.web_starter), dependency("org.springframework.boot", "spring-boot-starter-validation"), dependency("org.springframework.boot", "spring-boot-starter-test", null, "test"), dependency("com.tngtech.archunit", "archunit-junit5", platform.versions.archunit, "test"));
+    dependencies.push(dependency("org.projectlombok", "lombok", platform.versions.lombok, "test"));
     if (platform.web_test_starter !== "spring-boot-starter-test") dependencies.push(dependency("org.springframework.boot", platform.web_test_starter, null, "test"));
     if (modules.includes("client")) dependencies.push(own("client"));
     dependencies.push(dependency("com.h2database", "h2", null, "test"), dependency("org.mapstruct", "mapstruct", platform.versions.mapstruct), dependency("com.yss.cloud", "yss-component-dto"));
@@ -263,7 +264,8 @@ export async function generate(options, { skillId = SKILL_ID, architectureProfil
     await put(projectRoot, `${serverRoot}/src/main/resources/application-scaffold-local.yml`, localDatabaseConfiguration(options.projectName));
     await put(projectRoot, `${serverRoot}/src/test/resources/application-scaffold-test.yml`, localDatabaseConfiguration(`${options.projectName}_test`));
     await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/${applicationClass}Test.java`, `package ${options.basePackage};\n\nimport org.junit.jupiter.api.Test;\nimport org.springframework.boot.test.context.SpringBootTest;\nimport org.springframework.test.context.ActiveProfiles;\n\n@SpringBootTest\n@ActiveProfiles("scaffold-test")\nclass ${applicationClass}Test {\n    @Test\n    void contextLoads() {\n    }\n}`);
-    await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`, `package ${options.basePackage}.architecture;\n\nimport static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;\n\nimport com.tngtech.archunit.core.importer.ImportOption;\nimport com.tngtech.archunit.junit.AnalyzeClasses;\nimport com.tngtech.archunit.junit.ArchTest;\nimport com.tngtech.archunit.lang.ArchRule;\n\n@AnalyzeClasses(packages = "${options.basePackage}", importOptions = ImportOption.DoNotIncludeTests.class)\nclass LayeredMvcArchitectureTest {\n    @ArchTest\n    static final ArchRule repositoryDoesNotDependOnUpperLayers = noClasses().that().resideInAPackage("..repository..").should().dependOnClassesThat().resideInAnyPackage("..service..", "..server..");\n}`);
+    const architectureTemplate = await readFile(path.join(SKILL_ROOT, "assets/templates/architecture-rules-test.java.template"), "utf8");
+    await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/architecture/LayeredMvcArchitectureTest.java`, architectureTemplate.replaceAll("{{base_package}}", options.basePackage));
     await put(projectRoot, `${serverRoot}/src/test/java/${packagePath}/PlatformIntegrationTest.java`, platformSmokeTest(options.basePackage, platform, contract.module_profile.requested_capabilities));
     const wrapper = path.join(REPOSITORY_ROOT, ".agents/skills/yss-ddd-scaffold-generator/assets/wrapper");
     await cp(wrapper, projectRoot, { recursive: true });

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

@@ -55,3 +55,7 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 ## 平台与源码门禁
 
 接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../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-mybatis --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
+
+## 持久化选择记录
+
+在已有数据合同 / persistence_strategy 中记录：实际 Mapper 基类、组件源码与平台绑定、分页唯一责任者、主键与审计填充，以及命中批量时的 SQL 入口、分批大小和方言证据。`BaseMapper` 与组件扩展基类按所需能力选择，不因命名不同判违规；依赖存在和循环 insert 均不证明批量能力。未命中的能力不强制生成。

package/template/.pi/skills/yss-repository/references/profiles/target-domain-model.md

@@ -4,9 +4,9 @@
 
 ## 前置与所有权
 
-- 写模型必须已有批准的 Domain Gateway；读模型必须已有批准的 Application Query Port。缺失或需要改变签名时返回 `new_impacts`，由 `yss-domain` / `yss-application` 和实现合同编译器处理。
+- 写模型必须已有批准的 Domain Gateway；展示读模型必须已有批准的 Application Query Port。缺失或需要改变签名时返回 `new_impacts`，由 `yss-domain` / `yss-application` 和实现合同编译器处理。
 - Infrastructure 实现既有端口，拥有 PO、Repository/Mapper、XML、持久化 Convertor、GatewayImpl 和 QueryAdapter；不拥有领域规则、HTTP DTO 或业务事务。
-- Domain Gateway 只交换 Aggregate、Domain Model、领域值和标识；分页、列表和读模型走 Application Query Port，`PageQuery` 不进入 Domain。
+- Domain Gateway 只交换 Aggregate、Domain Model、领域值和标识；展示分页、列表和读模型走 Application Query Port，`PageQuery` 不进入 Domain。
 
 ## 结构决策
 
@@ -21,3 +21,11 @@
 - 经 Domain Gateway 保存后可重新加载语义等价的 Aggregate。
 - Query Port 覆盖分页 total、空结果、排序/过滤白名单和字段转换。
 - Mapper/Repository 使用批准数据库 fixture；H2 不能证明生产方言。
+
+## 持久化决策与映射
+
+- 在既有 persistence_strategy / 数据合同中明确 Mapper 基类及源码依据、主键、逻辑删除、审计填充、并发版本、敏感字段、分页责任和命中时的批量策略。未命中分页或批量时写明理由，不创建空适配器。
+- 多表聚合按同一 Application 事务保存，重载后比较身份、值对象、集合与业务状态；并发写入按批准策略验证冲突或幂等结果。
+- 机械字段使用 Spring MapStruct Bean；聚合重建可通过显式工厂或自定义映射方法。业务状态校验由领域入口拥有，禁止为了映射而开放破坏不变量的 setter。
+- 创建与更新的 null 语义、枚举未知值和审计字段保留必须有测试；转换器不得静默创造业务默认值或吞掉非法持久化状态。
+- 包名与类型后缀来自批准工程基线；Mapper 与 Repository 的命名不能替代职责、运行时发现和行为验证。

package/template/.pi/skills/yss-web-controller/references/web-adapter-layer-guide.md

@@ -84,3 +84,11 @@ public interface QualityRuleWebConvertor {
 - Wire forbidden fields 无法绑定。
 - OpenAPI 3 注解、YSS Result wrapper、Validation namespace 与平台 Profile 一致。
 - 执行项目根 `./mvnw test/package`，并保留 HTTP/serialization/exception 证据。
+
+## 非 CRUD 适配
+
+认证、OAuth 回调、Cookie、流式响应及协议端点可以手工实现，不强行套 CRUD metadata；仍消费批准的 wire 合同、Application seam 和平台配置。Controller 不直连 Domain Gateway，也不自行编排登录、撤销或持久化。
+
+协议转换、Cookie/Header 处理归 Web；业务决策归 Application/Domain。异常翻译器可以依赖领域错误类型，不能据此允许 Controller 调用领域端口。MapStruct 处理机械字段映射，协议编码及显式领域工厂适配使用有测试的自定义方法。
+
+生成器推荐 rest 布局；已登记的 adapter.web 等布局通过合同绑定识别。审查按模块、实际 Controller 类型和依赖方向进行，包名偏离不能让检查空匹配通过。

package/template/docs/agents/yss-skill-registry.yaml

@@ -33,6 +33,7 @@ backend_skill_domains:
     yss-implementation-contract-compiler: platform-governance-migration
     yss-skill-source-index-refresh: platform-governance-migration
     yss-up-springboot3: platform-governance-migration
+    yss-backend-spec-review: platform-governance-migration
   deprecated_skills: []
 backend_source_index_contract:
   schema_version: 1
@@ -126,6 +127,7 @@ retirement_contract:
     deprecated: skill-deprecated
     retired: skill-retired
 capabilities:
+  - { id: governance.backend-spec-conformance, primary_skill: yss-backend-spec-review, provider: { kind: none }, task_modes: [guidance, troubleshooting, review-input] }
   - { id: writing.lifecycle-document, primary_skill: i-have-adhd, provider: { kind: none }, task_modes: [guidance] }
   - { id: architecture.technical-design, primary_skill: yss-technical-design, provider: { kind: none }, task_modes: [guidance, integration, review-input] }
   - { id: architecture.mvc-design, primary_skill: yss-technical-design, provider: { kind: none }, architecture_family: layered-mvc, task_modes: [guidance, integration, review-input] }
@@ -159,6 +161,7 @@ capabilities:
   - { id: project-init.mvc-data-analysis, primary_skill: yss-layered-mvc-scaffold-generator, provider: { kind: none }, task_modes: [component-maintenance] }
   - { id: migration.springboot3, primary_skill: yss-up-springboot3, provider: { kind: none }, task_modes: [guidance, integration, troubleshooting, component-maintenance, review-input] }
 recipes:
+  - { id: backend.spec-conformance, capabilities: [governance.backend-spec-conformance, quality.java-code-style] }
   - { id: backend.ddd-domain-behavior, architecture_family: domain-driven, capabilities: [layer.domain, layer.application, quality.java-code-style] }
   - { id: backend.ddd-persistence-mybatis, architecture_family: domain-driven, capabilities: [layer.persistence, framework.mybatis, codegen.mapstruct, codegen.lombok, quality.java-code-style] }
   - { id: backend.ddd-http-api, architecture_family: domain-driven, capabilities: [layer.web-adapter, contract.dto-wire, contract.request-validation, contract.error-mapping, codegen.mapstruct, codegen.lombok, quality.java-code-style] }
@@ -180,6 +183,10 @@ recipes:
   - { id: frontend.vue3-scaffold, capabilities: [scaffold.frontend-vue3] }
   - { id: backend.springboot3-migration, capabilities: [migration.springboot3, quality.java-code-style] }
 skill_dependencies:
+  yss-backend-spec-review:
+    - { skill: alibaba-java-code-style, type: context-required }
+    - { skill: yss-implementation-contract-compiler, type: coordination-only }
+    - { skill: code-review, type: review-only }
   prototype-review:
     - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
   yss-implementation-contract-compiler:
@@ -689,6 +696,12 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [backend]
+  - id: yss-backend-spec-review
+    layer: specialist
+    maturity: verified
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [backend, quality]
   - id: yss-userinfo
     layer: specialist
     maturity: supported

package/template/docs/engineering/backend-platforms.md

@@ -101,3 +101,17 @@ Boot 4 使用对应 MVC / MVC 测试 starter、Jackson 3 默认栈与新的模
 通用运行时依赖仍由真实依赖树和 Boot BOM 核验。YSS 组件能力的精确构件绑定只读取同一兼容条目内的 `component_capabilities`，不得再从 catalog 顶层列表或平行 `components` 目录推断。
 
 Jar 核验拒绝未登记或版本不符的额外库；仅允许 Boot 对应版本的 jarmode 工具以及已选配方中的 provided Lombok 随包出现。原因是 [Boot repackage 默认包含 provided 依赖](https://docs.spring.io/spring-boot/maven-plugin/packaging.html)；这些打包例外不能补足必须存在于 compile/runtime 树的 Web、Servlet、JSON 等能力。
+
+
+## 双平台专项认证
+
+本轮必选范围为 `spring-boot-2.7-jdk8:2.7.18` 与 `spring-boot-3.5-jdk17:3.5.16`，各覆盖
+`domain-driven`、`layered-mvc`。矩阵输入可指定 `required_combinations`，或重复传
+`--require-combination <profile_id>:<spring_boot_version>:<architecture_family>`。不指定时仍执行完整矩阵。
+未选择的组合记录 `not-executed`，不计为通过，也不影响专项总状态。专项通过不自动修改清单可选性。
+
+每个组合使用合同选择的平台和显式 `java_homes`，本机默认 Java 不决定项目版本。生成的测试夹具覆盖
+HTTP JSON/Validation 错误响应、MapStruct 编译与字段映射、MyBatis 持久化往返/分页、事务失败回滚。
+夹具在 test scope 使用 H2、标准 MyBatis RowBounds 和 TransactionTemplate；它不证明生产方言、YSS 自动分页切面、业务 Service 代理事务或特定
+组件能力。对应能力仍须读取所选平台的源码索引、验证实际组件并绑定独立证据。新增用例必须出现在本次
+Surefire XML 中，空测试、跳过或旧报告不可通过。没有凭据、构件、真实批准合同或组件兼容证据时保持阻断。