create-yss-spec 2.2.9 → 3.0.0

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

@@ -172,8 +172,8 @@ task_package:
 matt_invocation_boundary:
   user_invoked_skills: [ask-matt, grill-me, grill-with-docs, handoff, implement, improve-codebase-architecture, loop-me, setup-matt-pocock-skills, setup-ts-deep-modules, teach, to-questionnaire, to-spec, to-tickets, triage, wait-what, wayfinder, writing-beats, writing-fragments, writing-shape]
   lifecycle_managed_user_entries: [setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, implement]
-  model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, migrate-to-shoehorn, prototype, research, resolving-merge-conflicts, scaffold-exercises, setup-pre-commit, tdd, writing-for-agents]
-  lifecycle_allowed_model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, prototype, research, tdd]
+  model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, migrate-to-shoehorn, prototype, resolving-merge-conflicts, scaffold-exercises, setup-pre-commit, tdd, writing-for-agents, yss-research]
+  lifecycle_allowed_model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, prototype, tdd, yss-research]
   lifecycle_may_invoke_user_invoked: false
   formal_artifact_owner: explicit-user-entry
   continuous_orchestration: compatibility-prepare-and-validate-only
@@ -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]
 
@@ -199,9 +199,9 @@ work_unit_routes:
   work-unit.discovery-opportunity:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
     primary_skill: yss-product-lifecycle
-    supporting_skills: [competitive-intelligence, research]
-    skills: [competitive-intelligence, research]
-    route_by: {market_or_competitor_fact: competitive-intelligence, technical_or_standard_fact: research, no_external_fact: yss-product-lifecycle}
+    supporting_skills: [competitive-intelligence, yss-research]
+    skills: [competitive-intelligence, yss-research]
+    route_by: {market_or_competitor_fact: competitive-intelligence, technical_or_standard_fact: yss-research:technical-evidence, strategy_fact: yss-research:strategy-evidence, no_external_fact: yss-product-lifecycle}
     applies_when: opportunity_or_external_fact_requires_validation
     not_applicable_reason: no_external_fact
   work-unit.discovery-requirements:
@@ -214,16 +214,18 @@ work_unit_routes:
   work-unit.domain-strategy-design:
     native: {source: yss-product-lifecycle, skill: yss-stage-decision, invocation_mode: model-invoked}
     primary_skill: yss-stage-decision
-    supporting_skills: [domain-modeling, research, grilling]
-    skills: [yss-stage-decision, domain-modeling, research, grilling]
+    supporting_skills: [domain-modeling, yss-research, grilling]
+    skills: [yss-stage-decision, domain-modeling, yss-research, grilling]
+    research_contract: {profile: strategy-evidence, mode_before_gate: evidence-audited, artifact_owner: yss-research, downstream_owner: yss-stage-decision}
     human_gate: domain-strategy-approved
     applies_when: domain_boundary_or_language_or_core_rule_impact
     not_applicable_reason: no_domain_strategy_impact
   work-unit.stage-decision:
     native: {source: yss-product-lifecycle, skill: yss-stage-decision, invocation_mode: model-invoked}
     primary_skill: yss-stage-decision
-    supporting_skills: [domain-modeling]
-    skills: [yss-stage-decision, domain-modeling]
+    supporting_skills: [domain-modeling, yss-research]
+    skills: [yss-stage-decision, domain-modeling, yss-research]
+    research_contract: {profile: strategy-evidence, mode_before_gate: evidence-audited, artifact_owner: yss-research, downstream_owner: yss-stage-decision}
     human_gate: stage-decision-package-approved
     applies_when: discovery_to_spec_requires_stable_decision_package
     not_applicable_reason: existing_approved_stage_decision_current
@@ -277,11 +279,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]
@@ -419,7 +422,7 @@ transition_graph:
 grill_exit:
   required: [frontier_empty, facts_resolved_or_routed, decisions_confirmed, shared_understanding_confirmed, no_unresolved_runnable_blocker]
   facts_resolved_or_routed:
-    technical_fact: research
+    technical_fact: yss-research
     runnable_question: handoff-prototype-handoff
     external_decision: external-input-required
   user_confirmation_required: true
@@ -542,21 +545,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 +593,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
 

package/template/.agents/skills/yss-product-lifecycle/references/orchestration.md

@@ -53,7 +53,7 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 
 - `work-unit.technical-analysis` 命中聚合、状态机、不变量、一致性、Domain Event、Gateway 或持久化映射影响时，先调度 `yss-tactical-design` 完成 Tactical DDD Check；默认嵌入系统概要设计 / 数据架构，复杂场景才生成 `artifact.tactical-design`。无领域影响记录 `not-applicable`。该 skill 只返回设计合同和验证结果，批准仍由生命周期编排器维护，发现 `stale`、`drift` 或 `new_impacts` 时不得继续 Ticket 正式化。
 
-- `work-unit.discovery-requirements` 实际调用 `grilling` 和 `domain-modeling`；`work-unit.discovery-opportunity` 按事实类型路由 `competitive-intelligence` 或 `research`。生命周期原生工作单元默认负责 Spec、Ticket 和实现资产；`to-spec`、`to-tickets`、`implement` 仅保留为显式兼容入口，结果必须回交生命周期验收。
+- `work-unit.discovery-requirements` 实际调用 `grilling` 和 `domain-modeling`；`work-unit.discovery-opportunity` 按事实类型路由 `competitive-intelligence` 或 `yss-research`。`yss-research:quick` 只用于探索；外部证据进入领域战略、阶段决策或其他生命周期批准输入前必须升级为 `evidence-audited`。生命周期原生工作单元默认负责 Spec、Ticket 和实现资产；`to-spec`、`to-tickets`、`implement` 仅保留为显式兼容入口，结果必须回交生命周期验收。
 - 原生 `work-unit.ticket-decomposition` 只能在 OpenAPI Freeze 或无 API 影响记录后创建垂直切片，初始 Ticket 状态统一为 `ready-for-human`；生命周期复算完整公式后才能提升 `ready-for-agent`。该工作单元必须返回 `ticket_decomposition_result_ref` 和垂直切片引用，并作为实现的必经前置证据。
 - 原生 `work-unit.slice-implementation` 必须在生命周期批准并持久化 Slice Implementation Contract 和 Build Architecture Checklist 后执行；用户显式 `implement` 仍走兼容入口，不得绕过生命周期。
 - `Workflow Execution Result.next_route` 必须通过生命周期转换校验；Spec、原型和技术分析不得直接跳转到 `work-unit.slice-implementation`，只能先进入 `work-unit.ticket-decomposition`。
@@ -105,7 +105,7 @@ Decision ticket 产生决策，不是实现切片，不得标记 `ready-for-agen
 
 ## `grill-with-docs` 退出判定
 
-进入 `to-spec` 前必须区分已确认项与未决项，并确认用户、问题、MVP、非目标、成功标准、术语/ADR 候选和测试 seam。事实问题走 `research`；需 runnable 反馈的问题走 `handoff → prototype → handoff`。存在未回流 blocker 时不得进入 Spec baseline。
+进入 `to-spec` 前必须区分已确认项与未决项，并确认用户、问题、MVP、非目标、成功标准、术语/ADR 候选和测试 seam。事实问题走 `yss-research`；需 runnable 反馈的问题走 `handoff → prototype → handoff`。存在未回流 blocker 时不得进入 Spec baseline。
 
 Prototype 回流必须有可核验证据：来源 handoff、prototype 资产或运行记录、结论、被更新的 Spec/设计/ADR/Ticket 引用、剩余未决项和返回 handoff。仅在对话中声称“已验证”不算回流完成。
 

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

@@ -1,6 +1,6 @@
 ---
 name: yss-repository
-description: Use when generating or refactoring YSS persistence models, BaseRepository/MyBatis repositories, MapStruct convertors, Domain Gateway implementations, or metadata/DDL-backed queries.
+description: Use when generating or refactoring YSS Infrastructure persistence models, repositories, MapStruct convertors, Domain Gateway implementations, or metadata/DDL-backed queries.
 ---
 
 # yss-repository
@@ -21,31 +21,35 @@ description: Use when generating or refactoring YSS persistence models, BaseRepo
 
 ## 工作方式
 
-1. 先确认输入来源：领域模型、metadata、数据库表、DDL。
-2. 探测持久化 profile：新 DDD 默认 `PO <-> Domain Model`；legacy YSS 常见 `Entity + BaseRepository + GatewayImpl`。沿用现有工程命名，不混用两套模型。
+1. 先确认批准且版本当前的 Slice Implementation Contract、数据架构、领域模型和既有 Domain Gateway/Application Query Port；缺任一前置项即返回 `blocked` / `new_impacts`，不得从 DDL 反向猜测领域端口。
+2. 确认持久化 Profile 为 `mybatis-plus` 与 `PO <-> Domain Model`；`Entity + BaseRepository + DTO/VO GatewayImpl` 等旧架构对新脚手架为 `unsupported`。
 3. 如果 metadata 不完整，先补齐 metadata、数据库表结构或 DDL 输入。
-4. 涉及 POJO 字段、getter/setter、constructor、builder 或日志时，必须加载并遵守 `lombok`。
-5. 涉及持久化模型与 Domain/VO/CMD 转换时，必须加载并遵守 `mapstruct`。
-6. 生成代码时严格保持 Domain 与 Infrastructure 分层边界。
-7. 默认先生成基础 CRUD 骨架，把复杂查询留给手工实现。
+4. 加载并遵守固定 Profile 的 `yss-mybatis`，不得在本 skill 内维护第二套 Mapper、分页或 SQL 安全规则。
+5. 涉及 POJO 字段、getter/setter、constructor、builder 或日志时，必须加载并遵守 `lombok`。
+6. 涉及持久化模型与 Domain/Application Result 转换时，必须加载并遵守 `mapstruct`；Infrastructure 不生成 Web VO/CMD 转换。
+7. 生成代码时严格保持 Domain 与 Infrastructure 分层边界。
+8. 默认先生成基础 CRUD 骨架，把复杂查询留给手工实现。
 
 ## 产物范围
 
-- `domain/{segment}/gateway/*Gateway.java`
-- `repository/entity/*PO.java`（legacy profile 沿用 `*Entity.java`）
-- `repository/*Repository.java`
-- `repository/convertor/*Convertor.java`
-- `repository/gateway/impl/*GatewayImpl.java`
+- `infrastructure/persistence/po/*PO.java`
+- `infrastructure/persistence/repository/*Repository.java`
+- `infrastructure/persistence/convertor/*Convertor.java`
+- `infrastructure/persistence/gateway/*GatewayImpl.java`
+- `infrastructure/query/adapter/*QueryAdapter.java`（实现 Application Query Port）
+- `infrastructure/query/convertor/*QueryConvertor.java`
 
 ## 约束
 
 - Domain 不依赖 Infrastructure。
 - Gateway 定义在 Domain，实现放在 Infrastructure。
+- `yss-repository` 不创建或改写 Domain Gateway interface；缺少或需要改变 Gateway 时返回 `new_impacts`，由 Router 回到 `yss-domain` / `yss-tactical-design`。
+- Domain Gateway 只交换 Domain Model、领域值和标识；分页、列表和读模型走 Application Query Port，禁止返回 Web VO 或把 `PageQuery` 带入 Domain。
 - PO / Domain Model 等 POJO 样板代码优先使用 Lombok；不要成片手写 getter/setter、constructor、builder 或 logger。
-- Convertor 必须优先使用 MapStruct；禁止 `BeanUtils.copyProperties`、反射式通用拷贝和重复手写字段赋值，除非实现合同记录受控例外、测试和 review 证据。
+- Convertor 必须优先使用 `@Mapper(componentModel = "spring")` 和构造器注入；禁止静态 `INSTANCE`、`BeanUtils.copyProperties`、反射式通用拷贝和重复手写字段赋值，除非实现合同记录受控例外、测试和 review 证据。
 - MapStruct 与 Lombok 同时使用时，必须确认注解处理器顺序和 `lombok-mapstruct-binding` 配置；构建命令使用项目根目录 `./mvnw ...`。
 - 逻辑删除、审计字段、主键策略要显式处理，不要隐式略过。
-- 事务放在批准的 Application 用例边界；legacy GatewayImpl 已有事务时先记录并测试迁移影响，不重复嵌套制造假边界。
+- 事务放在批准的 Application 用例边界；检测到旧 GatewayImpl 事务布局时返回 `unsupported`，不在 scaffold 链路内迁移。
 
 ## 质量门禁
 
@@ -53,7 +57,7 @@ description: Use when generating or refactoring YSS persistence models, BaseRepo
 - 命名、包路径、注解要与工程现有规范一致。
 - Convertor 必须有 MapStruct 接口 / 抽象类、生成实现可编译，必要时补 mapper 单测或覆盖核心字段转换的行为测试。
 - POJO 使用 Lombok 时不得引入 `@Data` 造成实体 equals / toString 风险；有关系字段、敏感字段或懒加载字段时按 `lombok` skill 排除。
-- 遇到无法自动判断的字段或规则时，写 TODO 或向用户说明，不要假装已确认。
+- 遇到无法自动判断的字段、映射或查询规则时返回 `new_impacts` / `drift` 并暂停，不要把 TODO 当作已完成实现。
 
 ## 协同顺序
 

package/template/.agents/skills/yss-repository/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS Repository"
-  short_description: "Repository、Convertor 与 gateway 实现规范"
-  default_prompt: "Use $yss-repository to generate or refactor YSS repository, convertor, and gateway implementation code."
+  short_description: "Infrastructure Repository、Mapper、Convertor 与端口实现规范"
+  default_prompt: "Use $yss-repository to implement Infrastructure persistence and query adapters against existing Domain Gateway and Application Query Port interfaces without creating domain contracts."

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

@@ -1,192 +1,107 @@
-本 Skill 提供了 YSS **Infrastructure (基础设施层)** 的通用开发规范。Infrastructure 层负责实现 Domain 层定义的网关接口，处理数据持久化、外部服务调用和配置管理。
+# YSS Infrastructure Target Profile 指南
 
-## 1. 核心职责 (Core Responsibilities)
+本指南只定义 `target-domain-model + mybatis-plus`。历史 `Entity + DTO/VO Gateway` 为 `unsupported`，不存在旧架构 Profile。
 
-- **实现网关接口 (Gateway Implementation)**: 实现 Domain 层定义的 `Gateway` 接口。
-- **数据持久化 (Persistence)**: 定义 `Repository` 接口和 `PO` (Persistent Object) 实体，操作数据库。
-- **对象转换 (Conversion)**: 使用 MapStruct 实现 PO 与 Domain Model/DTO 之间的转换。
-- **外部适配 (External Adapters)**: 集成外部服务 (如文件存储、消息队列)。
+## 1. 职责
 
-## 2. 代码结构 (Code Structure)
+- 实现既有 Domain Gateway，负责 Aggregate 持久化；不创建或改写 Gateway interface。
+- 实现 Application Query Port，负责分页、列表和读模型。
+- 定义 PO、MyBatis-Plus Repository/Mapper、XML 和数据源适配。
+- 通过 Spring MapStruct Bean 完成 `PO <-> Domain Model`、`PO -> Application Result`。
 
-```
-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(...)`。
+Infrastructure 不拥有业务事务边界，不向 Application/Web 暴露 PO，也不直接生成 HTTP VO。
 
-### 3.4 对象转换 (Convertor)
+## 2. 包结构
 
-- **工具**: MapStruct。
-- **位置**: `com.yss.{module}.repository.convertor`。
-- **命名**: `DomainName` + `Convertor` (e.g., `QualityTemplateConvertor`)。
-- **规范**: 定义 `INSTANCE` 常量，使用 `Mappers.getMapper(...)` 获取实例。
+```text
+{base_package}.infrastructure
+├── persistence
+│   ├── po
+│   ├── repository
+│   ├── convertor
+│   └── gateway
+└── query
+    ├── adapter
+    └── convertor
+```
 
-## 4. 详细案例 (Detailed Examples)
+新脚手架固定使用 `{base_package}.infrastructure`。已有 `{base_package}.repository` 工程不由 scaffold 改写；需要现代化时单独立项。
 
-### 4.1 Persistent Object (PO)
+## 3. Domain Gateway 实现
 
 ```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;
+@Repository
+@RequiredArgsConstructor
+public class QualityTemplateGatewayImpl implements QualityTemplateGateway {
+    private final QualityTemplateRepository repository;
+    private final QualityTemplatePersistenceConvertor convertor;
 
-    @TableField("template_code")
-    private String templateCode;
+    @Override
+    public Optional<QualityTemplate> findById(QualityTemplateId id) {
+        return Optional.ofNullable(repository.selectById(id.value()))
+                .map(convertor::toDomain);
+    }
 
-    @TableField("status")
-    private Integer status;
+    @Override
+    public void save(QualityTemplate aggregate) {
+        repository.insertOrUpdate(convertor.toPO(aggregate));
+    }
 }
 ```
 
-### 4.2 Repository Interface
+GatewayImpl 不接收 Web Cmd/Query，不返回 VO/PageResult，不声明新的业务事务。
 
-```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. Query Port 实现
 
-### 4.3 Gateway Implementation
+分页/列表属于 Application Query Port：
 
 ```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;
+public class QualityTemplateQueryAdapter implements QualityTemplateQueryPort {
+    private final QualityTemplateRepository repository;
+    private final QualityTemplateQueryConvertor convertor;
 
     @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()
-        );
+    public PageResult<QualityTemplateResult> page(QualityTemplatePageQuery query) {
+        // orderBy/groupBy 必须先映射到批准列白名单，再构造 MyBatis 条件。
+        return convertor.toResultPage(repository.selectPage(...));
     }
 }
 ```
 
-### 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;
+`PageQuery` 可以在 Web/Application/Infrastructure 协作链使用，但不得进入 Domain。`orderBy` / `groupBy` 禁止直接拼接 SQL。
 
-import java.util.List;
+## 5. PO 与 Repository
 
-@Mapper
-public interface QualityTemplateConvertor {
-    QualityTemplateConvertor INSTANCE = Mappers.getMapper(QualityTemplateConvertor.class);
+- Target Profile 使用 `*PO`；旧式 `*Entity` 布局为 `unsupported`。
+- PO 默认使用最小 Lombok 注解，不无条件使用 `@Data`。
+- 当前实现继承项目既有 `BasePlusRepository<PO>`；普通 MyBatis 为 `unsupported`。
+- Mapper XML 位于项目既有扫描路径；扫描包和 XML 路径必须由集成测试证明。
 
-    QualityTemplateVO toQualityTemplateVO(QualityTemplatePO po);
+## 6. MapStruct
 
-    List<QualityTemplateVO> toQualityTemplateVOList(List<QualityTemplatePO> pos);
+```java
+@Mapper(componentModel = "spring")
+public interface QualityTemplatePersistenceConvertor {
+    QualityTemplate toDomain(QualityTemplatePO source);
+    QualityTemplatePO toPO(QualityTemplate source);
 }
 ```
 
-## 5. 注意事项 (Notes)
+- 禁止 `INSTANCE = Mappers.getMapper(...)`。
+- Convertor 使用构造器注入。
+- 父 POM 必须配置 `mapstruct-processor`、Lombok 和 `lombok-mapstruct-binding`。
+- 验证必须编译生成实现，不能只检查接口文本。
+
+## 7. 验证
 
-1.  **AuditableEntity**: 推荐业务 PO 继承此基类，以便自动维护审计信息。
-2.  **Lombok 使用**: 使用 `@RequiredArgsConstructor` 进行构造器注入是推荐的最佳实践。
-3.  **Wrapper 使用**: 优先使用 `Wrappers.lambdaQuery()` 而不是字符串列名，以提高重构安全性。
-4.  **分页工具**: 使用 `PageUtil` 统一处理分页参数，避免手动计算 offset。
+- Domain Gateway：保存后可通过 Gateway seam 重新加载等价 Aggregate。
+- Query Port：分页、total、排序白名单和空结果。
+- Mapper/Repository：实际 MyBatis-Plus/H2 或批准数据库 fixture。
+- Architecture：Infrastructure 可以依赖 Application/Domain；反向依赖必须失败。
+- 使用项目根 `./mvnw test/package` 留证。
 
-## 6. 阶段 7 合同
+## 8. 旧架构边界
 
-- 前置条件是批准的数据架构、Repository 策略和 Slice Contract。
-- PO/Repository/Convertor 骨架可受控生成；复杂查询、分页语义、数据源、事务、迁移和并发使用 `behavior-tdd`。
-- 返回统一 `YSS Skill Execution Result`，证据包含实际文件、集成测试、MapStruct/Lombok 配置和 `./mvnw ...` 结果。
+检测到 Repository 直接接收 client Query、返回 VO、Convertor 做 `PO -> VO` 或使用旧式 Entity 布局时，返回 `unsupported`，不得由新 scaffold 自动改写。旧项目继续按原工程维护；现代化改造必须单独立项。

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

@@ -0,0 +1,73 @@
+---
+name: yss-research
+description: Research technical or product-strategy questions with traceable evidence before YSS Discovery, Spec, domain-strategy, API, architecture, or implementation decisions. Use for current facts, standards, third-party APIs, business constraints, user problems, domain-boundary evidence, or when the deprecated `research` alias is invoked.
+---
+
+# YSS Research
+
+Investigate facts that a YSS decision depends on. Produce evidence and bounded conclusions; do not make or approve the downstream product, domain, architecture, or release decision.
+
+`research` is a deprecated compatibility alias. Use `yss-research` in new assets and routing.
+
+## Profiles
+
+- `technical-evidence`: standards, official documentation, source code, third-party APIs, framework behavior, protocols, or implementation constraints. Decision-bearing claims must trace to primary sources.
+- `strategy-evidence`: user problems, business constraints, MVP/non-goal evidence, success criteria, domain-boundary signals, core business-rule evidence, and stage-decision inputs. This profile may consume direct-experience and near-primary evidence with explicit limitations.
+
+Route competitor, pricing, category, and market-position research to `competitive-intelligence`; consume its cited result rather than duplicating it. Route product UI and workflow-friction scans to `product-design:research` when that platform skill is available. `yss-research` may synthesize their outputs but does not replace their specialist contracts.
+
+## Modes
+
+- `quick` is the default for exploratory fact finding. Return an in-chat brief unless the user asks to persist it.
+- `evidence-audited` is required when research directly informs a persisted Spec, domain strategy, stage decision, OpenAPI, architecture decision, or another lifecycle approval input. It is also used when the user explicitly asks for deep, strict, reproducible, or auditable research.
+
+Do not silently promote an exploratory request solely because more rigor would be nice. State the active profile and mode before searching; explain when a downstream lifecycle use requires promotion.
+
+## Source policy
+
+1. Start from the decision, audience, time horizon, scope, and questions the research must answer.
+2. Search user-provided or registered material first, using the same inclusion and exclusion criteria as external material. Record exclusions and access failures.
+3. For `technical-evidence`, follow each decision-bearing claim to the official specification, official docs, source code, or first-party API that owns it.
+4. For `strategy-evidence`, classify sources as primary, direct experience, near-primary, secondary, or lead-only. Interviews, tickets, support records, dated reviews, surveys, and credible industry reports are allowed with their sampling and access limits.
+5. Treat untraceable reposts, aggregator snippets, and AI-generated summaries as leads only. They cannot support a published claim.
+6. Seek counter-signals and conflicting evidence. Source count alone is not frequency or confidence.
+
+## Delegation
+
+Use a background Agent when the runtime supports it and the reading can proceed independently while other useful work continues. Otherwise research in the current Agent. Delegation is an execution optimization, not a trust signal.
+
+Lifecycle dispatches must use the repository's structured task package, write isolation, role binding, and handoff contract. The owner receiving the result remains responsible for verifying material claims before consuming them.
+
+## Evidence-audited workflow
+
+Follow [evidence-contract.md](references/evidence-contract.md):
+
+1. Predeclare the research scope, source classes, inclusion/exclusion criteria, and known access limits.
+2. Maintain a reproducible Search Log and independently locatable Evidence Ledger.
+3. Separate observations, inference, hypotheses, and decisions.
+4. Audit each decision-bearing claim against the evidence it cites, including counter-signals.
+5. Narrow partially supported claims; mark unsupported claims `needs-deeper-research`.
+6. Persist `<slug>-research-brief.md` with adjacent `<slug>-evidence.yaml` and run the bundled validator.
+
+For `strategy-evidence`, every claim that determines a user problem, MVP/non-goal, domain boundary, core business rule, success criterion, important business constraint, or stage-decision basis is decision-bearing and must be audited. Background context may be sampled only when explicitly marked non-decision-bearing.
+
+## Ownership boundary
+
+- Research output is evidence, not approval.
+- `domain-modeling` owns glossary changes; `yss-stage-decision` owns domain strategy and the stage-decision package.
+- The lifecycle orchestrator and designated reviewers own gate state.
+- Do not modify `CONTEXT.md`, Spec, domain-strategy, OpenAPI, architecture, Ticket status, or approval records unless a separately authorized owning work unit performs that change.
+
+## Output
+
+A quick brief includes scope, findings, sources, inference, confidence, counter-signals, gaps, and the next decision it informs.
+
+For persisted `evidence-audited` work, start from [research-brief-template.md](assets/research-brief-template.md) and [evidence-template.yaml](assets/evidence-template.yaml). Run from this skill directory:
+
+```bash
+node scripts/validate-research-package.mjs <slug>-research-brief.md <slug>-evidence.yaml
+```
+
+In `template-source`, save reusable maintenance research under the existing `.template-source/evidence/maintenance/` convention. In `project-instance`, use the project research/evidence convention and bind any decision-bearing output from the lifecycle asset that consumes it.
+
+If sources are unavailable or conflict, state the limitation. Ordinary gaps lower confidence; a missing or mismatched source for a decision-bearing claim prevents that claim from being treated as established.

package/template/.agents/skills/yss-research/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "YSS Research"
+  short_description: "Research technical and strategy evidence"