create-yss-spec 3.2.0 → 3.3.0

package/template/.cursor/skills/yss-mybatis/references/source-index.md

@@ -1,13 +1,14 @@
 # yss-mybatis Source Index
 
-Generated: 2026-08-17T12:03:37.436Z
-Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
-Source worktree: `dirty`
+Generated: 2026-09-08T17:00:36.490Z
+Source commit: `2ccbd3f3f145f9bf74b217a2c211e4bf7a8a2074`
+Component worktree: `clean`
+Component tree `yss-microservice-components/yss-component-persistence`: `274d9f4c948d0bd8a58e7f6fb50685d6de740f7b`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
 This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
-Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
+Paths are relocatable source hints. Exact guidance requires a matching component tree and a clean indexed component subtree; the repository commit is trace metadata and may differ when unrelated components change.
 
 ## Component Path Hints
 
@@ -19,6 +20,8 @@ Paths below are source path hints captured at refresh time. If they do not exist
 - `yss-microservice-components/yss-component-persistence/README.md`
 - `yss-microservice-components/yss-component-persistence/TECHNICAL_DESIGN.md`
 
+Component documentation is a discovery aid. For API signatures, conditions and defaults, prefer the indexed source facts below when documentation differs.
+
 ## Maven Modules
 
 - `yss-microservice-components/yss-component-persistence`
@@ -27,67 +30,84 @@ Paths below are source path hints captured at refresh time. If they do not exist
 - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter`
 - `yss-microservice-components/yss-component-persistence/yss-component-persistence-common`
 
-## Key Java Entry Points
-
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/config/defaults/UserConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/config/spring/SpringEnvAutoConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/BaseMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/Mapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/base/EntityMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/config/MapperUserConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/example/ExampleMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/fn/FnMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/list/ListMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalColumn.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalProvider.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityColumnFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityInfoMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlCache.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlScript.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlScriptWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlSourceCustomize.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/config/ProviderUserConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/AnnotationSqlScriptWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/AnnotationSqlWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/CachingEntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityColumnFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityColumnFactoryChain.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityTableFactoryChain.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/GenericTypeResolver.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/JpaEntityColumnFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/JpaEntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/SimpleTypeUtil.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenId.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenIdKeyGenerator.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenIdSqlSource.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/KeySqlMsCustomize.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/KeySqlSqlSourceCustomize.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/MybatisPlusConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/MybatisPlusGlobalProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/PageInterceptorProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MybatisPlusConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/LogbackImpl.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/MybatisBaseConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/PrimaryDataSourceConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/PrimaryDataSourceProperties.java`
-
-## Recommended Next Reads
-
-- Start with the documentation files above when learning component usage.
-- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.
-- Prefer existing component extension points over rewriting framework logic in business modules.
+## Capability Matrix
+
+### Repository abstractions
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java` — `sha256:fd6d72ff759b3438a2cf9d8a2ba24e848a9e68995fc8a100a0a53c65ee3500bb`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:20` — `public interface BaseRepository<T, D extends Serializable> extends Mapper<T>, BaseMapper<T, D>, ListMapper<T> {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:66` — `<S extends T> int insert(S entity);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:80` — `<S extends T> int insertSelective(S entity);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:85` — `<S extends T> int insertList(@Param("entityList") List<S> entityList);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:96` — `<S extends T> int updateList(@Param("entityList") List<S> entityList);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:108` — `<S extends T> int updateListSelective(@Param("entityList") List<S> entityList);`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java` — `sha256:3c37b73a2a2dcaa1ad47fee42f8fb4f9b9ecf51b095f8d1fef816cf785fcbb05`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:12` — `public interface BasePlusRepository<T> extends BaseMapper<T> {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:21` — `default Integer insertBatchSomeColumn(List<T> entityList) {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:29` — `Integer rows = insertBatchSomeColumnInternal(entityList.subList(fromIndex, toIndex));`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:43` — `Integer insertBatchSomeColumnInternal(List<T> entityList);`
+
+### Pagination and activation
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java` — `sha256:617d5eba33a8266bfc485c8e5f39f43519dd16f4d89c9fea7f918d87b00293ba`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java:22` — `@Around("( (execution(public * (@org.springframework.stereotype.Repository *).*(..)) || execution(* com.yss..*.gateway.impl.*.*(..))))&& (args(pageQuery)||args(pageQuery,..))")`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java:27` — `Page<Object> page = PageHelper.offsetPage(pageQuery.getOffset(), pageQuery.getPageSize());`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java` — `sha256:c2659f417c10db7fd9e1a91f825d3b6396ae949f7858dbd3b3d9f8917ae42031`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java:15` — `@ConditionalOnProperty(name = "yss.mybatis.page-helper.enabled", havingValue = "true", matchIfMissing = true)`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java` — `sha256:2fda7b769434bd6942f680cdc7ffa71030c0d6a0e448d762e0f19b2d0b33cd85`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:8` — `@ConfigurationProperties(value = "yss.mybatis",ignoreUnknownFields = false)`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:10` — `private String mapperLocation = "mappers/*.xml";`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:11` — `private String mapperScan = "com.yss.cloud.**.mapper";`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:15` — `private Integer batchSize = 200;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:21` — `private PageHelper pageHelper = new PageHelper();`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:27` — `private MybatisPlusPagination mybatisPlusPagination = new MybatisPlusPagination();`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:36` — `private String dbType;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:164` — `private Boolean enabled = true;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:183` — `private Boolean enabled = true;`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java` — `sha256:79509947c12aeac7b9d6d3e8610edea438240b6613368b84b57b492f06a6b7fc`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:47` — `PageInterceptor pageInterceptor = new PageInterceptor();`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:264` — `batchSqlInjector.setDbType(dbType);`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:265` — `BatchInsertSettings.setBatchSize(yssMybatisMapperProperties.getBatchSize());`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:275` — `PaginationInnerInterceptor paginationInnerInterceptor = new PaginationInnerInterceptor(dbType);`
+
+### SQL-level batch insertion
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java` — `sha256:b1ae05aed5f90a97c36ad29d240b05f9f7c5ee5796f2bc293917e09f7d1c8bd2`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:8` — `private static final int DEFAULT_BATCH_SIZE = 200;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:9` — `private static volatile int batchSize = DEFAULT_BATCH_SIZE;`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:18` — `public static void setBatchSize(Integer configuredBatchSize) {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:19` — `batchSize = configuredBatchSize == null || configuredBatchSize <= 0`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:20` — `? DEFAULT_BATCH_SIZE : configuredBatchSize;`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java` — `sha256:463dfc881c0c33e27ed2a9157041e8b06d2b2e8bbab0dae1a106f467c31fb4ef`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java:16` — `public class BatchSqlInjector extends DefaultSqlInjector {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java:28` — `"insertBatchSomeColumnInternal", dbType, i -> FieldFill.UPDATE != i.getFieldFill()));`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java` — `sha256:9cc31f71154fffbc99e4f67816b9026f286f864cfb56a57420185f5e0362dca3`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:24` — `public class DialectInsertBatchSomeColumn extends AbstractMethod {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:82` — `return dbType == DbType.ORACLE`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:83` — `|| dbType == DbType.ORACLE_12C`
+  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:84` — `|| dbType == DbType.DM;`
+
+### Multi-data-source capability boundary
+
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java` — `sha256:d19370f6a63af76ccb0d05084ef9f0aa71488dcc98b320933ffb8ccf9b9bf896`
+  - `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java:10` — `public class MultiDataSourceHolder {`
+  - `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java:12` — `private Map<String, DataSource> multiDataSource;`
+
+### Auto-configuration registration
+
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/resources/META-INF/spring.factories` — `sha256:592ecdc43e8e11f86c6d1c4b335661f7a05ae8faf4ebb206ec49ef25512d5e46`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration=\`
+  - `io.mybatis.config.spring.SpringEnvAutoConfiguration`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/resources/META-INF/spring.factories` — `sha256:22d8e4510b67fffe9a132b20524c1982c530d80594a3c4e9f839e914068e0a58`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MybatisPlusConfiguration`
+- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/resources/META-INF/spring.factories` — `sha256:ab6be3903a3af9369ecc56d47dac769511e62bc4a7215ebb7171a920415fa23f`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MybatisBaseConfiguration,com.yss.cloud.mybatis.MybatisPlusConfiguration`
+- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/resources/META-INF/spring.factories` — `sha256:59e4a12550a854ad5a5b253ba3300058edc6646b2b221505aab4fb6bfcad1721`
+  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MultiDataSourceConfiguration`
+
+## Freshness and Use
+
+- Locate the current source root using `YSS_SOURCE_ROOT`, CodeGraph, Maven artifact names or repository search.
+- Compare each indexed `Component tree` with `git rev-parse HEAD:<component-path>` and require the current component subtree to be clean before exact guidance.
+- A repository commit difference alone is not stale when the component tree is unchanged; a component tree mismatch or component-local dirty state is stale.
+- Read only the source entries needed for the current decision or troubleshooting path.

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

@@ -5,74 +5,79 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 
 # YSS Product Lifecycle
 
-这是生命周期主控 skill：负责识别阶段、判定影响面、检查产物与门禁、选择下一工作单元并验收结果。业务实现必须交给对应的 Matt/YSS 专项 skill；本 skill 不替代它们。
+生命周期的单一主控入口。它识别仓库身份和最近可信阶段，计算可执行 frontier，选择并验收下一个工作单元；业务设计、实现和独立审查交给相应专项 skill。主控不替代专项 skill，也不复制它们的执行手册。
 
-## 入口与边界
+## 事实源与按需加载
 
-1. 先读取 `yss-project.yaml`、`CONTEXT.md`、相关 ADR、父 Ticket/checkpoint 和当前资产。
-2. `repository_mode=template-source` 只走模板维护流程；命中产品流程时返回 `blocked: template-source-product-artifact-forbidden`，不得生成产品 Spec、原型、OpenAPI 或切片 Ticket。
-3. `repository_mode=project-instance` 以 `docs/process/lifecycle-registry.yaml`、`harness-process-tailoring.md` 和本目录 references 为唯一阶段、门禁和裁剪事实源；技能分层、别名、默认可发现性和运行时入口以 `docs/agents/yss-skill-registry.yaml`（`status: active`）为准，来源、版本、hash 和投影以 `skills-lock.json` 为准。数字人角色、阶段协作组、运行时绑定与会签级别以 `docs/agents/digital-human-roles.yaml` 为准；职称实例不另起编排器。
-4. 模式：`route` 只读规划；`orchestrate` 有界推进；`resume` 重建后推进；`audit` 严格只读。未明确时使用 `route`。
+先读取项目根 `yss-project.yaml`、`CONTEXT.md`、相关 ADR、父 Ticket/checkpoint 和当前资产。随后只加载当前决策需要的合同子树：
 
-Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为显式兼容入口；默认路径是本 skill 持有的原生工作单元，由本编排器创建正式资产、维护状态并在会签门禁暂停（级别见数字人角色注册表）。兼容入口不得自动调用它们或代替其创建正式资产；Matt 只导航，不得写生命周期资产或改变门禁/Ticket 状态；任何写入前回交本编排器。
+| 事实 | 权威来源 |
+|---|---|
+| 阶段、门禁、产物、工作单元、证据和稳定 ID | `docs/process/lifecycle-registry.yaml` |
+| 执行模式、流转、readiness、暂停、结果和授权语义 | `references/orchestration-contract.yaml` |
+| Skill 身份、capability、依赖和路由 | `docs/agents/yss-skill-registry.yaml` |
+| 数字人角色、运行时和会签策略 | `docs/agents/digital-human-roles.yaml` |
+| 影响面、裁剪和模板维护强度 | `docs/process/harness-process-tailoring.md`、`docs/process/maintenance-intensity.yaml` |
 
-技能调用先消费 `docs/agents/yss-skill-registry.yaml` 的 `invocation_contract`：它只约束调用模式、触发/排除条件、主要输出和依赖，不替代生命周期证据或门禁。进入实现后，Slice Contract 的 `common.context_plan` 只加载当前切片的最小充分上下文；缺失权威上下文必须 `blocked` 或回 实现合同编译器，不得猜测补齐。质量标准由 `engineering-baseline` 一次定义并由切片、Execution Result、审查和发布复用；命中高风险影响时在途记录 Doubt-Driven 主张、反证、证据和残余风险。Wayfinder 仅作为超长或决策前沿不清晰工作的可选 Discovery → Spec 规划模式，完成后回到 `handoff → to-spec`，不改变生命周期状态。
+使用 `scripts/query-lifecycle-context` 获取确定性 JSON 投影，不要为普通路由整份读取编排合同：
 
-## 不可裁剪的主链
+```bash
+scripts/query-lifecycle-context --mode route
+scripts/query-lifecycle-context --stage stage.discovery
+scripts/query-lifecycle-context --work-unit work-unit.discovery-requirements
+scripts/query-lifecycle-context --work-unit work-unit.slice-implementation --include ready_for_agent --include ticket_formalization
+```
 
-新后端工程先按注册表选择 architecture_profile（target-domain-model / layered-mvc-service / mvc-data-analysis-v1），禁止从模块目录反推。全部新骨架只绑定 H2 本地/测试，不绑定生产数据库。独立数据分析 project-instance 走 `work-unit.service-project-initialization` 和 `yss-mvc-data-analysis-project-initializer`；通用 MVC 不调用该初始化器。父项目只保留交接/服务引用，子项目有自己的根 CONTEXT、Git 和生命周期。规则见 `docs/agents/backend-architecture-profiles.md`；Profile 为 draft 时不得 ready-for-agent。
+`--include` 接受编排合同的顶层键；非法模式、ID 或合同键必须失败。查询结果只是带摘要的权威事实投影，不成为新的事实源。解释性细节按需读取 `references/orchestration.md`、`references/state-model.md`、`references/artifact-dependencies.md`、`references/user-decisions.md` 和 `references/matt-yss-adapter.md`，达到最小充分证据后停止扩展上下文。
 
-入口分诊 → Discovery → Spec / 功能架构 → 产品设计 → 系统 / 数据架构与工程契约 → Ticket 正式化 → 垂直切片实现（前后端 TDD）→ 验证 / 发布 / 复盘。
+## 入口与模式
 
-裁剪只允许将未命中的条件门禁标记为 `not-applicable` 并写原因；不得删除主阶段、已命中的门禁或必需产物。阶段是否完成取决于“内容 + 审查结论 + 上游新鲜度 + 可读证据”，文件存在不算通过。每个 `project-instance` 工作单元在请求批准或进入下一工作单元前，必须先把已确认稳定术语回写到项目根目录唯一的 `CONTEXT.md`，再产出通过 `scripts/verify-context-reconciliation` 的 `context_reconciliation`；它是横切证据，不新增门禁。存在候选术语、错误路径、无法解析的 `<ContextId>/<EnglishIdentifier>`、摘要漂移或未决冲突时返回 `blocked`。
+1. 严格解析 `yss-project.yaml`，不得按目录、Git remote 或占位符猜仓库身份。
+2. 判定影响面和最近可信阶段；阶段完成必须同时满足内容、审查结论、上游新鲜度和可读证据，文件存在不代表通过。
+3. 模式为 `route`、`orchestrate`、`resume`、`audit`；未明确时使用只读 `route`。具体写入边界从编排合同的 `modes` 子树读取。
+4. `project-instance` 按生命周期注册表推进；`template-source` 只走模板维护流程。
 
-## 阶段路由与技能
+## 不可越过的边界
 
-下表按 `lifecycle-registry.yaml` 的主阶段颗粒度编排；同一阶段内的多个工作单元、条件技能和门禁依赖以 references 为准。
+### 仓库身份
 
-| 主阶段 | 必需产物/门禁 | 原生工作单元与技能 | 通过条件 |
-|---|---|---|---|
-| 入口分诊 `stage.entry-triage` | 身份、影响面、最近可信阶段 | `work-unit.entry-triage`；`yss-product-lifecycle` | `yss-project.yaml` 合法且影响面可解释 |
-| Discovery `stage.discovery` | 机会与目标、业务故事、用户/MVP/非目标/成功标准、测试 seam；需要时补充业务边界与规则设计和方案决策包 | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements` + `work-unit.domain-strategy-design` + `work-unit.stage-decision`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `yss-research:technical-evidence`，业务边界与方案决策证据用 `yss-research:strategy-evidence`；需求澄清用 `grilling`，业务词汇和责任区梳理用 `domain-modeling` / `yss-stage-decision`；`grill-with-docs` 为兼容入口 | 未决事实已由 `yss-research` 核验或 handoff；业务板块、责任区、统一业务词汇、协作关系和不可违反规则可审查；方案决策包完成必要批准；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
-| Spec / 功能架构 `stage.spec-architecture` | Spec、产品总体设计、功能架构；必要时 Spec Delta | 原生 `work-unit.spec-synthesis`；`to-spec` 为兼容入口 | 初稿先为 `ready-for-human`；只有 Spec baseline 会签批准后资产才为 `approved` 并进入下游 |
-| 产品设计 `stage.product-design` | 交互说明、低保真、状态矩阵、H1/H2 原型交付物、评审记录 | `work-unit.prototype-design`；`yss-prototype-stage` 先消费 `yss-design-system`、低保真与独立 `prototype-review`，再按风险选择 H1 静态视觉或 H2 可运行流程；H2 默认调用 `yss-antdv-next-design`，显式 `react-antd-6` 兼容路线才调用 `yss-antd-design`，原型阶段禁止调用 `yss-ui` | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有 schema v3 证据；真实组件待验事项已交接到前端实现计划 |
-| 系统 / 数据架构与工程契约 `stage.system-data-engineering` | OpenAPI Draft/Freeze、数据架构、工程基线、架构审查；按已确认架构执行 DDD / MVC 技术设计 | `work-unit.technical-analysis`；`yss-technical-design` + `yss-implementation-contract-compiler`、 `yss-openapi-governance` / `yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`；分支调用 `yss-tactical-design` / `yss-mvc-design`；用户或合同明确要求架构可视化时条件追加 `archify` | API/架构契约冻结；无 API 影响有明确记录；战术模型无未解释冲突；脚手架策略满足；Archify 图只作派生审查证据；`gate.openapi-draft-reviewed`、`gate.design-reviewed`、`gate.openapi-frozen`、`gate.engineering-baseline-accepted`、`gate.architecture-reviewed` |
-| Ticket 正式化 `stage.ticket-formalization` | 功能父 Ticket、垂直切片、Slice Implementation Contract | 原生 `work-unit.ticket-decomposition`；`yss-implementation-contract-compiler`；`to-tickets` 为兼容入口；生命周期复算 | 依赖、验收、测试 seam 可执行；合同已批准、持久化且为当前版本；`gate.slice-contract-approved`、`gate.slice-ready-for-agent` |
-| 垂直切片实现 `stage.vertical-slice-implementation` | 前端/后端代码、TDD 证据、YSS Skill Execution Result | 原生 `work-unit.slice-implementation`；`yss-implementation-contract-compiler` + `tdd`；前端按 `yss-ui` + `yss-ui-business-page-generation`，后端按 实现合同编译器 最小闭包；`implement` 为兼容入口 | 仅接收已完成 Ticket 正式化、已绑定垂直切片且 `ready-for-agent` 公式通过的输入；只写允许路径；业务行为用 `tdd` 的 `behavior-tdd` 模式；UI 影响必须有还原计划 |
-| 验证 / 发布 / 复盘 `stage.verification-release-retrospective` | 不可变候选快照、review 结论、fresh verification、发布 / 回滚证据、复盘记录 | `work-unit.frontend-implementation-verification` + `work-unit.code-review` + `work-unit.release-and-retrospective`；`code-review` 独立于实现者，Standards 消费合同 `required_skills` 与 YSS / Alibaba 专项检查输入；UI 影响追加 `yss-ui` + `yss-design-system` 的 UI fidelity 轴；发布 / 复盘由生命周期持有 | findings 已按合同分流处理（修复后全轴复审或 stale 回 实现合同编译器）；同一候选快照通过全部审查轴、专项覆盖与验证；UI 影响追加 `gate.frontend-implementation-verified`；`gate.release-ready` 仍须生物人 |
+`template-source` 不得生成产品 Spec、原型、OpenAPI 或垂直切片 Ticket；命中产品流程时返回 `blocked: template-source-product-artifact-forbidden`。模板维护使用 `maintaining-skills`，按 L1/L2/L3 留下对应证据。
 
-## 面向业务角色的默认入口
+### 流转与实现
 
-Discovery 默认通过 Agent 引导，不要求产品、需求或商务直接填写内部模型字段。按以下主线推进：
+不得越过命中的阶段、门禁、实现仓库准备或 Ticket 正式化。实现只接收绑定垂直切片、已批准且持久化、版本当前并通过完整 `ready-for-agent` 计算的合同；父 Ticket、`ready-for-human` 切片、`stale`、`drift`、`new_impacts`、`violation` 或缺失证据均阻断。实现仓库、脚手架、UI 还原、review input 和发布条件从对应合同子树查询，不在入口重复定义。
 
-`机会与目标 → 业务故事 → 责任与交接 → 规则、例子与疑问 → 可验收需求 → 页面验证 → 业务任务 → 交接研发`
-
-Agent 先问清六件事：谁遇到什么问题并想得到什么结果；事情通常怎样发生；每一步由谁负责并交给谁；有哪些规则、例外和未决问题；哪一小段可以独立交付；用哪些例子和证据证明结果正确。需要分类业务板块时，改问“是否直接决定关键结果、是否有独特规则、是否可复用或外购”，再提出“重点业务、必要支撑、通用能力”建议，由业务负责人确认。
+### 用户决定
 
-每轮路由先输出一页派生的“业务方案总览”，引用机会与目标、业务故事、业务责任区、规则与例子、Spec、页面验证、Ticket 和交接状态。总览只显示状态、权威资产引用、未决问题、责任人和下一步，不复制正文、不成为新的事实源，也不新增门禁。内部稳定 ID 和兼容字段只在 Agent 运行结果或维护者诊断中显示。
+命中 `docs/agents/digital-human-roles.yaml.user_decision_policy` 的关键决定，必须先展示当前资产、版本、变化、风险、推荐方案、批准范围和后续动作，再取得提问者或其明确指定生物人负责人的原始回复。数字人同意、超时、默认项或无反对意见不能代答；恢复前按 `references/user-decisions.md` 验证当前资产与原始回复绑定。
 
-## 前端实现还原硬检查
+### 外部副作用与 Git
 
-采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `docs/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
+生命周期批准、实现授权和自然语言意向不构成结构化 Git 授权。commit、push、远端仓库创建、发布及其他运行时外部副作用分别检查明确动作、范围和可读授权引用；缺失时保持外部状态不变。`git-submodule` 还必须遵守逐仓授权、非 detached HEAD 和先子仓后父仓 gitlink 的顺序。
 
-原型通过不等于前端实现通过。`ready-for-agent` 前先产生 `frontend_implementation_plan`，绑定批准且 digest 当前的 Visual Baseline manifest，并按垂直切片选择 `case_id`；实现完成、发布前再产生 `frontend_implementation_verification`，逐 case 配对基准图、实现图、diff/mask 与差异解释，同时补齐交互、console warning、实际 `pnpm` 命令和退出码。模型必须先读 manifest 与语义引用再查看图片，禁止通过目录 glob 猜测含义。差异未解释、图片或摘要缺失、只做 type-check 或只声称“已对齐”均为 `blocked`；Visual Baseline 版本或 digest 变化使实现计划和 Slice Contract `stale`，新 API、状态或视觉行为返回 `new_impacts`/`drift` 并重新路由。优先使用 `yss-ui/references/verification.md` 的分层验证和既有 `pnpm` scripts。
+## 有界编排循环
 
-## 真实用户决定
+1. 从真实资产重建当前状态，查询当前 mode、stage、work-unit 及必要合同子树。
+2. 评估影响面、上游新鲜度、门禁和阻塞，选择第一个未阻塞工作单元；不把 `not-applicable` 当作豁免。
+3. 原生工作单元由主控持有正式资产；专项工作通过结构化任务包派发，只调用编排合同允许的 model-invoked skill。
+4. Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等仅为显式 user-invoked 兼容入口。主控不得自动调用它们或代替其创建正式资产；Matt 仅导航，不得写生命周期资产或改变门禁/Ticket 状态，任何写入前回交本编排器。
+5. 验收 `Workflow Execution Result`：工作单元、合同、允许写路径、`context_reconciliation`、证据、实际验证、延期 seam、漂移和下一路由必须可核验。实现派发额外绑定当前 Slice Implementation Contract；其他阶段不得伪造该合同。
+6. 在授权边界内继续下一工作单元；遇到人工决定、新授权、证据冲突、专项失败或合并/发布结论时暂停。暂停不得阻断无依赖的独立工作。
 
-关键决定按 `docs/agents/digital-human-roles.yaml.user_decision_policy` 强制取得提问者或其明确指定的生物人负责人的原始回复。先展示资产、版本、变化、风险、推荐方案、批准范围和后续动作，再等待决定；超时、默认选项、数字人同意、无反对意见均无效。数字人审查不能替代用户批准；已有同版本同范围的有效确认复用，依据变化或撤回后重新展示并确认。单项“同意”有效，多项“继续”不算全部批准。独立工作可继续，依赖工作不得流转。
+每个 `project-instance` 工作单元在申请批准或流转前，先把稳定术语回写到根目录唯一 `CONTEXT.md`，并生成通过校验的 `context_reconciliation`。候选术语、错误路径、摘要漂移或未决冲突必须阻断。质量标准只由 `engineering-baseline` 定义一次；高风险影响按裁剪合同补充反证和残余风险。
 
-统一记录、跨平台来源、机器校验、批量批准、历史兼容和实施范围绑定见 [user-decisions.md](references/user-decisions.md)。批准、恢复和实施入口必须重读来源与当前资产；不得只填 `approved`、自行创建用户同意或用旧数字人记录关闭关键门禁。
+## 面向业务角色
 
-## 结果与暂停
+默认使用业务语言推进：
 
-凡主控向数字人角色或独立运行时正式派发生命周期工作单元，都必须通过结构化任务包派发，并返回 `Workflow Execution Result`（workflow reference、skill、changed files、`context_reconciliation`、evidence refs、actual verification、deferred seams、drift/new impacts）。任务包使用 `docs/process/schemas/digital-human-task-package.schema.json`，由 `scripts/verify-digital-human-task-package` 校验；其中 `role_id`、`runtime_id`、`execution_state`、`contract.kind/id/version`、允许写路径、预期证据和汇合引用必须完整。`slice-implementation` 任务包额外绑定批准且当前版本的 Slice Implementation Contract；Discovery、Spec、原型、技术分析、Ticket、Review、发布和模板维护分别绑定各自的生命周期资产或维护 checkpoint，不得伪造 Slice Contract。缺少可读证据、`context_reconciliation` 未通过、`stale`、`violation`、`drift`、`new_impacts` 或阻塞信号时不得标记 completed。实现授权不包含 Git commit/push 授权；仅自然语言意向不构成上述结构化 Git 授权。用户已明确授权的具体动作可从原始回复整理为结构化授权并复用，不重复要求用户填写内部字段。
+`机会与目标 → 业务故事 → 责任与交接 → 规则、例子与疑问 → 可验收需求 → 页面验证 → 业务任务 → 交接研发`
 
-输出固定包含：模式、当前阶段、影响面、资产/门禁状态、证据、Ticket 正式化状态、垂直切片引用、`ready-for-agent` 计算结果、阻塞项、本轮动作、下一工作单元、暂停/继续理由、Ticket 同步和 Git checkpoint 判断。原生路径未出现 `to-tickets` / `implement` 名称本身不构成异常；但没有完成 `work-unit.ticket-decomposition`、垂直切片仍为 `ready-for-human`、引用父 Ticket 或 `next_route` 越过 Ticket 正式化时必须返回 `blocked`。暂停会签时必须输出门禁 ID、指定 `role_id`、`runtime_id` 和会签文件路径（`docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`）。恢复前运行 `scripts/verify-approval-record --require-approved`；错误会签记为 `blocked`，不得把该门禁标为 `approved`。任务包的 `core_skills` / `forbidden_skills` 必须从 `docs/agents/digital-human-roles.yaml` 复制（`taskPackageDefaults`），禁止手写第二套。
+先问清用户与结果、通常流程、责任交接、规则与例外、可独立交付的最小范围、证明结果正确的例子和证据。每轮可生成一页“业务方案总览”，只引用权威资产并显示状态、未决问题、责任人和下一步；不复制正文、不成为新的事实源、不新增门禁。
 
-详细执行循环、readiness、脚手架（包括 `controlled-generation`）、审查快照、状态传播和 Matt 边界见 [orchestration.md](references/orchestration.md)、[orchestration-contract.yaml](references/orchestration-contract.yaml)、[artifact-dependencies.md](references/artifact-dependencies.md) 和 [state-model.md](references/state-model.md)。
+## 结果与暂停
 
-## 战略交接快照包
+输出至少包含：模式、仓库身份、当前阶段和工作单元、影响面、资产与门禁状态、证据、新鲜度、Ticket/垂直切片/合同状态、`ready-for-agent` 结论、阻塞项、本轮动作、下一工作单元、暂停或继续理由、Ticket 同步和 Git checkpoint 判断。
 
-跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。
+暂停会签时追加门禁 ID、`role_id`、`runtime_id`、会签文件路径、推荐答案和恢复动作；恢复前运行适用验证器。只有同一候选快照通过全部适用审查轴与 fresh verification，才能提出合并、发布或完成结论；发布仍须生物人决定。
 
-来自战略交接包的技术设计合同（DDD / MVC）必须绑定 `strategic_handoff` 导入收据、包摘要、正式目标对账及逐条承接 rows。来自导入包时禁止仅填 `upstream_current: true`。批准前执行 `scripts/verify-strategic-handoff-consumption --root <target> <tactical>`；存在受控延期时按切片执行 `--slice <slice-id>`，实际核验通过且合同批准后才可继续相关切片。最新源规则、关键场景或资产变化使依赖项 stale；未知依赖扩大阻断，业务冲突回交战略方。结果绑定当前包与战术摘要，不能复用旧输出宣布 ready-for-agent。
+专项加载提示：实现仓库与脚手架查询 `implementation_repository_preparation`、`backend_scaffold`；切片实现查询 `ticket_formalization`、`ready_for_agent`；UI 查询 `frontend_implementation_plan`、`frontend_implementation_verification`；审查查询 `review_input`；发布查询 `release_readiness`、`git_authorization`、`user_decision_evidence`；战略交接读取 `docs/process/strategic-handoff-package.md` 并按其中验证器执行。

package/template/.cursor/skills/yss-product-lifecycle/references/artifact-dependencies.md

@@ -9,10 +9,12 @@ Spec + Product Overview → Product Design / Requirement Freeze
 Spec + Product Overview → API Impact / OpenAPI Draft
 Spec + Product Overview → System / Data Architecture
 System / Data Architecture + confirmed project architecture → Technical Design Contract (DDD / MVC)
-Technical Design Contract → Architecture Review / Engineering Baseline → Slice Implementation Contract draft
+Technical Design Contract → Architecture Review / Engineering Baseline → implementation repository choice
+implementation repository choice → existing repository onboarding OR approved Project Scaffold Contract → scaffold generation / verification
+Repository Onboarding Result OR Scaffold Manifest + Verification → Implementation Repository Preparation Result → gate.implementation-repositories-ready
 API impact = yes: Requirement Freeze + Design Review + Draft Review → OpenAPI Freeze
 API impact = no: API Impact Assessment approved → No-API-Impact record；Draft/Freeze gates = not-applicable
-Frozen Contract → Vertical Slice Tickets
+Frozen Contract + gate.implementation-repositories-ready → Vertical Slice Tickets
 Tickets + Architecture → Implementation Contract / Build Architecture Checklist
 Implementation → Independent Review → Fresh Verification → Release
 ```

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

@@ -294,6 +294,17 @@ work_unit_routes:
     human_gate: openapi-freeze_if_api_impact
     applies_when: technical_or_contract_impact
     not_applicable_reason: no_technical_or_contract_impact
+  work-unit.implementation-repository-preparation:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: implementation-repo-onboarding
+    supporting_skills: [yss-implementation-contract-compiler, yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator, yss-frontend-scaffold-generator]
+    skills: [implementation-repo-onboarding, yss-implementation-contract-compiler, yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator, yss-frontend-scaffold-generator]
+    applies_when: before_ticket_formalization
+    not_applicable_reason: no_frontend_or_backend_delivery_impact
+    decision_boundary: scaffold-choice
+    completion_states: [existing-and-onboarded, initialized-and-verified, not-applicable]
+    aggregate_gate: gate.implementation-repositories-ready
+    must_complete_before: work-unit.ticket-decomposition
   work-unit.ticket-decomposition:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
     primary_skill: yss-product-lifecycle
@@ -342,8 +353,8 @@ work_unit_routes:
   work-unit.code-review:
     native: {source: yss-product-lifecycle, skill: code-review, invocation_mode: model-invoked}
     primary_skill: code-review
-    supporting_skills: [alibaba-java-code-style, yss-ui, yss-design-system, yss-ui-business-page-generation, yss-domain, yss-application, yss-repository, yss-web-controller, yss-dto, mapstruct, lombok]
-    skills: [code-review, alibaba-java-code-style, yss-ui, yss-design-system, yss-ui-business-page-generation, yss-domain, yss-application, yss-repository, yss-web-controller, yss-dto, mapstruct, lombok]
+    supporting_skills: [alibaba-java-code-style, yss-ui, yss-design-system, yss-ui-business-page-generation, yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-dto, mapstruct, lombok]
+    skills: [code-review, alibaba-java-code-style, yss-ui, yss-design-system, yss-ui-business-page-generation, yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-dto, mapstruct, lombok]
     review_standards_route:
       unique_default_skill: code-review
       second_generic_review_skill: forbidden
@@ -354,8 +365,13 @@ work_unit_routes:
         run_if_present: true
         missing_tooling: not-applicable-with-reason
         checkable_rule_without_machine: not-a-pass
+      project_scope:
+        sources: [candidate-project-root, implementation-repository-registry, slice-project-roots, allowed-write-paths]
+        include: [project-itself, registered-backend-development-projects]
+        exclude: [frontend-projects, unrelated-submodules, vendor, unregistered-directories]
+        fixed_apps_backend_assumption: forbidden
       conditional_skills:
-        backend_impact: [alibaba-java-code-style, yss-domain, yss-application, yss-repository, yss-web-controller, yss-dto, mapstruct, lombok]
+        backend_impact: [alibaba-java-code-style, yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-dto, mapstruct, lombok]
         ui_impact: [yss-ui, yss-design-system, yss-ui-business-page-generation]
       not_applicable_reasons:
         backend_impact: no_backend_impact
@@ -399,7 +415,7 @@ compatibility_flow_preconditions:
     evidence: [user_problem, mvp_and_non_goals, success_criteria, test_seam, terminology_review]
     output_role: ready-for-human
   to-tickets:
-    required: [openapi_freeze_or_no_api_impact, required_gates_satisfied, vertical_slice_scope, blocking_edges]
+    required: [openapi_freeze_or_no_api_impact, required_gates_satisfied, implementation_repositories_ready, vertical_slice_scope, blocking_edges]
     output: vertical-slice-tickets
     output_role: ready-for-human
   implement:
@@ -407,6 +423,7 @@ compatibility_flow_preconditions:
     applies_to_single_session: true
 
 ticket_formalization:
+  repository_predecessor: work-unit.implementation-repository-preparation
   implementation_predecessor: work-unit.ticket-decomposition
   result_ref_required: true
   result_must_be: completed
@@ -424,7 +441,37 @@ ticket_formalization:
     current_version: true
   validator:
     module: scripts/lib/lifecycle-transition.mjs
-    functions: [validateNextRoute, validateTicketFormalization, validateImplementationEntry]
+    functions: [validateNextRoute, validateImplementationRepositoriesReady, validateTicketFormalization, validateImplementationEntry]
+
+implementation_repository_preparation:
+  stage: stage.system-data-engineering
+  work_unit: work-unit.implementation-repository-preparation
+  gate: gate.implementation-repositories-ready
+  applies_per_delivery_role: [backend, frontend]
+  affected_role_allowed_states: [existing-and-onboarded, initialized-and-verified]
+  unaffected_role_state: not-applicable
+  not_applicable_reason_required: true
+  existing_repository:
+    required: [repository_ref, project_root, repository_scope, onboarding_result]
+    onboarding_skill: implementation-repo-onboarding
+    architecture_migration: separate-initiative
+  new_repository:
+    default_scope: external-repository
+    allowed_scopes: [external-repository, harness-apps, git-submodule]
+    user_confirmation_required: [scope, project_root, init_git]
+    remote_repository_creation: explicit-authorization-only
+    approved_project_scaffold_contract_required: true
+    frontend_contract_minimum_schema_version: 4
+    backend_contract_compatibility_schema_versions: [3, 4]
+    target_policy: nonexistent-or-empty
+    force_overwrite: forbidden
+    completion_requires: [scaffold_manifest_ref, scaffold_verification]
+  aggregate_result:
+    required: [result, current_version, projects, evidence_refs]
+    result: completed
+    evidence_refs_readable: true
+    stale_action: return-to-work-unit.implementation-repository-preparation
+  blocking_signals: [implementation-repository-decision-required, implementation-repository-location-required, implementation-repository-onboarding-incomplete, scaffold-choice-required, scaffold-contract-unapproved, scaffold-generation-incomplete, scaffold-verification-failed, frontend-template-unavailable, implementation-repositories-stale]
 
 transition_graph:
   validator: scripts/lib/lifecycle-transition.mjs
@@ -437,14 +484,16 @@ transition_graph:
     work-unit.intensity-aware-verification: [work-unit.intensity-aware-review]
     work-unit.intensity-aware-review: [work-unit.release-and-rollback]
     work-unit.release-and-rollback: []
-    work-unit.spec-synthesis: [work-unit.prototype-design, work-unit.technical-analysis, work-unit.ticket-decomposition]
-    work-unit.prototype-design: [work-unit.technical-analysis, work-unit.ticket-decomposition]
-    work-unit.technical-analysis: [work-unit.ticket-decomposition]
+    work-unit.spec-synthesis: [work-unit.prototype-design, work-unit.technical-analysis, work-unit.implementation-repository-preparation]
+    work-unit.prototype-design: [work-unit.technical-analysis, work-unit.implementation-repository-preparation]
+    work-unit.technical-analysis: [work-unit.implementation-repository-preparation]
+    work-unit.implementation-repository-preparation: [work-unit.ticket-decomposition]
     work-unit.ticket-decomposition: [work-unit.slice-implementation]
   forbidden_shortcuts:
     - {from: work-unit.spec-synthesis, to: work-unit.slice-implementation}
     - {from: work-unit.prototype-design, to: work-unit.slice-implementation}
     - {from: work-unit.technical-analysis, to: work-unit.slice-implementation}
+    - {from: work-unit.technical-analysis, to: work-unit.ticket-decomposition}
 
 grill_exit:
   required: [frontier_empty, facts_resolved_or_routed, decisions_confirmed, shared_understanding_confirmed, no_unresolved_runnable_blocker]
@@ -470,6 +519,10 @@ review_input:
   second_generic_review_skill: forbidden
   axes: [standards, spec, ui_fidelity_if_ui_impact]
   standards_sources: [repo_coding_standards, slice_contract_required_skills, specialist_check_inputs, review_report_template]
+  scope_resolution:
+    sources: [candidate-project-root, implementation-repository-registry, slice-project-roots, allowed-write-paths]
+    backend_includes: [project-itself, registered-backend-development-projects]
+    excludes: [frontend-projects, unrelated-submodules, vendor, unregistered-directories]
   completed_requires_specialist_coverage: true
   finding_disposition_required: true
   completed_requires_no_open_mandatory_violations: true
@@ -618,7 +671,11 @@ backend_scaffold:
     layered-mvc: { recipe: backend.mvc-scaffold, generator_skill: yss-layered-mvc-scaffold-generator, baseline_skills: [] }
   tdd_mode: controlled-generation
   contract_schema:
-    schema_version: 3
+    schema_version: 4
+    current_schema_version: 4
+    schema_ref: docs/process/schemas/project-scaffold-contract.schema.json
+    compatible_backend_versions: [3, 4]
+    frontend_minimum_version: 4
     identity: service-engineering-baseline
     required: [contract_id, contract_version, scaffold_request_id, status, compiler_draft_ref, lifecycle_approval_ref, persisted_ref, current_version, implementation_repository, backend_repository, scaffold_status, project_name, target_output_dir, base_package, architecture_family, generator_skill, decision_ref, decision_id, decision_digest, maven_coordinates, profiles, module_profile, allowed_write_paths, expected_evidence_files, verification_commands, approval, work_unit, generation_policy]
     status_by_owner:
@@ -796,7 +853,7 @@ quality_baseline_reuse:
   redefinition: forbidden
 
 ready_for_agent:
-  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]
+  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, context_plan, quality_baseline_ref, implementation_repositories_ready, implementation_repository_preparation_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

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

@@ -27,6 +27,10 @@ Matt phase boundary 是工作阶段之间的上下文决策，不是新的生命
 
 ## 原型到后端脚手架的接力
 
+阶段 5 在技术分析后固定进入 `work-unit.implementation-repository-preparation`。编排器按 backend / frontend 影响逐项目展示已有或新建工程、Agent 推荐、仓库 scope、目标路径、Git 初始化、验证命令和风险，取得真实用户确认后再执行。已有工程调用 `implementation-repo-onboarding`；新后端按已确认架构调用对应生成器；新前端调用 `yss-frontend-scaffold-generator`。默认 `external-repository`，`harness-apps` / `git-submodule`、`git init` 和远端仓库创建均须显式选择或授权。
+
+所有命中项目必须达到 `existing-and-onboarded` 或 `initialized-and-verified`，未命中的交付面必须有带原因的 `not-applicable`。聚合结果、Manifest、验证和 onboarding 证据必须可读且当前；否则 `gate.implementation-repositories-ready` 阻断 Ticket 正式化。旧实例恢复时保留已有 Ticket，但将相关 Ticket / Slice Contract 标为 `blocked` / `stale` 并返回本工作单元。
+
 `prototype_confirmation` 通过后，先判断实现仓库登记中的 backend `scaffold_status`。当状态为 `required` 时，在工程基线中先完成脚手架架构选择：Agent 按领域复杂度给出 `domain-driven` / `layered-mvc` 推荐和依据，本体选择作为子项目预填默认值，用户通过批量表确认全部项目或逐项覆盖。选择写入 `scaffold-architecture-decisions.yaml`；处于 `undecided`、`recommended`、`awaiting-user-decision` 或 `stale` 时必须阻断，不得默认 DDD，也不得在生成器内交互。
 
 选择达到 `lifecycle-approved` 且 digest 当前后，由 `yss-implementation-contract-compiler` 编译脚手架 schema v3 `controlled-generation` 工作单元合同，生命周期批准并持久化后才能运行对应生成器。顺序为：工程基线与架构推荐 → 用户确认与选择持久化 → 实现合同编译器脚手架合同 draft → 生命周期批准/持久化 → `domain-driven` 使用 `yss-ddd-scaffold-generator` 或 `layered-mvc` 使用 `yss-layered-mvc-scaffold-generator` → 对应基线/Manifest v3 校验 → 实现合同编译器业务合同重编译。`existing` / `initialized` 不重复生成；架构转换必须单独立项。
@@ -58,7 +62,7 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 - `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`。
+- `Workflow Execution Result.next_route` 必须通过生命周期转换校验；Spec、原型和技术分析不得直接跳转到 Ticket 正式化或实现，必须先完成 `work-unit.implementation-repository-preparation`，再进入 `work-unit.ticket-decomposition`。
 - `implement` 遇到 backend `scaffold_status=required` 时，还必须满足原型确认后的脚手架策略：脚手架 Execution Result、`yss-backend-scaffold-parent` 基线、Wrapper 验证和 实现合同编译器 合同重编译均已回写；否则停在工程基线，不得写业务代码。
 - `Workflow Execution Result` 出现 `drift`、`new_impacts`、`stale_candidates`、`violation`、`missing_evidence`、空 `evidence_refs` 或缺少必需字段时暂停当前工作单元；旧结果只能先经只读兼容 adapter 归一化。