create-yss-spec 2.1.10 → 2.1.11

package/template/.hermes/skills/yss-repository/references/infrastructure-layer-guide.md

@@ -0,0 +1,192 @@
+本 Skill 提供了 YSS **Infrastructure (基础设施层)** 的通用开发规范。Infrastructure 层负责实现 Domain 层定义的网关接口，处理数据持久化、外部服务调用和配置管理。
+
+## 1. 核心职责 (Core Responsibilities)
+
+- **实现网关接口 (Gateway Implementation)**: 实现 Domain 层定义的 `Gateway` 接口。
+- **数据持久化 (Persistence)**: 定义 `Repository` 接口和 `PO` (Persistent Object) 实体，操作数据库。
+- **对象转换 (Conversion)**: 使用 MapStruct 实现 PO 与 Domain Model/DTO 之间的转换。
+- **外部适配 (External Adapters)**: 集成外部服务 (如文件存储、消息队列)。
+
+## 2. 代码结构 (Code Structure)
+
+```
+com.yss.{module}.repository
+├── entity                  # 持久化对象 (PO)
+├── gateway.impl            # Domain Gateway 接口实现
+├── convertor               # MapStruct 转换器
+├── util                    # 工具类
+└── {Domain}Repository.java # MyBatis Plus Repository 接口
+```
+
+## 3. 开发规范 (Development Guidelines)
+
+### 3.1 持久化对象 (PO)
+
+- **命名**: `DomainName` + `PO` (e.g., `QualityTemplatePO`)。
+- **继承**: 推荐继承 `AuditableEntity` 以自动处理审计字段 (`created_by`, `created_date` 等)，但非强制要求。
+- **注解**:
+  - `@TableName("t_table_name")`: 指定数据库表名。
+  - `@TableId(value = "id", type = IdType.ASSIGN_ID)`: 指定主键策略 (雪花算法)。
+  - `@TableField("column_name")`: 指定字段映射。
+  - 按 `lombok` skill 选择最小注解；PO 默认使用 `@Getter` / `@Setter`，不得无条件使用 `@Data`。继承基类时再审查 `equals/hashCode/toString` 风险。
+
+### 3.2 Repository 接口
+
+- **继承**: `com.yss.cloud.mybatis.support.BasePlusRepository<PO>`。
+- **位置**: 直接位于 `com.yss.{module}.repository` 包下。
+- **Mapper XML**: 对应的 XML 文件位于 `src/main/resources/mappers`。
+
+### 3.3 Gateway 实现
+
+- **位置**: `com.yss.{module}.repository.gateway.impl`。
+- **注解**: `@Repository` 或 `@Service`。
+- **依赖注入**: 使用 `@RequiredArgsConstructor` (Lombok) 或 `@Autowired` 注入 Repository。
+- **查询逻辑**: 使用 `Wrappers.lambdaQuery()` 构建类型安全的查询条件。
+- **分页处理**: 使用 `PageUtil.page(query)` 构建分页对象，返回 `PageResult.of(...)`。
+
+### 3.4 对象转换 (Convertor)
+
+- **工具**: MapStruct。
+- **位置**: `com.yss.{module}.repository.convertor`。
+- **命名**: `DomainName` + `Convertor` (e.g., `QualityTemplateConvertor`)。
+- **规范**: 定义 `INSTANCE` 常量，使用 `Mappers.getMapper(...)` 获取实例。
+
+## 4. 详细案例 (Detailed Examples)
+
+### 4.1 Persistent Object (PO)
+
+```java
+package com.yss.quality.repository.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Getter;
+import lombok.Setter;
+import lombok.EqualsAndHashCode;
+
+@Getter
+@Setter
+@EqualsAndHashCode(callSuper = true)
+@TableName("t_quality_template")
+public class QualityTemplatePO extends AuditableEntity {
+
+    @TableId(value = "id", type = IdType.ASSIGN_ID)
+    private Long id;
+
+    @TableField("template_name")
+    private String templateName;
+
+    @TableField("template_code")
+    private String templateCode;
+
+    @TableField("status")
+    private Integer status;
+}
+```
+
+### 4.2 Repository Interface
+
+```java
+package com.yss.quality.repository;
+
+import com.yss.cloud.mybatis.support.BasePlusRepository;
+import com.yss.quality.repository.entity.QualityTemplatePO;
+
+public interface QualityTemplateRepository extends BasePlusRepository<QualityTemplatePO> {
+}
+```
+
+### 4.3 Gateway Implementation
+
+```java
+package com.yss.quality.repository.gateway.impl;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.yss.cloud.dto.result.PageResult;
+import com.yss.quality.client.dto.query.QualityTemplatePage;
+import com.yss.quality.client.vo.QualityTemplateVO;
+import com.yss.quality.domain.template.gateway.QualityTemplateGateway;
+import com.yss.quality.repository.QualityTemplateRepository;
+import com.yss.quality.repository.convertor.QualityTemplateConvertor;
+import com.yss.quality.repository.entity.QualityTemplatePO;
+import com.yss.quality.repository.util.PageUtil;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Repository;
+import org.springframework.util.StringUtils;
+
+import java.util.List;
+
+@Repository
+@RequiredArgsConstructor
+public class QualityTemplateGatewayImpl implements QualityTemplateGateway {
+
+    private final QualityTemplateRepository qualityTemplateRepository;
+
+    @Override
+    public PageResult<QualityTemplateVO> pageQualityTemplate(QualityTemplatePage query) {
+        LambdaQueryWrapper<QualityTemplatePO> wrapper = Wrappers.lambdaQuery(QualityTemplatePO.class);
+
+        // 构建查询条件
+        if (StringUtils.hasText(query.getTemplateName())) {
+            wrapper.like(QualityTemplatePO::getTemplateName, query.getTemplateName());
+        }
+        if (query.getStatus() != null) {
+            wrapper.eq(QualityTemplatePO::getStatus, query.getStatus());
+        }
+
+        wrapper.orderByDesc(QualityTemplatePO::getCreatedDate);
+
+        // 执行分页查询
+        IPage<QualityTemplatePO> result = qualityTemplateRepository.selectPage(PageUtil.page(query), wrapper);
+
+        // 转换结果
+        List<QualityTemplateVO> records = QualityTemplateConvertor.INSTANCE.toQualityTemplateVOList(result.getRecords());
+
+        return PageResult.of(
+                records,
+                result.getTotal(),
+                result.getSize(),
+                result.getCurrent()
+        );
+    }
+}
+```
+
+### 4.4 Convertor (MapStruct)
+
+```java
+package com.yss.quality.repository.convertor;
+
+import com.yss.quality.client.vo.QualityTemplateVO;
+import com.yss.quality.repository.entity.QualityTemplatePO;
+import org.mapstruct.Mapper;
+import org.mapstruct.factory.Mappers;
+
+import java.util.List;
+
+@Mapper
+public interface QualityTemplateConvertor {
+    QualityTemplateConvertor INSTANCE = Mappers.getMapper(QualityTemplateConvertor.class);
+
+    QualityTemplateVO toQualityTemplateVO(QualityTemplatePO po);
+
+    List<QualityTemplateVO> toQualityTemplateVOList(List<QualityTemplatePO> pos);
+}
+```
+
+## 5. 注意事项 (Notes)
+
+1.  **AuditableEntity**: 推荐业务 PO 继承此基类，以便自动维护审计信息。
+2.  **Lombok 使用**: 使用 `@RequiredArgsConstructor` 进行构造器注入是推荐的最佳实践。
+3.  **Wrapper 使用**: 优先使用 `Wrappers.lambdaQuery()` 而不是字符串列名，以提高重构安全性。
+4.  **分页工具**: 使用 `PageUtil` 统一处理分页参数，避免手动计算 offset。
+
+## 6. 阶段 7 合同
+
+- 前置条件是批准的数据架构、Repository 策略和 Slice Contract。
+- PO/Repository/Convertor 骨架可受控生成；复杂查询、分页语义、数据源、事务、迁移和并发使用 `behavior-tdd`。
+- 返回统一 `YSS Skill Execution Result`，证据包含实际文件、集成测试、MapStruct/Lombok 配置和 `./mvnw ...` 结果。

package/template/.hermes/skills/yss-router/references/boundaries.md

@@ -22,8 +22,8 @@ Default for a new page: first verify the approved product design, state matrix,
 ## Backend Boundaries
 
 - `yss-ddd-scaffold-generator`: Create a whole multi-module backend skeleton.
-- `yss-domain`: Domain modeling and domain gateway contracts.
-- `yss-backend-scaffold-application`: Application use cases, transaction boundaries, and cross-aggregate orchestration.
+- `yss-domain`: Domain modeling, domain gateway contracts, and domain-layer conventions.
+- `yss-application`: Application use cases, transaction boundaries, and cross-aggregate orchestration.
 - `yss-repository`: Persistence implementation, PO, Repository, Convertor, GatewayImpl.
 - `yss-web-controller`: REST adapter layer, request/response DTOs, VO, web convertor.
 - `yss-mybatis`: Framework behavior for MyBatis/MyBatis-Plus, BaseRepository, pagination, mapper scanning, batch, datasource issues.
@@ -39,11 +39,7 @@ Default for end-to-end backend CRUD: include Domain, Application, Infrastructure
 - `yss-audit-log`: Audit annotations, SpEL summaries, async publication, subscribers.
 - `yss-excel-mvc`: Spring MVC Excel import/export annotations and handlers.
 - `yss-distributed-id`: ID strategies, AutoIdInterceptor, Leaf/CosId/Snowflake, batch ID injection.
-- `yss-jdbc`: Hutool Db, dynamic datasource JDBC, JdbcSqlUtil, batch SQL execution.
-- `yss-dictionary`: Dictionary/domain item APIs and dictionary component integration.
-- `yss-log`: DEBUG request-parameter/success-latency logging, starter auto-configuration, and centralized collection; current `CatchAndLog` is not exception logging.
 - `yss-resilience4j`: Circuit breaker, fallback, and gateway resilience integration.
-- `yss-taskflow`: Task flow definition/execution component behavior.
 - `yss-validation`: Validation engine and JSR-303 integration.
 - `yss-security-algorithm`: RSA/AES/SM/JWT/JWK/password-encoding compatibility and production key-management safety gates.
 - `yss-userinfo`: Current-user info propagation and starter integration.

package/template/.hermes/skills/yss-router/references/router-contract.yaml

@@ -1,6 +1,9 @@
 schema_version: 1
 allowed_statuses: [draft, blocked, ready-for-lifecycle-review]
 forbidden_statuses: [approved, ready-for-agent, completed]
+skill_aliases:
+  api-integration: yss-api-integration
+  microapp-commit: yss-microapp-commit
 implementation_path_policy:
   applies_to: harness-resident-runtime-code
   project_roots:
@@ -120,24 +123,22 @@ dependency_closure:
   yss-ddd-scaffold-generator:
     always: [yss-backend-scaffold-parent, alibaba-java-code-style]
   yss-domain:
-    always: [yss-backend-scaffold-domain, alibaba-java-code-style]
+    always: [alibaba-java-code-style]
     when_modeling: [domain-modeling]
     when_pojo: [lombok]
-  yss-backend-scaffold-application:
+  yss-application:
     always: [alibaba-java-code-style]
     when_conversion: [mapstruct, lombok]
   yss-repository:
-    always: [yss-backend-scaffold-infrastructure, mapstruct, lombok, alibaba-java-code-style]
+    always: [mapstruct, lombok, alibaba-java-code-style]
     when_mybatis: [yss-mybatis]
   yss-web-controller:
-    always: [yss-dto, yss-backend-scaffold-web, mapstruct, lombok, alibaba-java-code-style]
+    always: [yss-dto, mapstruct, lombok, alibaba-java-code-style]
   yss-userinfo:
     always: [yss-dto]
     when_cache_lookup: [yss-cache]
   yss-audit-log:
     always: [yss-userinfo, yss-dto]
-  yss-log:
-    always: []
   yss-validation:
     always: [yss-exception]
   yss-security-algorithm:
@@ -156,7 +157,6 @@ component_impact_values:
   - current-user-context
   - user-cache-lookup
   - audit-event
-  - technical-request-logging
   - request-validation
   - error-mapping
   - encryption-or-signing
@@ -165,20 +165,16 @@ component_impact_routing:
   current-user-context: [yss-userinfo]
   user-cache-lookup: [yss-userinfo, yss-cache]
   audit-event: [yss-audit-log, yss-userinfo, yss-dto]
-  technical-request-logging: [yss-log]
   request-validation: [yss-validation, yss-exception]
   error-mapping: [yss-exception, yss-dto]
   encryption-or-signing: [yss-security-algorithm, yss-exception]
 
 end_to_end_backend_required:
   - yss-domain
-  - yss-backend-scaffold-domain
-  - yss-backend-scaffold-application
+  - yss-application
   - yss-repository
-  - yss-backend-scaffold-infrastructure
   - yss-web-controller
   - yss-dto
-  - yss-backend-scaffold-web
   - mapstruct
   - lombok
   - alibaba-java-code-style

package/template/.hermes/skills/yss-source-index/references/source-map-config.md

@@ -12,11 +12,7 @@ The refresh script maps component source path hints to skill references. These p
 | `yss-audit-log` | `yss-microservice-components/yss-component-audit-log` |
 | `yss-excel-mvc` | `yss-microservice-components/yss-component-excel-mvc`, `yss-microservice-components/yss-component-excel-starter` |
 | `yss-distributed-id` | `yss-microservice-components/yss-component-distributed-id`, `yss-microservice-components/yss-component-leaf` |
-| `yss-jdbc` | `yss-microservice-components/yss-component-jdbc` |
-| `yss-dictionary` | `yss-microservice-components/yss-component-dictionary-parent` |
-| `yss-log` | `yss-microservice-components/yss-component-log-starter` |
 | `yss-resilience4j` | `yss-microservice-components/yss-component-resilience4j-starter` |
-| `yss-taskflow` | `yss-microservice-components/yss-component-taskflow` |
 | `yss-validation` | `yss-microservice-components/yss-component-validation-engine-parent`, `yss-microservice-components/yss-component-validation-jsr303` |
 | `yss-security-algorithm` | `yss-microservice-components/yss-component-security-algorithm` |
 | `yss-userinfo` | `yss-microservice-components/yss-component-userinfo-starter` |

package/template/.hermes/skills/yss-source-index/scripts/refresh-yss-skill-index.mjs

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-jdbc":["yss-microservice-components/yss-component-jdbc"],"yss-dictionary":["yss-microservice-components/yss-component-dictionary-parent"],"yss-log":["yss-microservice-components/yss-component-log-starter"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-taskflow":["yss-microservice-components/yss-component-taskflow"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
+const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
 const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-page-module-development":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
 const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
 const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];

package/template/.hermes/skills/yss-web-controller/SKILL.md

@@ -63,6 +63,7 @@ node scripts/generate_controller.mjs \
 
 ## 按需读取
 
+- 分层开发规范：`references/web-adapter-layer-guide.md`
 - 生成脚本：`scripts/generate_controller.mjs`
 - Controller 模板：`assets/templates/Controller.java.template`
 - Convertor 模板：`assets/templates/WebConvertor.java.template`

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

@@ -0,0 +1,168 @@
+本技能为开发 YSS 服务的**Web 适配器层**（REST API）提供指导和框架。
+Web 适配器负责通过 HTTP 公开业务功能、处理输入验证和格式化响应。
+
+## 1. 核心职责 (Core Responsibilities)
+
+- **Request Handling**: Map HTTP requests (GET, POST, PUT, DELETE) to Java methods.
+- **Input Validation**: Validate request bodies and parameters using JSR-303/380 annotations (`@Valid`, `@NotNull`, etc.).
+- **Response Formatting**: Wrap business results into standard `Result` objects (`SingleResult`, `PageResult`, `MultiResult`).
+- **Orchestration Delegation**: Delegate business logic to the **Application Service**. Simple queries can be delegated directly to the **Domain Gateway** (CQRS pattern).
+
+## 2. 代码结构 (Code Structure)
+
+Web Adapters are typically located in the `bootstrap` module or a dedicated `web` module.
+
+```
+com.yss.{module}.rest
+├── {Domain}Controller.java      # Main REST Controller
+└── {Domain}ReportController.java # Optional: For reporting/stats APIs
+```
+
+## 3. 开发规范 (Development Guidelines)
+
+### 3.1 Controller 定义
+
+- **注解**: 使用 `@RestController`。
+- **路径**: `@RequestMapping("/api/{module}/{domain}")` (e.g., `/api/quality/rule`).
+- **依赖注入**: 使用 Lombok `@RequiredArgsConstructor` 进行构造器注入。
+- **命名**: `{Domain}Controller` (e.g., `QualityRuleController`).
+
+### 3.2 依赖注入原则
+
+- **写操作/复杂逻辑**: 必须注入 **Application Service** (`XxxService`)。
+- **读操作 (Query)**: 允许直接注入 **Domain Gateway** (`XxxGateway`) 以减少样板代码 (CQRS)。
+
+### 3.3 参数与响应
+
+- **Command (写)**: 使用 `@PostMapping`/`@PutMapping` + `@RequestBody` + `{Domain}Cmd` 对象。
+- **Query (读)**: 使用 `@PostMapping` (for complex search) + `@RequestBody` + `{Domain}Page/Query` 对象。
+- **Wrapper**:
+  - `SingleResult<T>`: 单个对象或基本类型。
+  - `MultiResult<T>`: 列表。
+  - `PageResult<T>`: 分页数据。
+- **Validation**: 必须在参数前添加 `@Valid` 注解。
+
+### 3.4 异常处理
+
+- **不要**在 Controller 中捕获通用异常 (`Exception`)。
+- 让全局异常处理器 (`GlobalExceptionHandler`) 统一处理运行时异常。
+- 仅在需要特定 HTTP 状态码转换时捕获特定异常。
+
+## 4. 代码示例 (Code Examples)
+
+### 4.1 标准 CRUD Controller
+
+```java
+package com.yss.{module}.rest;
+
+import com.yss.cloud.dto.result.MultiResult;
+import com.yss.cloud.dto.result.PageResult;
+import com.yss.cloud.dto.result.SingleResult;
+import com.yss.{module}.client.dto.cmd.{Domain}AddCmd;
+import com.yss.{module}.client.dto.cmd.{Domain}UpdateCmd;
+import com.yss.{module}.client.dto.cmd.{Domain}StatusCmd;
+import com.yss.{module}.client.dto.query.{Domain}Page;
+import com.yss.{module}.client.vo.{Domain}VO;
+import com.yss.{module}.core.service.{Domain}Service;
+// Optional: Import Gateway for direct queries
+// import com.yss.{module}.domain.gateway.{Domain}Gateway;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+
+import javax.validation.Valid;
+
+/**
+ * {Domain} 管理控制器
+ *
+ * @author {User}
+ */
+@RestController
+@RequestMapping("/api/{module}/{domain-path}")
+@RequiredArgsConstructor
+public class {Domain}Controller {
+
+    private final {Domain}Service {domainVar}Service;
+    // private final {Domain}Gateway {domainVar}Gateway; // For CQRS if needed
+
+    /**
+     * 分页查询 {Domain}
+     *
+     * @param query 查询条件
+     * @return 分页结果
+     */
+    @PostMapping("/page")
+    public PageResult<{Domain}VO> page(@Valid @RequestBody {Domain}Page query) {
+        return {domainVar}Service.page(query);
+    }
+
+    /**
+     * 根据ID查询详情
+     *
+     * @param id 主键ID
+     * @return 详情对象
+     */
+    @GetMapping("/detail/{id}")
+    public SingleResult<{Domain}VO> detail(@PathVariable String id) {
+        return SingleResult.of({domainVar}Service.detail(id));
+    }
+
+    /**
+     * 新增 {Domain}
+     *
+     * @param cmd 新增命令
+     * @return 新增结果 (通常是ID或完整对象)
+     */
+    @PostMapping
+    public SingleResult<Long> add(@Valid @RequestBody {Domain}AddCmd cmd) {
+        return SingleResult.of({domainVar}Service.add(cmd));
+    }
+
+    /**
+     * 更新 {Domain}
+     *
+     * @param cmd 更新命令
+     * @return 更新结果
+     */
+    @PutMapping
+    public SingleResult<Boolean> update(@Valid @RequestBody {Domain}UpdateCmd cmd) {
+        {domainVar}Service.update(cmd);
+        return SingleResult.of(true);
+    }
+
+    /**
+     * 状态变更 (启用/禁用)
+     *
+     * @param cmd 状态命令
+     * @return 变更后的状态
+     */
+    @PostMapping("/enabled")
+    public SingleResult<Integer> switchStatus(@Valid @RequestBody {Domain}StatusCmd cmd) {
+        {domainVar}Service.switchStatus(cmd);
+        return SingleResult.of(cmd.getStatus());
+    }
+}
+```
+
+### 4.2 复杂业务操作示例
+
+```java
+    /**
+     * 执行业务操作 (e.g. 立即运行检查)
+     *
+     * @param cmd 执行命令
+     * @return 执行结果ID
+     */
+    @PostMapping("/execute")
+    public SingleResult<String> execute(@Valid @RequestBody {Domain}ExecuteCmd cmd) {
+        // 调用 Service 处理复杂业务逻辑
+        return SingleResult.of(
+                {domainVar}Service.execute(cmd)
+        );
+    }
+```
+
+## 5. 阶段 7 合同
+
+- 只消费冻结 OpenAPI/no-impact record 和批准合同；Controller 不得穿透 Application/Domain 边界。
+- Controller/DTO/Convertor 骨架可受控生成；权限、校验、错误映射和接口行为使用 `behavior-tdd`。
+- 返回统一 `YSS Skill Execution Result`，包含代码、契约/API 测试、实际验证和新增 API/权限影响。

package/template/.pi/skills/ask-matt/SKILL.md

@@ -8,9 +8,15 @@ disable-model-invocation: true
 
 You don't remember every skill, so ask.
 
+## YSS default (read this first)
+
+In this template, **`yss-product-lifecycle` is the default orchestrator**. Native work-units own Spec, tickets, implementation authorization, and gates.
+
+This skill is a **Matt compatibility map**. Use `/grill-with-docs`, `/to-spec`, `/to-tickets`, and `/implement` only when the user **explicitly** names them. Do not treat the idea→ship list below as the YSS default. `/implement` does not grant git commit/push. Spec drafts from `/to-spec` stay `ready-for-human` until a human approves the Spec baseline.
+
 A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
 
-## The main flow: idea → ship
+## Matt compatibility flow: idea → ship
 
 The route most work travels. You have an idea and want it built.
 
@@ -23,7 +29,7 @@ The route most work travels. You have an idea and want it built.
    - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `docs/.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
    - **No** → **`/implement`** right here, in the same context window.
 
-   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`** (Standards + Spec, plus UI fidelity when UI is in scope). Do not commit or push from `/implement`. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
 
 ### Context hygiene
 

package/template/.pi/skills/code-review/SKILL.md

@@ -3,12 +3,13 @@ name: code-review
 description: Use when the user wants to review a branch, PR, committed candidate, uncommitted work-in-progress changes, or changes since a fixed point.
 ---
 
-Two-axis review of a pinned candidate against a fixed point:
+Review of a pinned candidate against a fixed point on two core axes, plus UI fidelity when UI is in scope:
 
 - **Standards** — does the code conform to this repo's documented coding standards?
 - **Spec** — does the code faithfully implement the originating issue / spec?
+- **UI fidelity** (only when the change has UI impact) — does the candidate match the confirmed prototype and `yss-design-system` / `yss-ui`? Type-check or claiming "already aligned" is not a pass. Invoke those skills' verification notes; do not collapse this axis into Standards or Spec.
 
-Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+Standards and Spec run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. When UI is in scope, add a separate UI fidelity pass after those two reports (do not merge it into either axis).
 
 If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
@@ -99,17 +100,18 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor
 
 ### 5. Aggregate
 
-Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_).
 
 For Worktree mode, recapture the candidate digest after both reports return. If it differs from `candidate_digest`, mark both reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 
 State the reviewed `review_mode`, fixed point, candidate digest and coverage before the two reports. End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
 
-## Why two axes
+## Why separate axes
 
 A change can pass one axis and fail the other:
 
 - Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
 - Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+- Code that implements the spec but diverges from the confirmed prototype or design system → **Spec pass, UI fidelity fail.**
 
 Reporting them separately stops one axis from masking the other.

package/template/.pi/skills/high-fidelity-html-prototype/SKILL.md

@@ -102,5 +102,5 @@ High-fidelity HTML prototype
 - <yes/no; list blocking gaps>
 
 ### 下一步
-- <Spec calibration / return to high-fidelity prototype / return to product-design-prototype>
+- <Spec calibration / return to high-fidelity prototype / return to yss-prototype-stage>
 ```

package/template/.pi/skills/implement/SKILL.md

@@ -12,4 +12,4 @@ Run typechecking regularly, single test files regularly, and the full test suite
 
 Once done, use /code-review to review the work.
 
-Commit your work to the current branch.
+Do not commit or push. Implementation authorization does not include git commit/push. Natural language such as "do it and commit" is not structured Git authorization. Stop after review unless a structured Git authorization is already present.

package/template/.pi/skills/to-spec/SKILL.md

@@ -16,7 +16,7 @@ If the issue tracker or triage label vocabulary is missing, tell the user to run
 
 Check with the user that these seams match their expectations.
 
-3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
+3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-human` triage label. Spec drafts need a human baseline approval before they are `approved`, and before implementation tickets may become `ready-for-agent`. Do not label the Spec itself `ready-for-agent`.
 
 <spec-template>
 

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

@@ -5,6 +5,8 @@ description: Guide AI to correctly use Orval-generated API clients in Vue 3 micr
 
 # API 集成 Skill
 
+目录与锁文件身份是 `yss-api-integration`；Agent 发现名与 Router 闭包键是 `api-integration`。二者指向同一技能，注册表以 alias 对齐。
+
 ## 📋 目标
 
 帮助 AI 正确使用基于 **Orval** 生成的 API 客户端：

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

@@ -0,0 +1,52 @@
+---
+name: yss-application
+description: Use when implementing YSS application use cases, transaction boundaries, cross-aggregate orchestration, idempotency, or application-level DTO conversion.
+---
+
+# yss-application
+
+Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事务边界和跨聚合流程，不承载核心领域规则。
+
+## 何时使用
+
+- 用户要实现 Application Service、用例编排或 `@Transactional` 边界。
+- 用户要补 App 层 MapStruct Convertor 或跨聚合协调逻辑。
+- 脚手架生成完成后进入业务实现，Router 按 `backend_impact` 加载本 skill。
+
+## 不适用
+
+- 只做领域建模时，优先 `yss-domain`。
+- 只做持久层时，优先 `yss-repository`。
+- 只做 Controller 时，优先 `yss-web-controller`。
+
+## 工作方式
+
+1. 先探测工程是新 DDD `application/domain/infrastructure/adapter` 还是 legacy `core/client/repository` profile。
+2. 确认 Use Case、Application 边界、事务边界已在批准合同中写明。
+3. 实现 AppService 时调用 Domain Service / Gateway，核心规则下沉 Domain。
+4. 涉及 POJO 样板加载 `lombok`；涉及 App 层转换加载 `mapstruct`。
+5. 详细包结构、注解、示例和 legacy 兼容说明见 `references/application-layer-guide.md`。
+
+## 产物范围
+
+- `application/.../service/*Service.java`（或 legacy `core/service`）
+- `application/.../service/impl/*ServiceImpl.java`
+- `application/.../service/convertor/*Convertor.java`（MapStruct）
+
+## 协同顺序
+
+- 领域建模：`yss-domain`
+- 持久层：`yss-repository`
+- Web 适配：`yss-web-controller`
+- DTO 契约：`yss-dto`
+
+## 阶段 7 合同
+
+- 只消费批准后的 `Slice Implementation Contract` 和当前 `work_unit`。
+- AppService 骨架可 `controlled-generation`；用例编排、事务、幂等、权限和失败行为必须 `behavior-tdd`。
+- 按 `yss-router/references/yss-skill-execution-result.md` 返回统一 `YSS Skill Execution Result`。
+- 发现新 API、权限、状态机或跨上下文影响时填入 `new_impacts` 并暂停。
+
+## 按需读取
+
+- 分层开发规范：`references/application-layer-guide.md`

package/template/.pi/skills/yss-application/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Application Layer"
+  short_description: "YSS Application 层用例编排、事务边界与跨聚合协调规范"
+  default_prompt: "Use $yss-application to implement the application layer for a YSS backend module."