create-yss-spec 3.0.0 → 3.1.0

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/ARCHITECTURE.md

@@ -1,116 +0,0 @@
-# YSS DDD Target Profile
-
-本文定义 `architecture=target-domain-model` 的唯一目标结构。历史 `core/client/repository`、DTO 型 Gateway、client-in-domain 以及其他旧架构全部为 `unsupported`，不存在 legacy Profile 或回退分支。
-
-## 1. 模块职责
-
-### Domain
-
-- 聚合根、Entity、Value Object、领域行为、不变量、Domain Event。
-- 聚合持久化使用 Domain Gateway/Port，只交换 Domain Model、领域值和领域标识。
-- 不依赖 Application、Infrastructure、Repository、Web、YSS DTO/Exception、Jackson、Swagger 或 Validation。
-- Domain error 使用稳定领域错误标识和参数，不决定 HTTP status 或公开消息。
-
-推荐包：
-
-```text
-{base_package}.domain.{segment}
-├── model
-├── gateway
-├── service
-└── event
-```
-
-### Application
-
-- 定义并编排 Use Case、事务边界、Application Command/Query/Result。
-- 写用例调用 Domain Model/Domain Gateway。
-- 分页、列表和读模型通过 Application Query Port，不把 `PageQuery`、`PageResult` 或 Web VO 放入 Domain。
-- 不依赖 Infrastructure 或 Web。
-
-推荐包：
-
-```text
-{base_package}.application
-├── command
-├── query
-├── result
-├── port
-└── service
-```
-
-### Infrastructure
-
-- 实现 Domain Gateway 和 Application Query Port。
-- MyBatis-Plus Repository、PO、SQL、数据源配置和 `PO <-> Domain Model` MapStruct 转换位于本层。
-- 首个受支持 Profile 是 `persistence=mybatis-plus`；其他持久化方案必须先通过独立 fixture。
-- 事务边界由 Application 持有，不在 GatewayImpl 重复制造边界。
-
-### Adapter/Web
-
-- HTTP Request/Response、校验、Controller、WebConvertor 和异常到 HTTP/YSS Result 的映射。
-- Request 字段来自冻结 OpenAPI/批准 allowlist，不从数据库 metadata 全量推导。
-- WebConvertor 使用 `@Mapper(componentModel = "spring")` 和构造器注入。
-- DTO 物理位置固定为 Web；独立 client module 为 `unsupported`。如未来确需发布复用制品，必须另行设计并批准新的 Target Profile。
-- Web 不直接依赖 Infrastructure，不把 Domain Model 作为 Controller seam。
-
-### Bootstrap
-
-- 组合 Web 和 Infrastructure，提供机械 Spring Boot 入口与环境配置。
-- 默认配置使用 INFO；DEBUG 和 MyBatis stdout SQL 仅存在于 `application-local.yml`。
-
-## 2. 依赖方向
-
-```text
-Web -> Application -> Domain
-Infrastructure -> Application + Domain
-Bootstrap -> Web + Infrastructure
-```
-
-禁止：
-
-- Domain → Application/Infrastructure/Web
-- Application → Infrastructure/Web
-- Web → Infrastructure
-- Domain Gateway 接收 HTTP DTO、返回 Web VO/PageResult
-- Repository 把 PO 直接返回给 Application/Web
-
-上述规则由生成工程的 `ArchitectureRulesTest` 执行，不只依赖文档约定。
-
-## 3. 调用链
-
-写模型：
-
-```text
-HTTP Request -> WebConvertor -> Application Command -> Use Case
-  -> Domain Model/Domain Gateway -> GatewayImpl -> Repository/MyBatis -> PO
-```
-
-读模型：
-
-```text
-HTTP Page Request -> WebConvertor -> Application Query -> Query Port
-  -> Infrastructure Query Adapter -> Application Result -> Web Response
-```
-
-异常：
-
-```text
-Domain Error -> Application propagation/translation -> Web Exception Translator
-  -> HTTP status + stable error code + sanitized public message
-```
-
-## 4. 生成与演进
-
-- Scaffold 只生成机械模块、POM、Wrapper、配置、架构规则和 Manifest，不生成生产业务 CRUD。
-- 初始生成器为 `initialize-only`，非空目标失败。
-- Manifest v2 记录模板、脚手架父合同、Router 合同、downstream 完整 skill tree digest 与 generator-owned 文件 hash。
-- 当前不支持模板升级，不得重跑初始生成器覆盖业务工程。未来如需支持同一 Target Profile 内的模板版本升级，必须另行设计、批准并验证。
-
-## 5. 完成等级
-
-- `generated`：文件已原子生成，尚未完成 Wrapper 验证。
-- `empty-scaffold-verified`：根目录 `./mvnw validate/test/package` 全部通过。
-- `first-slice-verified`：批准且版本当前的 golden first slice 已具备 Domain 模型/Gateway、Application Service 实现/事务/Query Port、Repository/Mapper/GatewayImpl/QueryAdapter、DTO/Web/Exception 与分层测试；下游完整 skill tree digest 无漂移，且根 Wrapper 全部通过。该状态只能由 `scripts/run_first_slice_verification.mjs` 写入。
-
-只有首切片验证器可以把 Manifest 从 `empty-scaffold-verified` 升级到最后一级；手工写值、局部测试或结构扫描均无效。只有最后一级可以声明已满足下游 YSS skills 的首切片就绪条件。

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/USAGE_EXAMPLES.md

@@ -1,125 +0,0 @@
-# 使用示例
-
-## 1. 准备批准合同
-
-新合同是服务级工程基线，使用 schema v2 与 `scaffold_request_id`，并把 Java 包名、Maven 坐标和 Profile 分开登记：
-
-```json
-{
-  "schema_version": 2,
-  "scaffold_request_id": "scaffold-metadata-service-1",
-  "project_name": "metadata-service",
-  "target_output_dir": "/path/to/implementation-repo",
-  "base_package": "com.yss.metadata",
-  "maven_coordinates": {
-    "group_id": "com.yss.datamiddle",
-    "project_version": "1.0.0-SNAPSHOT",
-    "parent": {
-      "group_id": "com.yss.datamiddle",
-      "artifact_id": "yss-datamiddle-parent",
-      "version": "2.0.0-SNAPSHOT"
-    },
-    "yss_components_version": "2.0.0-SNAPSHOT"
-  },
-  "profiles": {
-    "architecture": "target-domain-model",
-    "persistence": "mybatis-plus",
-    "database": "mysql",
-    "platform": "spring-boot-2.7-jdk8",
-    "validation_namespace": "javax",
-    "dto_placement": "web",
-    "repository": "yss-internal"
-  },
-  "generation_policy": {
-    "mode": "initialize-only",
-    "existing_target": "unsupported",
-    "old_project_migration": "unsupported",
-    "template_upgrade": "unsupported"
-  }
-}
-```
-
-以上只是关键片段；实际合同还必须满足 `yss-router/references/router-contract.yaml` 中的完整 `scaffold_contract_schema`，由生命周期批准并持久化为当前版本。schema v1 合同为 `unsupported`，直接拒绝且不自动升级。
-
-## 2. 一键生成并验证
-
-```bash
-node .agents/skills/yss-ddd-scaffold-generator/scripts/generate_and_verify_scaffold.mjs \
-  --project-name metadata-service \
-  --base-package com.yss.metadata \
-  --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 \
-  --database mysql \
-  --contract-id <approved-scaffold-contract-id> \
-  --contract-version <current-version> \
-  --approval-ref <lifecycle-approval-ref> \
-  --router-draft-ref <router-draft-ref> \
-  --persisted-ref <persisted-contract-ref> \
-  --contract-file /path/to/persisted-scaffold-contract.json \
-  --evidence-dir /path/to/evidence/scaffold
-```
-
-该入口依次生成工程并在项目根实际执行：
-
-```bash
-./mvnw validate
-./mvnw test
-./mvnw package
-```
-
-执行前必须由安全环境提供 `YSS_MAVEN_REPOSITORY_URL`、`MAVEN_REPO_USERNAME`、`MAVEN_REPO_PASSWORD`；模板不固化内部 URL 或凭据。只有三条命令全部返回 0，工作流才把 Manifest 从 `generated` 更新为 `empty-scaffold-verified`。任一步失败都返回非 0并保留证据：
-
-- `scaffold-generation.stdout.log` / `scaffold-generation.stderr.log`
-- `mvnw-validate.*.log`、`mvnw-test.*.log`、`mvnw-package.*.log`
-- `scaffold-verification.json`
-- `scaffold-workflow.json`
-
-验证报告的 `failure_category` 会区分内部仓库访问、项目模型、编译、启动入口、测试和打包失败。`preflight` 只记录凭据是否配置，不记录凭据值。
-
-## 3. 生成结果
-
-```text
-metadata-service/
-├── .mvn/
-├── .yss/scaffold-generation.json
-├── mvnw
-├── pom.xml
-├── metadata-service-domain/
-├── metadata-service-application/
-├── metadata-service-infrastructure/
-├── metadata-service-adapter/
-│   └── metadata-service-web/
-└── metadata-service-bootstrap/
-    └── src/main/java/com/yss/metadata/MetadataServiceApplication.java
-```
-
-生成器只提供工程结构、POM、项目级 Maven 配置、机械启动入口和通用测试依赖，不生成实体、表、Controller、业务 API 或示例 CRUD。
-
-## 4. 后续路由
-
-`empty-scaffold-verified` 不等于业务切片可实现。后续必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract，再按影响面加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller`、`yss-dto`、`yss-exception`、`yss-validation`、`mapstruct`、`lombok`、`alibaba-java-code-style` 等 skill，并使用 `behavior-tdd` 实现业务行为。
-
-完成 golden first slice 后，必须运行：
-
-```bash
-node .agents/skills/yss-ddd-scaffold-generator/scripts/run_first_slice_verification.mjs \
-  --project-root /path/to/implementation-repo/metadata-service \
-  --slice-contract-file /path/to/approved-slice-contract.json \
-  --evidence-dir /path/to/evidence/first-slice
-```
-
-只有该验证器确认合同、全层产物、skill tree digest 与根 Wrapper 全部通过，并更新 Manifest 后，才能标记 `first-slice-verified`。
-
-目标目录必须不存在。`--force`、旧项目迁移和当前模板升级均为 `unsupported`。旧项目继续按原工程维护；现代化改造必须单独立项、先评估再逐切片迁移。
-
-如需本地启动机械入口：
-
-```bash
-cd /path/to/implementation-repo/metadata-service
-./mvnw spring-boot:run -pl metadata-service-bootstrap
-```

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-adapter/SKILL.md

@@ -1,31 +0,0 @@
----
-name: yss-backend-scaffold-adapter
-description: Use when the YSS DDD scaffold workflow reaches Web, scheduler, or external-adapter implementation and needs the shared target-profile skills.
----
-
-# Adapter Layer Reference
-
-本文件只负责从脚手架路由到共享权威技能，不维护第二套 Adapter 规范。
-
-## Web Adapter
-
-**REQUIRED SUB-SKILL:** 使用 `yss-web-controller` 作为 Web Adapter 的唯一实现指南，并同时消费 `yss-dto`、`yss-exception`：
-
-- HTTP Request / Response DTO 默认位于 Web module。
-- Controller 只调用 Application Service，不直连 Domain Gateway 或 Infrastructure。
-- 映射链固定为 Web DTO → Spring MapStruct WebConvertor → Application Command / Query / Result → Domain。
-- HTTP/YSS wrapper/异常脱敏在 Web 边界完成；Domain 只表达领域错误语义。
-
-## Scheduler / External Adapter
-
-- Adapter 只做协议、调度器或外部系统适配，不承载领域规则。
-- 输入先转换为 Application Command / Query，再调用 Application Service。
-- 若实现 Application 或 Domain 声明的端口，端口签名不得泄漏 HTTP DTO、PO、Mapper、第三方 SDK 类型。
-- 具体持久化端口实现继续使用 `yss-repository`；不得把 Repository 规则复制到本文件。
-
-## 禁止事项
-
-- 禁止 Web Controller 直接注入 Domain Gateway。
-- 禁止 `client.dto`、VO、`PageQuery` 进入 Domain。
-- 禁止静态 `Mappers.getMapper(...)` / `INSTANCE`；MapStruct 必须 `componentModel = "spring"` 并构造器注入。
-- 禁止把旧式 Controller 示例当成 `target-domain-model` 的方案。旧架构对新脚手架一律 `unsupported`；旧项目继续在原工程维护，现代化改造必须单独立项。

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-adapter/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS Scaffold Adapter"
-  short_description: "YSS 后端脚手架适配器层与接口接入设计落地标准规范"
-  default_prompt: "Use $yss-backend-scaffold-adapter to implement the adapter layer for a YSS backend scaffold module."

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-application/SKILL.md

@@ -1,8 +0,0 @@
----
-name: yss-application-layer-reference
-description: Use when the YSS DDD scaffold workflow reaches Application-layer implementation and needs the shared Application skill.
----
-
-# Application Layer Reference
-
-**REQUIRED SUB-SKILL:** Use `yss-application` as the single authoritative Application-layer implementation guide (`references/application-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-application/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS Scaffold Application"
-  short_description: "YSS 后端脚手架应用层、用例编排与 DTO 规范"
-  default_prompt: "Use $yss-application to implement the application layer for a YSS backend scaffold module."

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-domain/SKILL.md

@@ -1,8 +0,0 @@
----
-name: yss-domain-layer-reference
-description: Use when the YSS DDD scaffold workflow reaches Domain-layer implementation and needs the shared Domain skill.
----
-
-# Domain Layer Reference
-
-**REQUIRED SUB-SKILL:** Use `yss-domain` as the single authoritative Domain-layer implementation guide (`references/domain-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-domain/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS Scaffold Domain"
-  short_description: "YSS 后端脚手架领域层、聚合与规则建模实践落地规范"
-  default_prompt: "Use $yss-domain to implement the domain layer for a YSS backend scaffold module."

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-infrastructure/SKILL.md

@@ -1,8 +0,0 @@
----
-name: yss-infrastructure-layer-reference
-description: Use when the YSS DDD scaffold workflow reaches Infrastructure-layer implementation and needs the shared Repository skill.
----
-
-# Infrastructure Layer Reference
-
-**REQUIRED SUB-SKILL:** Use `yss-repository` as the single authoritative Infrastructure-layer implementation guide (`references/infrastructure-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-infrastructure/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS Scaffold Infrastructure"
-  short_description: "YSS 后端脚手架基础设施层与持久化实现设计落地规范"
-  default_prompt: "Use $yss-repository to implement the infrastructure layer for a YSS backend scaffold module."

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

@@ -1,58 +0,0 @@
----
-name: yss-backend-scaffold-parent
-description: YSS DDD scaffold Engineering Baseline entry for profile, module, dependency, build, and downstream-skill routing checks.
----
-
-# YSS DDD Scaffold Engineering Baseline
-
-本文件只定义脚手架工程基线和路由，不复制 Domain、Application、Repository、Web 的实现细则。
-
-## 当前可验证 Profile
-
-- Architecture: `target-domain-model`
-- Persistence: `mybatis-plus`
-- Database: `mysql`
-- Platform: `spring-boot-2.7-jdk8`
-- Validation namespace: `javax`
-- DTO placement: `web`
-- Repository: `yss-internal`
-
-未具备独立 fixture、受控合同和真实验证证据的组合统一为 `unsupported`。旧架构不存在可选 Profile，也不能作为回退。
-
-## 模块与依赖方向
-
-```text
-domain <- application <- web
-   ^            ^
-   |            |
-infrastructure-+
-        ^
-     bootstrap
-```
-
-- `domain`：纯 Java 领域模型、领域服务、领域事件、Domain Gateway；不得依赖 YSS DTO/Exception、Web Validation、Jackson、Swagger、MyBatis。
-- `application`：用例编排、Command / Query / Result、事务边界、Application Query Port；可以依赖 Domain 和必要的 YSS result wrapper。
-- `infrastructure`：实现 Domain Gateway / Application Query Port，拥有 PO、Mapper、持久化转换器；依赖 Domain 与 Application。
-- `adapter/web`：拥有 HTTP DTO、Controller、异常翻译、WebConvertor；只依赖 Application。
-- `bootstrap`：装配与启动，不放业务逻辑。
-
-依赖方向由 Maven Reactor、Maven Enforcer 与 ArchUnit 共同约束。MapStruct 统一使用 Spring component model，父 POM 配置 annotation processor、Lombok 与 `lombok-mapstruct-binding`。
-
-## 生成与验证
-
-- 输入是批准且持久化的服务级 scaffold contract schema v2，身份为 `scaffold_request_id`，不使用 `slice_id`。
-- 生成器严格 initialize-only：目标工程目录必须不存在，`--force`、旧项目迁移和当前模板升级均为 `unsupported`。
-- Maven 内部仓库通过命名 profile `yss-internal` 与环境变量注入；共享模板不写内部 URL 或凭据。
-- Wrapper 必须带 checksum；DEBUG 和 MyBatis stdout SQL 只允许在 `application-local.yml`。
-- `./mvnw validate`、`./mvnw test`、`./mvnw package` 全部成功只得到 `empty-scaffold-verified`。
-- 只有批准且版本当前的 golden first slice 真实组合 Domain/Application/Infrastructure/Web、通过下游 skill tree drift 校验与根 Wrapper，才能由 `run_first_slice_verification.mjs` 写入 `first-slice-verified`。
-
-## 下游权威技能
-
-- Domain：`yss-domain`
-- Application：`yss-application`
-- Persistence：`yss-repository` + `yss-mybatis`
-- Web：`yss-web-controller` + `yss-dto` + `yss-exception`
-- 横切实现约束：`yss-validation` + `mapstruct` + `lombok` + `alibaba-java-code-style`
-
-业务代码必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract，并采用 `behavior-tdd`；脚手架只生成机械工程资产。

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS Scaffold Parent"
-  short_description: "YSS 后端脚手架父工程、依赖与公共约定实践落地规范"
-  default_prompt: "Use $yss-backend-scaffold-parent to set up the parent project and shared conventions for a YSS backend scaffold."

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-web/SKILL.md

@@ -1,8 +0,0 @@
----
-name: yss-web-layer-reference
-description: Use when the YSS DDD scaffold workflow reaches Web Adapter implementation and needs the shared Web Controller skill.
----
-
-# Web Adapter Layer Reference
-
-**REQUIRED SUB-SKILL:** Use `yss-web-controller` as the single authoritative Web-layer implementation guide (`references/web-adapter-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-web/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS Scaffold Web"
-  short_description: "YSS 后端脚手架 Web 层、DTO 与控制器规范"
-  default_prompt: "Use $yss-web-controller to implement the web adapter layer for a YSS backend scaffold module."