create-yss-spec 2.2.8 → 2.2.10

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

@@ -1,274 +1,99 @@
-本 Skill 提供了 YSS 数据质量管理服务 **Domain (领域层)** 的开发规范。Domain 层是系统的核心，包含业务逻辑、领域模型和接口定义。
+# YSS Domain Target Profile 指南
 
-## 1. 核心职责 (Core Responsibilities)
+本指南只定义新 DDD `target-domain-model`。历史 DTO/VO 型 Gateway、`core/client/repository` 和贫血对象均为 `unsupported`，不存在旧架构 Profile 或迁移分支。
 
-- **定义业务模型 (Model)**: 包含实体 (Entity)、值对象 (VO)、聚合根 (Aggregate Root)。
-- **定义服务接口 (Gateway/Service)**: 定义与 Infrastructure 层交互的接口 (Gateway) 以及领域内部服务 (Domain Service)。
-- **定义数据契约 (DTO)**: 定义 Command (增删改), Query (查询), VO (视图) 等数据传输对象。
-- **业务逻辑实现**: 核心业务规则的校验和处理。
+## 1. Domain 所有权
 
-## 2. 代码结构 (Code Structure)
+Domain 只拥有：
 
-```
-com.yss.{module}
-├── client                  # 对外暴露的数据契约 (DTOs)
-│   ├── dto
-│   │   ├── cmd             # Command: 写操作参数 (e.g., QualityRuleAddCmd)
-│   │   └── query           # Query: 读操作参数 (e.g., QualityRulePage)
-│   └── vo                  # Value Object: 返回结果 (e.g., QualityBusinessRuleVO)
-└── domain                  # 领域核心实现
-    └── {domain_name}       # 具体的领域模块 (e.g., user, metadata)
-        ├── gateway         # 网关接口定义 (e.g., UserGateway)
-        ├── model           # 领域实体/枚举 (e.g., User, UserType)
-        └── service         # 领域服务 (e.g., UserService)
-```
-
-## 3. 开发规范 (Development Guidelines)
-
-### 3.1 数据传输对象 (DTO)
-
-- **Command (Cmd)**: 用于数据修改 (Create/Update/Delete)。
-  - 继承 `com.yss.cloud.dto.CommandDTO`。
-  - 按 `lombok` skill 选择 `@Getter` / `@Setter` / 构造器等最小注解；不默认使用 `@Data`。
-  - 必须使用 JSR-303/380 注解进行参数校验 (`@NotBlank`, `@NotNull`, `@Size` 等)。
-  - **示例**: `QualityRuleAddCmd`
-
-- **Query**: 用于数据查询。
-  - 分页查询继承 `com.yss.cloud.dto.page.PageQuery`。
-  - 普通查询继承 `com.yss.cloud.dto.QueryDTO`。
-  - **示例**: `QualityRulePage`
-
-- **View Object (VO)**: 用于展示层返回数据。
-  - 纯 POJO 仍按 `lombok` skill 选择最小注解；涉及身份、关系、敏感字段或懒加载时不得默认使用 `@Data`。
-  - **示例**: `QualityBusinessRuleVO`
-
-### 3.2 网关接口 (Gateway)
-
-Gateway 定义了领域层对外的依赖接口，通常由 Infrastructure 层实现。
-
-- **命名**: `DomainName` + `Gateway` (e.g., `QualityTemplateGateway`)。
-- **方法定义规范**:
-  - **分页查询**: `PageResult<VO> pageXxx(Query query)`
-  - **列表查询**: `List<VO> listXxx(Query query)`
-  - **单条查询**: `VO getXxxById(Long id)` 或 `VO getXxxByCode(String code)`
-  - **新增**: `Long/ResultVO addXxx(Cmd cmd)` (返回 ID 或 结果对象)
-  - **更新**: `void/ResultVO updateXxx(Cmd cmd)`
-  - **删除**: `void deleteXxx(Cmd cmd)`
-
-### 3.3 领域服务 (Domain Service)
-
-当业务逻辑涉及多个聚合根或不适合放入单一实体时，使用 Domain Service。
-
-- **命名**: `DomainName` + `Service` (e.g., `QualityTemplateService`)。
-- **职责**: 编排领域逻辑，调用 Gateway。
-
-### 3.4 常用类与注解
-
-- **分页结果**: `com.yss.cloud.dto.result.PageResult<T>`
-- **校验注解**: `javax.validation.constraints.*` (`@NotNull`, `@NotBlank`)
-- **Lombok**: 按对象语义选择 `@Getter`, `@Setter`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor`，不默认使用聚合式 `@Data`。
-
-## 4. 详细案例 (Detailed Examples)
-
-### 4.1 Command (新增命令)
-
-```java
-package com.yss.quality.client.dto.cmd;
-
-import com.yss.cloud.dto.CommandDTO;
-import com.yss.quality.domain.QualityRuleTemplateType;
-import com.yss.quality.domain.QualityType;
-import com.yss.quality.domain.datasource.entity.DatabaseType;
-import com.yss.quality.domain.rule.entity.QualityRuleType;
-import lombok.Getter;
-import lombok.Setter;
-
-import javax.validation.constraints.NotBlank;
-import javax.validation.constraints.NotEmpty;
-import javax.validation.constraints.NotNull;
-import java.util.List;
-import java.util.Map;
-
-/**
- * 数据质量规则模板新增命令对象
- */
-@Getter
-@Setter
-public class QualityTemplateAddCmd extends CommandDTO {
-
-    @NotBlank(message = "模板名称不能为空")
-    private String templateName;
-
-    @NotBlank(message = "模板编码不能为空")
-    private String templateCode;
+- Aggregate Root、Entity、Value Object。
+- 领域行为、不变量、状态转换和 Domain Event。
+- 聚合持久化及外部领域能力所需的 Gateway/Port。
+- 稳定的领域错误标识与错误参数。
 
-    @NotEmpty(message = "数据库类型不能为空")
-    private List<DatabaseType> databaseType;
+Domain 不拥有：
 
-    @NotNull(message = "模板类型不能为空")
-    private QualityRuleTemplateType templateType;
+- HTTP Cmd/Query/VO、YSS `PageQuery` / `PageResult`。
+- Repository PO、Mapper、SQL、Controller。
+- HTTP status、YSS Result 包装或公开错误消息。
 
-    @NotNull(message = "模板规则类型不能为空")
-    private QualityType ruleType;
+## 2. 包结构
 
-    private String description;
-
-    @NotBlank(message = "异常SQL不能为空")
-    private String exceptionCountSql;
-
-    @NotNull
-    private String resultLabel;
-
-    private Boolean defaultFlag;
-
-    Map<String, Object> ruleTemplateParam;
-}
+```text
+{base_package}.domain.{segment}
+├── model
+├── gateway
+├── service
+└── event
 ```
 
-### 4.2 Query (分页查询)
-
-```java
-package com.yss.quality.client.dto.query;
-
-import com.yss.cloud.dto.page.PageQuery;
-import com.yss.quality.domain.QualityRuleTemplateType;
-import com.yss.quality.domain.QualityType;
-import lombok.Getter;
-import lombok.Setter;
-
-import javax.validation.constraints.NotNull;
+DTO/VO 位于 `{base_package}.rest.dto`。独立 client Maven module 对当前 Target Profile 为 `unsupported`；不得放回 Domain module。
 
-/**
- * 数据质量规则模板查询对象
- */
-@Getter
-@Setter
-public class QualityTemplatePage extends PageQuery {
-    /**
-     * 模板类型
-     */
-    private QualityRuleTemplateType templateType;
+## 3. Aggregate 与行为
 
-    /**
-     * 规则类型
-     */
-    @NotNull
-    private QualityType ruleType;
+- Aggregate Root 是一致性边界，不按表数量机械拆分。
+- Entity identity 使用明确类型；Value Object 按值相等并尽量不可变。
+- 对外暴露业务动作，例如 `publish()`、`cancel()`，不要让 Application 任意修改状态字段。
+- 每个批准不变量必须有 `behavior-tdd` 测试；测试通过聚合公开方法观察结果。
+- 没有真实行为时保持简单模型，不为了“看起来像 DDD”制造空 Domain Service。
 
-    /**
-     * 模板名称
-     */
-    private String templateName;
-
-    private Integer status;
-}
-```
+## 4. Gateway
 
-### 4.3 Gateway (网关接口)
+Gateway 描述领域能力，只交换 Domain Model、领域值和领域标识。例如：
 
 ```java
 package com.yss.quality.domain.template.gateway;
 
-import com.yss.cloud.dto.result.PageResult;
-import com.yss.quality.client.dto.cmd.QualityTemplateAddCmd;
-import com.yss.quality.client.dto.cmd.QualityTemplateDeleteCmd;
-import com.yss.quality.client.dto.cmd.QualityTemplateUpdateCmd;
-import com.yss.quality.client.dto.query.QualityTemplatePage;
-import com.yss.quality.client.vo.QualityTemplateVO;
+import com.yss.quality.domain.template.model.QualityTemplate;
+import com.yss.quality.domain.template.model.QualityTemplateId;
+import java.util.Optional;
 
-/**
- * 数据质量规则模板网关接口
- */
 public interface QualityTemplateGateway {
-
-    /**
-     * 分页查询数据质量规则模板
-     */
-    PageResult<QualityTemplateVO> pageQualityTemplate(QualityTemplatePage query);
-
-    /**
-     * 根据ID查询数据质量规则模板
-     */
-    QualityTemplateVO getQualityTemplateById(Long id);
-
-    /**
-     * 新增数据质量规则模板
-     */
-    Long addQualityTemplate(QualityTemplateAddCmd cmd);
-
-    /**
-     * 更新数据质量规则模板
-     */
-    void updateQualityTemplate(QualityTemplateUpdateCmd cmd);
-
-    /**
-     * 删除数据质量规则模板
-     */
-    void deleteQualityTemplate(QualityTemplateDeleteCmd cmd);
+    Optional<QualityTemplate> findById(QualityTemplateId id);
+    void save(QualityTemplate template);
 }
 ```
 
-### 4.4 Domain Service (领域服务)
+禁止在 Domain Gateway 中出现：
 
-```java
-package com.yss.quality.domain.template.service;
+- `*AddCmd`、`*UpdateCmd`、HTTP request。
+- `*VO`、`PageResult`、Repository PO。
+- MyBatis、Spring MVC、Jackson、Swagger 类型。
 
-import com.yss.cloud.dto.result.PageResult;
-import com.yss.quality.client.dto.cmd.QualityTemplateAddCmd;
-import com.yss.quality.client.dto.query.QualityTemplatePage;
-import com.yss.quality.client.vo.QualityTemplateVO;
+分页、列表和投影查询由 Application Query Port 定义，Infrastructure 实现。
 
-/**
- * 数据质量规则模板服务接口
- */
-public interface QualityTemplateService {
+## 5. Domain Error
 
-    PageResult<QualityTemplateVO> pageQualityTemplate(QualityTemplatePage query);
+领域错误携带稳定标识和参数，不决定 HTTP 行为：
 
-    QualityTemplateVO getQualityTemplateById(Long id);
+```java
+public final class QualityTemplateNameConflict extends RuntimeException {
+    private final String templateName;
 
-    Long addQualityTemplate(QualityTemplateAddCmd cmd);
+    public QualityTemplateNameConflict(String templateName) {
+        super("quality-template-name-conflict");
+        this.templateName = templateName;
+    }
 
-    // 更多业务方法...
+    public String templateName() {
+        return templateName;
+    }
 }
 ```
 
-### 4.5 Value Object (视图对象)
-
-```java
-package com.yss.quality.client.vo;
-
-import lombok.Getter;
-import lombok.Setter;
-import java.io.Serializable;
-import java.util.Map;
+Web Exception Translator 再将它映射为批准的状态码、错误码和消毒消息。Domain 不直接依赖 YSS `BizException`。
 
-/**
- * 数据质量规则模板值对象
- */
-@Getter
-@Setter
-public class QualityTemplateVO implements Serializable {
-    private Long id;
-    private String templateName;
-    private String templateCode;
-    private String resultLabel;
-    private String databaseType;
-    private String qualityRuleType;
-    private String qualityType;
-    private Map<String,Object> ruleTemplateParam;
-    private Boolean defaultFlag;
-}
-```
+## 6. 依赖门禁
 
-## 5. 注意事项 (Notes)
+生成工程的 ArchUnit 规则必须证明：
 
-1.  **依赖倒置**: Domain 层**不应依赖** Infrastructure 层或 Web 层。所有外部交互通过 Gateway 接口定义。
-2.  **贫血模型 vs 充血模型**: 虽然目前主要是贫血模型 (DTO/VO)，但鼓励将核心业务逻辑下沉到 Domain Model 中。
-3.  **参数校验**: 必须在 Cmd 对象中使用注解进行严格的参数校验，Gateway 实现层应进行 `@Valid` 校验。
+- Domain 不依赖 Application、Infrastructure、Repository 或 Web。
+- Domain 不依赖 YSS DTO/Exception、Jackson、Swagger 或 Validation。
+- 负例 fixture 中的 Domain → Web DTO 引用会使验证失败。
 
-## 6. 阶段 7 合同
+## 7. 生命周期证据
 
-- 领域规则、状态机和不变量必须使用 `behavior-tdd`；只允许 DTO/VO/接口等机械骨架使用受控生成。
-- 消费批准后的合同和 work unit，写入允许路径，并返回统一 `YSS Skill Execution Result`。
-- 发现新的状态机、权限、数据模型、API 或跨上下文影响时返回 `new_impacts` 并暂停。
+- 消费批准且当前的 Tactical Design 与 Slice Implementation Contract。
+- 返回 YSS Skill Execution Result，包含 Domain 文件、行为测试、ArchUnit 结果及实际 `./mvnw ...` 证据。
+- 新聚合、不变量、状态机或跨上下文影响进入 `new_impacts` 并暂停。
+- 检测到旧架构时返回 `unsupported`；如需现代化，退出 scaffold 工作流并单独立项评估。

package/template/.hermes/skills/yss-dto/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-dto
-description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`, `PageQuery`, `CommandDTO`, `QueryDTO`, pagination, or response-wrapper compatibility is involved.
+description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`, `PageQuery`, `CommandDTO`, `QueryDTO`, pagination, or response-wrapper boundaries are involved.
 ---
 
 # yss-dto
@@ -20,7 +20,7 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 1. 优先沿用项目现有 DTO 体系，不重复造返回包装类。
 2. 涉及真实类名、返回结构、分页字段或排障时，先读 `references/source-index.md`，再定位源码或文档。
-3. 先确认当前项目用的是哪一套结果封装和实际 import；新契约的 canonical 包是 `com.yss.cloud.dto.result`，`com.yss.cloud.dto.response` 只能作为 legacy / compatibility 线索，不能在新契约中引入。
+3. 新 Target Profile 的 canonical 包固定为 `com.yss.cloud.dto.result`；`com.yss.cloud.dto.response` 为 `unsupported`，不得在新契约或脚手架输出中引入。检测到旧包时只报告边界，不自动改写；旧项目现代化须单独立项。
 4. 需要设计或审查 API 时，先校验 `references/openapi-wire-profile.yaml`，再把 endpoint 的具体 DTO/VO schema 组合到 wrapper；Java 泛型不是 OpenAPI schema。
 5. 只围绕当前 DTO 结构回答，不泛化到整个微服务理论。
 
@@ -36,8 +36,8 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 ## 使用规则
 
 - 写操作参数优先继承 `CommandDTO`。
-- 读操作参数优先继承 `QueryDTO` 或 `PageQuery`。
-- 分页查询优先继承 `PageQuery`，不要自行发明分页字段名。
+- Application/Infrastructure 内部读参数可按项目 Profile 使用 `QueryDTO` 或 `PageQuery`。
+- 公开 HTTP Page Request 默认不继承 `PageQuery`，只复制冻结 OpenAPI 允许的分页字段，再由 WebConvertor 转为 Application Query；避免继承的 `offset`、`needTotalCount`、`tempTotalCount` 进入绑定面。
 - Controller 返回优先使用项目既有的 `Result` 或派生结果对象。
 - 单对象返回优先 `SingleResult`，列表返回优先 `MultiResult`，分页返回优先 `PageResult`，前提是当前项目已采用这套体系。
 - 三种泛型结果要求 `T extends Serializable`；生成的 VO/响应类型必须满足该编译约束。
@@ -54,7 +54,7 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 - 分页字段名是否和框架约定一致。
 - `orderBy` / `groupBy` 是否经过 Repository 白名单映射，禁止直接拼接 SQL。
-- Service / Repository 是否真的接收到了 `PageQuery`。
+- Application Query Port / Infrastructure 是否收到批准的分页语义；Domain Gateway 不接收 `PageQuery`。
 - 新增 DTO 是否与现有序列化和校验方式兼容。
 - 返回结构是否和前端或上游调用方契约一致。
 - 是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。

package/template/.hermes/skills/yss-dto/references/README.md

@@ -46,7 +46,7 @@
 
 ## HTTP/JSON 映射边界
 
-- 新契约使用 `com.yss.cloud.dto.result`；`com.yss.cloud.dto.response` 只作为 legacy / compatibility 线索。
+- 新 Target Profile 只使用 `com.yss.cloud.dto.result`；`com.yss.cloud.dto.response` 为 `unsupported`，不得由新契约或脚手架引入，也不自动迁移旧项目。
 - 公共响应 schema 使用 `YssResultMeta`，具体 endpoint schema 使用 `allOf` 组合，并声明 `x-yss-response-wrapper`。
 - `MultiResult.data` 和 `PageResult.data` 为数组；`SingleResult.data` 绑定具体 endpoint schema。不要把 `SingleResult<T>`、`MultiResult<T>` 或 `PageResult<T>` 的 Java 泛型文字直接写成 OpenAPI schema。
 - `PageQuery` 的客户端字段是 `pageIndex/pageSize/orderBy/orderDirection/groupBy`；`offset`、`needTotalCount`、`tempTotalCount` 不属于客户端输入。`totalPages` 只有目标 mapper / contract evidence 证明后才进入响应契约。
@@ -63,5 +63,5 @@
 ## 使用场景
 
 1. **API 响应**: 所有 Controller 方法应返回 `Result` 或其子类（如 `PageResult`, `SingleResult`）。
-2. **分页查询**: Controller 接收分页请求时，参数类应继承 `PageQuery`。MyBatis 分页插件会自动识别并处理。
+2. **分页查询**: `PageQuery` 用于 Application/Infrastructure 内部协作；公开 HTTP Page Request 默认只声明冻结 OpenAPI 允许的字段，再由 WebConvertor 转换，避免内部字段被继承到绑定面。MyBatis 拦截器所需形状必须由 Query Port 集成测试证明。
 3. **参数封装**: 使用 `CommandDTO` 封装增删改参数，使用 `QueryDTO` 封装查询参数，保持代码语义清晰。

package/template/.hermes/skills/yss-dto/references/openapi-wire-profile.yaml

@@ -14,11 +14,11 @@ canonical:
     response_wrapper_extension: x-yss-response-wrapper
     literal_java_generic_schema: false
 
-compatibility_packages:
+unsupported_packages:
   - java_package: com.yss.cloud.dto.response
-    status: legacy-or-compatibility
+    status: unsupported
     use_for_new_contracts: false
-    policy: do-not-introduce-in-new-contracts
+    policy: reject-in-new-contracts-no-auto-migration
 
 common_response:
   schema_name: YssResultMeta

package/template/.hermes/skills/yss-exception/SKILL.md

@@ -24,6 +24,7 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 3. Use `ExceptionFactory` and `ResultErrorCode` conventions instead of ad-hoc runtime exceptions when creating YSS component errors.
 4. Check `YssGlobalExceptionProperties` when global exception output/logging behavior is configurable.
 5. Keep logging semantics aligned: business exceptions usually do not require error-stack logging; system/unknown exceptions usually do.
+6. In the `target-domain-model` profile, Domain owns stable error meaning and parameters but does not depend directly on YSS `BizException` or HTTP. Translate at the Web boundary after verifying the component handler precedence.
 
 ## Current Source Behavior
 
@@ -47,6 +48,7 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 - Stack traces are preserved for unknown/system failures.
 - Retry guidance matches exception type.
 - Known system failures use `ExceptionFactory.sysException(..., cause)`; Application code does not replace them with ad-hoc `RuntimeException`.
+- Endpoint contract tests cover business, known-system, and unknown/runtime failures; unknown public messages never expose `getLocalizedMessage()`.
 
 ## Do Not
 

package/template/.hermes/skills/yss-formily/SKILL.md

@@ -15,7 +15,7 @@ description: 指导在 YSS UI 业务页面中正确使用 @yss-ui/components 的
 
 - 页面只有普通列表，不涉及表单：使用 `../page-list-module/SKILL.md`。
 - 只处理表格操作列或分页：使用 `../ytable-usage/SKILL.md`。
-- 组件库内部改造 YFormily 源码：使用 `../component-development/SKILL.md`。
+- 组件库内部改造 YFormily 源码：回到 yss-ui 源仓库，使用其 `categories.library` 维护流程；该类 skill 不随业务模板分发。
 
 ## 文档检索
 

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

@@ -16,7 +16,7 @@ description: 用于 YSS MyBatis 与 MyBatis-Plus 持久层规范、配置和排
 
 ## 工作方式
 
-1. 先确认项目使用的是通用 MyBatis 还是 MyBatis-Plus。
+1. 先读取批准的 `persistence_profile`。新 DDD scaffold 当前只支持 `mybatis-plus`；普通 MyBatis 必须有独立 fixture 和批准 Profile，禁止自动猜测或混用。
 2. 涉及真实类名、配置项、模块依赖或排障时，先读 `references/source-index.md`，再定位源码或文档。
 3. 先复用现有基类与配置，不手搓新的基础设施。
 4. 涉及分页时，先验证 `PageQuery` 传递链路和拦截器是否生效。
@@ -35,7 +35,7 @@ description: 用于 YSS MyBatis 与 MyBatis-Plus 持久层规范、配置和排
 - MP 模式优先继承项目既有的 `BasePlusRepository`
 - 批量导入优先使用真正的 SQL 级批量方法，不要默认循环单条插入
 - 多数据源问题优先先看配置和扫描范围，再怀疑业务代码
-- 分页查询优先沿用 `PageQuery` 传递链路，不要在 Repository 内临时发明分页参数。
+- 分页查询经 Application Query Port 进入 Infrastructure；可以在适配层转换为组件所需 `PageQuery`，但不得把 `PageQuery` 带入 Domain Gateway，也不得在 Repository 内临时发明分页参数。
 - 生成或重构持久层时，先看当前模块已有 Repository/Mapper 命名、包路径、XML 位置。
 
 ## 检查清单

package/template/.hermes/skills/yss-page-module-development/SKILL.md

@@ -5,6 +5,8 @@ description: 指导创建标准 Vue 3 YSS 业务页面模块，覆盖 CRUD、列
 
 # YSS Page Module Development
 
+> **核心路由说明**：新页面生成开发请优先以 `../yss-ui-business-page-generation/SKILL.md` 为统一主规则与硬约束。当前会话可用 yss-ui MCP 时，生成业务代码前必须先调用 `get_codegen_rules`。本技能作为兼容旧触发名与流程编排入口保留。
+
 Use this skill when the user asks for a business page, CRUD module, tree-table page, detail page, or any standard YSS Vue 3 page module.
 
 ## Authoritative Docs And Skill Boundaries

package/template/.hermes/skills/yss-product-lifecycle/SKILL.md

@@ -16,6 +16,8 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 
 Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为显式兼容入口；默认路径是本 skill 持有的原生工作单元，由本编排器创建正式资产、维护状态并在会签门禁暂停（级别见数字人角色注册表）。兼容入口不得自动调用它们或代替其创建正式资产；Matt 只导航，不得写生命周期资产或改变门禁/Ticket 状态；任何写入前回交本编排器。
 
+技能调用先消费 `docs/agents/yss-skill-registry.yaml` 的 `invocation_contract`：它只约束调用模式、触发/排除条件、主要输出和依赖，不替代生命周期证据或门禁。进入实现后，Slice Contract 的 `common.context_plan` 只加载当前切片的最小充分上下文；缺失权威上下文必须 `blocked` 或回 Router，不得猜测补齐。质量标准由 `engineering-baseline` 一次定义并由切片、Execution Result、审查和发布复用；命中高风险影响时在途记录 Doubt-Driven 主张、反证、证据和残余风险。Wayfinder 仅作为超长或决策前沿不清晰工作的可选 Discovery → Spec 规划模式，完成后回到 `handoff → to-spec`，不改变生命周期状态。
+
 ## 不可裁剪的主链
 
 入口分诊 → Discovery → Spec / 功能架构 → 产品设计 → 系统 / 数据架构与工程契约 → Ticket 正式化 → 垂直切片实现（前后端 TDD）→ 验证 / 发布 / 复盘。

package/template/.hermes/skills/yss-product-lifecycle/references/matt-yss-adapter.md

@@ -19,7 +19,7 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 | 通用入口 | `ask-matt` | 检测到 YSS 后由本编排器最终裁决 |
 | 需求澄清 | `grill-with-docs`（用户显式）或 `grilling`、`domain-modeling`（生命周期原语） | 按退出判定检查未决项和回流 |
 | 信息在其他人手中 | `to-questionnaire` | 使用 `external-input-required` 暂停；答案回流后记录 response、重新分类影响面，再进入 `grill-with-docs` 或 `to-spec` |
-| 大型模糊工作 | `wayfinder` | map 真正完成后 `handoff → to-spec` |
+| 大型模糊工作 | `wayfinder`（可选） | 仅在跨会话 / 跨 Agent 或 frontier 不清晰时启用；map 真正完成后 `handoff → to-spec` |
 | 技术事实 | `research` | 一手资料回填 Spec/OpenAPI/架构/ADR |
 | runnable 问题 | `prototype` | 生成单文件可分享 HTML，保留 `prototype/<name>` 分支作为主来源；必须 source/return handoff 和结论回填，不得替代阶段 4 的低保真评审、Ant Design v6 高保真 HTML、AntD CLI 证据和用户确认 |
 | Spec 综合 | 原生 `work-unit.spec-synthesis`；`to-spec`（用户显式兼容） | 初稿进入 `ready-for-human`，不得直接实现 |
@@ -76,7 +76,7 @@ Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-
 
 ## Review 候选与 Git 授权
 
-YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、`spec_ref`、`ticket_ref`、`slice_contract_ref`、`build_architecture_checklist_ref` 和 `yss_execution_result_refs`，并满足 `orchestration-contract.yaml.review_input.manifest_required_by_mode`。Standards 还必须编译 `review_standards_route`：合同 `required_skills`、影响面专项检查输入、报告模板与 `finding_disposition`；机器检查按 `run_if_present` 执行。`committed` 审查 merge-base 到不可变 `HEAD`；`worktree` 一次捕获 merge-base 到 working tree 的 committed、staged、unstaged 和 untracked 内容，使用 `yss-worktree-candidate-v1` 规定的 raw path、uint64 big-endian 长度、tracked/untracked record 和不支持条目阻断规则计算 SHA-256，让两个 Reviewer 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空、专项覆盖缺失、未关闭 mandatory `violation`、适用行空白或摘要变化时返回 `blocked`，不能缩小审查范围、另起通用审查 skill、由审查者改实现，或合并不同候选的结论。`violation` 类 finding 交实现者在原合同路径修复后全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 Router。
+YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、`spec_ref`、`ticket_ref`、`slice_contract_ref`、`build_architecture_checklist_ref` 和 `yss_execution_result_refs`，并满足 `orchestration-contract.yaml.review_input.manifest_required_by_mode`。Standards 还必须编译 `review_standards_route`：合同 `required_skills`、影响面专项检查输入、报告模板与 `finding_disposition`；机器检查按 `run_if_present` 执行。质量标准只从 `engineering-baseline` 引用，禁止在 review input 或切片中另起一份。命中高风险影响时，review input 还要引用 Doubt-Driven 主张 / 反证记录；缺少反证或残余风险未处理时返回 `blocked`。`committed` 审查 merge-base 到不可变 `HEAD`；`worktree` 一次捕获 merge-base 到 working tree 的 committed、staged、unstaged 和 untracked 内容，使用 `yss-worktree-candidate-v1` 规定的 raw path、uint64 big-endian 长度、tracked/untracked record 和不支持条目阻断规则计算 SHA-256，让两个 Reviewer 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空、专项覆盖缺失、未关闭 mandatory `violation`、适用行空白或摘要变化时返回 `blocked`，不能缩小审查范围、另起通用审查 skill、由审查者改实现，或合并不同候选的结论。`violation` 类 finding 交实现者在原合同路径修复后全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 Router。
 
 Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。`git-submodule` 还必须按仓授权、禁止 detached HEAD 提交，并先推子仓再更新父仓 gitlink。
 

package/template/.hermes/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -181,7 +181,7 @@ matt_invocation_boundary:
 
 skill_source_contract:
   lock_version: 3
-  source_revisions_required: [mattpocock/skills]
+  source_revisions_required: [mattpocock/skills, iloveZzz/yss-ui]
   adaptation_ref_required_when_effective_diff: true
   retired_shared_skills: [batch-grill-me, product-design-prototype, yss-dictionary, yss-jdbc, yss-log, yss-taskflow, yss-backend-scaffold-application, yss-backend-scaffold-domain, yss-backend-scaffold-infrastructure, yss-backend-scaffold-web]
 
@@ -277,11 +277,12 @@ work_unit_routes:
   work-unit.slice-implementation:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
     primary_skill: yss-router
-    supporting_skills: [tdd, yss-ui, yss-page-module-development]
+    supporting_skills: [tdd, yss-ui, yss-ui-business-page-generation, yss-page-module-development]
     compatibility: {source: mattpocock/skills, skill: implement, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
-    skills: [tdd, yss-router, yss-ui, yss-page-module-development]
+    skills: [tdd, yss-router, yss-ui, yss-ui-business-page-generation, yss-page-module-development]
     frontend_route:
       primary_skill: yss-ui
+      page_generation_skill: yss-ui-business-page-generation
       page_orchestration_skill: yss-page-module-development
       conditional_skills:
         api_impact: [yss-api-integration]
@@ -542,21 +543,47 @@ backend_scaffold:
   baseline_skill: yss-backend-scaffold-parent
   tdd_mode: controlled-generation
   contract_schema:
-    schema_version: 1
-    required: [contract_id, contract_version, slice_id, status, router_draft_ref, lifecycle_approval_ref, persisted_ref, current_version, implementation_repository, backend_repository, scaffold_status, target_git_url_or_output_dir, allowed_write_paths, expected_evidence_files, verification_commands, approval, work_unit, overwrite_policy]
+    schema_version: 2
+    identity: service-engineering-baseline
+    required: [contract_id, contract_version, scaffold_request_id, status, router_draft_ref, lifecycle_approval_ref, persisted_ref, current_version, implementation_repository, backend_repository, scaffold_status, project_name, target_output_dir, base_package, maven_coordinates, profiles, allowed_write_paths, expected_evidence_files, verification_commands, approval, work_unit, generation_policy]
     status_by_owner:
       router: [draft, ready-for-lifecycle-review, blocked]
       lifecycle: [approved, stale, blocked]
     approval:
       required: [approval_ref, approver, persisted_ref, current_version]
-    overwrite_policy:
-      required: [force_allowed, overwrite_scope, rollback_ref]
-  required_inputs: [implementation_repository, backend_repository, scaffold_status, scaffold_target_confirmed, target_git_url_or_output_dir, project_name, base_package, database, scaffold_contract_file, scaffold_contract_draft, scaffold_contract_id, scaffold_contract_version, scaffold_contract_status, scaffold_contract_approved, scaffold_contract_router_draft_ref, scaffold_contract_lifecycle_approval_ref, scaffold_contract_persisted, scaffold_contract_persisted_ref, scaffold_contract_current_version]
-  required_evidence: [generator_inputs, expected_files, scaffold_generation_manifest, generated_project_structure, generation_execution_result, verification_execution_result, ./mvnw_validate, ./mvnw_test, ./mvnw_package, yss_skill_execution_result]
+    generation_policy:
+      required: [mode, existing_target, old_project_migration, template_upgrade]
+      mode: initialize-only
+      existing_target: unsupported
+      old_project_migration: unsupported
+      template_upgrade: unsupported
+    maven_coordinates:
+      required: [group_id, project_version, parent, yss_components_version]
+      parent_required: [group_id, artifact_id, version]
+      yss_components_version: 2.0.0-SNAPSHOT
+    profiles:
+      required: [architecture, persistence, database, platform, validation_namespace, dto_placement, repository]
+      supported_initial:
+        architecture: target-domain-model
+        persistence: mybatis-plus
+        database: mysql
+        platform: spring-boot-2.7-jdk8
+        validation_namespace: javax
+        dto_placement: web
+        repository: yss-internal
+      unsupported: [old-architecture-profile, client-in-domain, mybatis, spring-boot-3, jakarta, separate-client-module]
+    unsupported_inputs:
+      schema_v1: reject-no-auto-upgrade
+      slice_id: forbidden-as-scaffold-identity
+      existing_project: reject-no-scaffold-migration
+  required_inputs: [implementation_repository, backend_repository, scaffold_status, scaffold_target_confirmed, scaffold_request_id, target_output_dir, project_name, base_package, maven_group_id, project_version, parent_group_id, parent_artifact_id, parent_version, yss_components_version, architecture_profile, persistence_profile, database, platform_profile, validation_namespace, dto_placement, repository_profile, scaffold_contract_file, scaffold_contract_draft, scaffold_contract_id, scaffold_contract_version, scaffold_contract_status, scaffold_contract_approved, scaffold_contract_router_draft_ref, scaffold_contract_lifecycle_approval_ref, scaffold_contract_persisted, scaffold_contract_persisted_ref, scaffold_contract_current_version]
+  required_evidence: [generator_inputs, expected_files, scaffold_generation_manifest_v2, generated_project_structure, generation_execution_result, verification_execution_result, architecture_rules, ./mvnw_validate, ./mvnw_test, ./mvnw_package, yss_skill_execution_result]
   generation_options:
     with_example: false
     force: forbidden-by-default
-    force_requires: [contract_file, contract_id, contract_version, approval_ref, router_draft_ref, persisted_ref, overwrite_scope, rollback_ref]
+    regeneration: unsupported
+    template_upgrade: unsupported
+    old_project_migration: unsupported-separate-architecture-modernization-initiative
   forbidden_generation: [business_rules, state_machine, permission, transaction, complex_query, error_mapping, user_visible_behavior, business_example_crud, unapproved_force_overwrite]
   after_generation: [yss-backend-scaffold-parent, yss-router]
   existing_or_initialized: [baseline_evidence, wrapper_verification, yss_router_contract_recompile]
@@ -564,7 +591,11 @@ backend_scaffold:
     commands: ["./mvnw validate", "./mvnw test", "./mvnw package"]
     requires_execution: true
     printed_commands_are_not_evidence: true
-    evidence: [command, exit_code, duration_ms, stdout_ref, stderr_ref, executed_at]
+    completion_levels: [generated, empty-scaffold-verified, first-slice-verified]
+    downstream_readiness_claim_requires: first-slice-verified
+    evidence: [preflight, command, exit_code, failure_category, duration_ms, stdout_ref, stderr_ref, executed_at]
+    completion_requires: [validate_passed, test_passed, package_passed]
+    failure_categories: [repository-access, project-model, compilation, bootstrap-entrypoint, test-failure, packaging, maven-execution, verification-preflight]
     failure_action: blocked
   failure_action: blocked
 
@@ -648,8 +679,49 @@ release_readiness:
 wayfinder_completion:
   required: [no_open_children, no_open_blocked_or_claimed_children, no_fog, destination_clear]
 
+wayfinder_mode:
+  optional: true
+  enable_when:
+    - multi-session-or-multi-agent-work
+    - unclear-decision-frontier
+    - cross-domain-dependency-map-needed
+  lifecycle_position: discovery-to-spec-planning
+  completion_route: wayfinder -> handoff -> to-spec
+  does_not_replace: [lifecycle-gates, spec-baseline, ticket-formalization]
+  forbidden_state_mutations: [ready-for-agent, gate-approval, ticket-role]
+  template_source_use: only-when-template-evolution-is-long-running
+
+context_engineering:
+  contract_field: slice_contract.common.context_plan
+  required_context: [CONTEXT.md, approved-spec, current-slice-contract, applicable-adr-or-baseline]
+  on_demand_context: [specialist-references, implementation-repository-files, historical-evidence]
+  stop_rule: minimal-sufficient-evidence
+  missing_context_action: [blocked, reroute]
+  numeric_token_budget: not-required
+
+doubt_driven_review:
+  applies_when:
+    - api-schema-impact
+    - database-schema-impact
+    - cross-repo-contract
+    - release-or-rollback
+    - authentication-authorization-tenant-or-sensitive-data-behavior
+    - lifecycle-or-generation-semantics
+  required: [claim, counterclaim, evidence_refs, residual_risks, reviewer_ref]
+  record_in: [decision-record, architecture-review, contract-review, release-review]
+  blocking_when: [missing-counterclaim, insufficient-evidence, unresolved-residual-risk]
+  ordinary-low-risk_changes: not-required
+  no_new_lifecycle_stage: true
+
+quality_baseline_reuse:
+  source: artifact.engineering-baseline
+  applies_to: project-instance
+  consumers: [slice-implementation-contract, yss-skill-execution-result, code-review, release]
+  constraint_results_field: required
+  redefinition: forbidden
+
 ready_for_agent:
-  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, predecessor_work_unit, ticket_decomposition_result_ref, ticket_decomposition_result_status, vertical_slice_ticket_ref, vertical_slice_ticket_role, vertical_slice_ticket_kind, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied, frontend_implementation_plan_if_ui_impact]
+  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, context_plan, quality_baseline_ref, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, predecessor_work_unit, ticket_decomposition_result_ref, ticket_decomposition_result_status, vertical_slice_ticket_ref, vertical_slice_ticket_role, vertical_slice_ticket_kind, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied, frontend_implementation_plan_if_ui_impact]
   ticket_formalization_validator: scripts/lib/lifecycle-transition.mjs
   requires_vertical_slice_ticket: true
   parent_ticket_as_implementation_ref: forbidden