create-yss-spec 3.4.9 → 3.5.0

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

@@ -10,8 +10,8 @@ description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、
 ## 工作流
 
 1. 按 `yss-skill-source-index-refresh/references/source-location.md` 定位真实源码。当前工作区有 `.codegraph/` 时先用 CodeGraph；否则读取 [source-index.md](references/source-index.md) 后用符号或 Maven 模块搜索。
-2. 识别使用模型：Spring Cache 单后端路由、Redis 故障降级，或 JetCache local + remote。不要混用三者的行为假设。
-3. 明确缓存名、key、TTL、更新/删除路径、跨节点一致性和序列化兼容要求。
+2. 识别使用模型：Spring Cache 单后端路由、Redis 故障处理，或独立的 JetCache local + remote。`fail-fast`/`bypass`/`fallback` 是当前 Boot 3 Redis 契约；Boot 2 以其独立源码索引为准，不要混用两代或三种模型的行为假设。
+3. 明确缓存名、key、区域 TTL/容量/空值策略、更新/删除路径、跨节点一致性和序列化兼容要求。
 4. 先检查现有依赖、启动注解、配置和注解用法，再决定修改业务代码、配置还是组件。
 5. 修改后执行对应 reference 的验证；组件跨模块修改必须从父 reactor 构建，不要依赖本地旧 SNAPSHOT。
 
@@ -20,13 +20,14 @@ description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、
 - 新增查询缓存时同时覆盖更新、删除和状态变更的失效路径。
 - key 必须稳定并显式包含租户、机构、账套等隔离维度；不要依赖 DTO 的不稳定序列化结果。
 - 不要把 Redis fallback 当作正常二级缓存。Caffeine fallback 存在节点间不一致窗口。
-- 不要声称纯 Redis 后端会广播本地缓存失效。只有确认 JetCache 配置了 local、remote 和 broadcast channel 后才能作此判断。
+- 不要声称纯 Redis 后端会广播本地缓存失效。JetCache 即使存在 broadcast channel 配置，也须验证实际 local/remote 实例和同步开关后才能作此判断。
 - 不要在没有双读、版本前缀、灰度清理或迁移窗口时修改 serializer、key prefix 或 cache name。
 - 不明确一致性要求时，不默认启用本地缓存或 fallback。
 
 ## 按场景读取
 
 - 模块、后端选择或多级缓存边界：[architecture.md](references/architecture.md)
+- JetCache 包装器、`QuickConfig`、跨 JVM 失效与故障边界：[jetcache.md](references/jetcache.md)
 - 新增或修改缓存注解、SpEL、空 key、全量清理：[annotations.md](references/annotations.md)
 - 依赖、启动注解、TTL、Caffeine/Hazelcast、Bean backoff：[configuration.md](references/configuration.md)
 - Redis 单机、哨兵、集群、认证、SSL、超时、Jedis pool：[redis-topology.md](references/redis-topology.md)
@@ -38,10 +39,10 @@ description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、
 ## 工具
 
 - `scripts/inspect-cache-usage.sh <project-root>`：只读扫描消费项目；发现阻断缺陷返回 1，输入或环境错误返回 2。
-- `scripts/verify-cache-component.sh [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]`：验证组件、真实 Redis、Java 8 字节码及可选消费模块。
+- `scripts/verify-cache-component.sh --platform-line <boot2-java8|boot3-java17> [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]`：从匹配的平台源码根干净构建，验证组件、可用时的真实 Redis、对应 Java 字节码及可选消费模块。
 - `scripts/check-skill-freshness.sh <boot2-java8|boot3-java17> [source-root]`：比较所选平台线的技能契约与当前组件源码；发现平台错配或漂移返回 1。
 
-当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新 [source-index.md](references/source-index.md)，再运行 freshness 检查。不要手工修改生成索引。
+本 Skill 中新增的 `failure-mode`、区域策略和 `empty-key-eviction` 指引针对当前 Boot 3 组件；Boot 2 的精确配置与默认值须查其独立索引及源码。组件源码形成干净、固定的来源后，用 `yss-skill-source-index-refresh` 刷新所选平台的生成索引，再运行 freshness 检查。`source-index.md` 是平台选择页；不要手工修改生成索引或把 dirty 工作树的观察说成已核验事实。
 
 ## 平台与源码门禁
 

package/template/.agents/skills/yss-cache/references/annotations.md

@@ -1,5 +1,7 @@
 # 注解契约
 
+以下 `empty-key-eviction` 可配置行为针对当前 Boot 3 / Java 17 组件；Boot 2 的空 key 处理以其独立源码索引和当前源码为准。
+
 ## 映射
 
 - `@QueryCache` -> Spring `CacheableOperation`。
@@ -28,7 +30,7 @@ public void delete(String tenantId, Long planId) { ... }
 ```
 
 - 未配置 key 时由 Spring KeyGenerator 生成；无参数方法会得到 `SimpleKey.EMPTY`。
-- 当前 YSS 拦截器将 `SimpleKey.EMPTY` 视为全量清理。需要单 key 清理时必须给出稳定 key。
+- 当前 Boot 3 的 `yss.cache.empty-key-eviction=legacy-clear`（默认）把 `SimpleKey.EMPTY` 当作清区；`evict` 时只删该 key。迁移前核对原有无参数清理调用及实际属性，不能把默认行为说成所有配置下的不变量。
 - 全量清理优先显式写 `allEntries=true`，不要依赖偶然 key 形态。
 - 集合参数先稳定排序；null、大小写和空白必须归一化。
 

package/template/.agents/skills/yss-cache/references/architecture.md

@@ -1,12 +1,14 @@
 # 架构与选择
 
+以下模型划分适用于接入决策；具体配置、默认值及跨节点行为按所选平台线的当前源码核验。本轮新增的 Redis 故障模式、区域策略和 JetCache 运行证据属于 Boot 3 当前组件。
+
 ## 三种模型
 
 | 模型 | 行为 | 一致性边界 |
 |---|---|---|
 | Spring Cache 后端路由 | `yss.cache.active-type` 在 Redis、Caffeine、Hazelcast 中选择一个 Provider | 同一时刻是单后端，不是多级缓存 |
 | Redis fallback | Redis 故障时可临时改用另一个 Provider | 是故障降级；Caffeine 会产生节点间不一致窗口 |
-| JetCache | 独立扩展，可配置 local + remote | 只有实际配置 broadcast channel 才能认为本地失效会同步 |
+| JetCache | 独立扩展，可配置 local + remote | broadcast channel 配置本身不证明包装器已启用跨 JVM 本地失效同步 |
 
 ## 模块
 
@@ -22,4 +24,4 @@
 - 跨节点共享且不接受节点本地旧值：使用纯 Redis。
 - 读多写少并允许短暂节点差异：可选择 Caffeine。
 - Redis 故障期间业务可用性高于缓存一致性：评估后启用 fallback。
-- 需要 local + remote：先确认 JetCache 的 local、remote、序列化和广播配置，不要只看依赖名称。
+- 需要 local + remote：按 [JetCache 专项参考](jetcache.md) 核对实际创建的 Cache、配置来源及首次创建参数，并用跨 JVM 测试证明同步，不要只看依赖或 `bootstrap.yml`。

package/template/.agents/skills/yss-cache/references/configuration.md

@@ -13,20 +13,23 @@
 
 ## 公共属性
 
+以下示例及 `failure-mode`、区域策略、空值策略说明针对当前 Boot 3 / Java 17 组件。Boot 2 / Java 8 维护须先核对其独立源码索引与匹配源码，不套用这些新属性或默认值。
+
 ```yaml
 yss:
   cache:
     active-type: redis       # redis | caffeine | hazelcast
     default-ttl: 1h
+    failure-mode: fail-fast  # fail-fast | bypass | fallback；仅 active-type=redis
     redis:
       fallback-enabled: false
       fallback-type: caffeine
       clear-fallback-on-recovery: true
 ```
 
-- Redis 动态 cache 和 Caffeine 默认 TTL 使用 `yss.cache.default-ttl`。
-- `CacheKeyCode` 中声明的 TTL 覆盖默认 TTL。
-- Caffeine 的 `spring.cache.caffeine.spec` 可覆盖默认构建规格，修改前检查项目现有配置。
+- `failure-mode` 默认 fail-fast；旧 `redis.fallback-enabled=true` 仍映射 fallback，同时配置为冲突值会拒绝启动。bypass 仅将 Redis 连接/资源故障的查询视为 miss，显式写入和失效仍报告错误；业务与序列化异常不降级。fallback 仅可选择已安装的 Caffeine，不是默认二级缓存。
+- 区域 `yss.cache.regions[区域名]` 可逐字段设置 `ttl`、`caffeine-maximum-size`、`null-policy`。TTL 以区域值优先；Caffeine 用户显式过期策略、`CacheKeyCode` 与 `default-ttl` 的实际优先级按当前组件源码核对。`null-policy=cache` 必须指定正的区域 TTL；`skip` 不等于删除旧值，`reject` 的契约错误不能吞成 Redis 故障。
+- Caffeine `spring.cache.caffeine.spec`、自定义 Builder/Loader 与区域覆盖的组合可能无法表达；核对当前组件的启动拒绝条件。自定义 CacheManager/Provider 时需证明区域策略真实生效，不能因配置存在就宣称 TTL、容量或空值策略已应用。
 - Hazelcast 不在 starter 生产依赖中；使用时显式引入模块并配置 `active-type=hazelcast`。
 
 ## 自定义 Bean

package/template/.agents/skills/yss-cache/references/jetcache.md

@@ -0,0 +1,21 @@
+# JetCache 独立接入与验证
+
+本页记录当前 Boot 3 / Java 17 `yss-component-jetcache` 工作树的接入判断；Boot 2 的精确能力以其平台索引和匹配源码为准。JetCache 与 YSS Spring Cache 是两条独立入口，不继承 `yss.cache.active-type`、区域 TTL 或 Redis `failure-mode`。
+
+## 先确认实际入口
+
+- 检查运行时上游 `CacheManager`、local/remote builder、应用自己的 JetCache 配置及实际创建的 area/name。依赖 JAR 中有 `bootstrap.yml` 不证明应用加载了它；无有效 local builder 时，LOCAL 请求可能在运行时失败。
+- 组件兼容包装器的两参数 `getCache` 默认 TTL 为 5 分钟，重载接收 `Duration`；它不设置 `syncLocal`、loader 或刷新策略。包装器的类型映射也不证明 LOCAL 实际采用 Caffeine。需要这些能力时核对原生 `QuickConfig` 与上游管理器。
+- 管理器按 area/name 复用已创建缓存。类型、TTL、`syncLocal` 等参数在第一次创建时确定，后续 `getOrCreateCache` 不会重建同名缓存；修改配置须使用新名称或明确的生命周期切换。
+
+## 跨 JVM 本地失效
+
+原生 `QuickConfig` 选择 `BOTH`、设置 `syncLocal(true)`，并为所有参与节点配置兼容的 `jetcache.remote.default.broadcastChannel`、编码及相同 area/name。包装器即使存在广播频道也不会自行开启 `syncLocal`；缺频道时不能据 `syncLocal(true)` 宣称已同步。
+
+验收时启动两个独立 JVM，在两端创建同名缓存，确认广播订阅实际建立后，从一端更新和删除并观察另一端本地值失效；同时用未同步的对照缓存确认失效范围。广播是异步通知，不承诺强一致或断连期间的持久补偿。
+
+## 故障与数据格式
+
+- 读取 `CacheResult` 状态来区分未命中和故障；便利 `get`/`getValue` 可能将远端故障折叠为 `null`。REMOTE 与 BOTH 的故障结果也不同，不能套用主线 Redis 的 fail-fast/bypass/fallback。
+- JetCache Java 编码保存 `CacheValueHolder`，与 Spring RedisCache 的 JDK 业务值及 RedisTemplate 的 Jackson 值不同。缓存名称、key 前缀或 serializer 迁移前，核对实际物理 key 和兼容方案，避免混写。
+- 包装器不提供主线缓存的事务后提交协调。刷新须核对原生 loader 与 refresh policy 是否同时配置；本轮未验证多节点刷新去重、断连补偿或生产 SLA。

package/template/.agents/skills/yss-cache/references/redis-fallback.md

@@ -1,11 +1,13 @@
 # Redis 故障降级与恢复
 
+以下故障模式和脏 Redis 区域恢复顺序是当前 Boot 3 / Java 17 组件契约。Boot 2 / Java 8 的故障处理和恢复默认值须单独核对其索引及源码。
+
 ## 状态流
 
 ```text
 Redis 健康 -> 命令或健康检查失败 -> 标记不健康 -> 跳过 Redis
 -> 可选 fallback -> 周期健康检查 -> Redis 可连接
--> 清理脏 Redis cache 与本地 fallback cache -> 恢复 Redis
+-> 清理脏 Redis cache；按配置清理本地 fallback cache -> 恢复 Redis
 ```
 
 - fallback 默认关闭，默认目标是 Caffeine。
@@ -13,11 +15,11 @@ Redis 健康 -> 命令或健康检查失败 -> 标记不健康 -> 跳过 Redis
 - Redis 命令级连接故障也会立即报告不健康，不必等待下一轮检查。
 - 只读 fallback 不标记 Redis cache 为脏。
 - put、putIfAbsent、evict、clear、invalidate 和 valueLoader 产生的回退写入会标记为脏。
-- 恢复时先清理降级期间发生写操作的 Redis cache，再清理本地 fallback cache。
+- 恢复时始终先清理降级期间发生写操作的 Redis cache；`clear-fallback-on-recovery=true` 时还清理本地 fallback cache。
 - Redis 失效失败时继续保持不健康状态并在后续检查重试，不能提前切回旧 Redis 数据。
 
 ## 一致性判断
 
 - Caffeine fallback 是每节点独立数据，不能保证跨节点读到相同值。
-- `clear-fallback-on-recovery=false` 会跳过恢复清理，可能重新暴露 Redis 旧值；除非业务明确接受，不要关闭。
+- `clear-fallback-on-recovery=false` 只跳过本地备用缓存清理，不跳过脏 Redis 区域失效。Redis 失效失败时不切回；关闭本地清理仍须评估后续备用使用时的本地旧值窗口。
 - 强一致、锁、幂等状态或余额类数据不应依赖缓存 fallback 保证正确性。

package/template/.agents/skills/yss-cache/references/verification.md

@@ -3,15 +3,17 @@
 ## 组件
 
 ```bash
-./mvnw -f yss-microservice-components/yss-component-cache-parent/pom.xml verify
+./mvnw -f yss-microservice-components/yss-component-cache-parent/pom.xml clean verify
 ```
 
 跨模块测试使用父 reactor 的 `-pl <module> -am`，避免解析本地旧 SNAPSHOT。也可运行：
 
 ```bash
-scripts/verify-cache-component.sh --source-root /path/to/yss-cloud-microservice
+scripts/verify-cache-component.sh --platform-line boot3-java17 --source-root /path/to/boot3/yss-cloud-microservice
 ```
 
+运行前将 `JAVA_HOME` 与 `PATH` 设为所选平台的 JDK（Boot 2 为 Java 8，Boot 3 为 Java 17）；脚本从 `clean verify` 后的每个 cache class 检查 major，无法读取任一 class 即失败。
+
 ## 消费项目
 
 ```bash
@@ -22,13 +24,17 @@ scripts/verify-cache-component.sh --source-root /path/to/yss-cloud-microservice
 
 ## 验收矩阵
 
+通用命中、隔离和失效项适用于所选平台线；下述 `failure-mode`、区域策略、`empty-key-eviction` 与 JetCache 场景核验的是当前 Boot 3 / Java 17 组件。Boot 2 的对应行为按其源码和实际配置另行验证。
+
 - 首次调用执行业务，第二次相同 key 命中缓存。
 - 不同租户/业务 key 不串值。
 - 更新、删除、状态变更后旧值失效。
 - `condition`、`unless` 和异常返回行为符合预期。
 - 默认 TTL 和枚举覆盖 TTL 在后端物理存在。
-- Redis 停止后行为符合 fallback 配置；恢复后旧 Redis 值不会重新出现。
+- Redis 故障时 fail-fast、bypass、fallback 的查询与显式写行为分别符合配置；恢复时脏 Redis 区域必须失效，失效失败不得切回。
+- 区域 TTL/容量/空值策略按实际后端生效；`SimpleKey.EMPTY` 在 legacy-clear 与 evict 下分别执行清区与单 key 删除。
+- JetCache 分别验证包装器与原生 `QuickConfig`：包装器即使配置广播频道也不自动同步本地失效；原生 `BOTH + syncLocal(true)` 在频道、相同 area/name 和订阅生效后，用两个独立 JVM 验证更新、删除与未订阅时的旧值边界；第二次创建不改变首次缓存配置。
 - Sentinel/Cluster 创建正确连接工厂，Cluster 使用 DB 0。
 - Docker 可用时真实 Redis 认证、JSON template、JDK cache serialization 和 TTL 测试实际执行。
-- Java 8 组件 class major version 为 52。
+- 所选 Boot 2 / Java 8 源码 class major 为 52；Boot 3 / Java 17 为 61。两条平台线分别使用匹配的源码根运行脚本，Docker 不可用时单独报告真实 Redis 集成测试未执行。
 - `git diff --check` 通过，消费 starter 构建通过。

package/template/.agents/skills/yss-cache/scripts/verify-cache-component.sh

@@ -1,16 +1,18 @@
 #!/usr/bin/env bash
 set -u
 
+platform_line=""
 source_root=""
 consumer_root=""
 consumer_module=""
 
 usage() {
-  echo "Usage: $0 [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]" >&2
+  echo "Usage: $0 --platform-line <boot2-java8|boot3-java17> [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]" >&2
 }
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
+    --platform-line) [ "$#" -ge 2 ] || { usage; exit 2; }; platform_line=$2; shift 2 ;;
     --source-root) [ "$#" -ge 2 ] || { usage; exit 2; }; source_root=$2; shift 2 ;;
     --consumer-root) [ "$#" -ge 2 ] || { usage; exit 2; }; consumer_root=$2; shift 2 ;;
     --consumer-module) [ "$#" -ge 2 ] || { usage; exit 2; }; consumer_module=$2; shift 2 ;;
@@ -19,21 +21,19 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
+case "$platform_line" in
+  boot2-java8) expected_major=52; configured_root=${YSS_SOURCE_ROOT_BOOT2_JAVA8:-} ;;
+  boot3-java17) expected_major=61; configured_root=${YSS_SOURCE_ROOT_BOOT3_JAVA17:-} ;;
+  *) usage; exit 2 ;;
+esac
+
 if [ -z "$source_root" ]; then
-  source_root=${YSS_SOURCE_ROOT:-}
-fi
-if [ -z "$source_root" ]; then
-  for candidate in "$PWD" "$PWD/.." "$HOME/Projects/yss-cloud-microservice" "$HOME/Documents/yss-project/yss-cloud-microservice"; do
-    if [ -d "$candidate/yss-microservice-components/yss-component-cache-parent" ]; then
-      source_root=$candidate
-      break
-    fi
-  done
+  source_root=$configured_root
 fi
 
 parent="${source_root%/}/yss-microservice-components/yss-component-cache-parent"
 if [ -z "$source_root" ] || [ ! -f "$parent/pom.xml" ]; then
-  echo "ERROR: cannot locate cache parent; use --source-root or YSS_SOURCE_ROOT" >&2
+  echo "ERROR: cannot locate cache parent for $platform_line; use --source-root or its generation-specific YSS_SOURCE_ROOT variable" >&2
   exit 2
 fi
 if [ ! -x "$source_root/mvnw" ]; then
@@ -46,7 +46,7 @@ if { [ -n "$consumer_root" ] && [ -z "$consumer_module" ]; } || { [ -z "$consume
 fi
 
 echo "== Cache reactor verify =="
-(cd "$source_root" && ./mvnw -f "$parent/pom.xml" verify) || exit 1
+(cd "$source_root" && ./mvnw -f "$parent/pom.xml" clean verify) || exit 1
 
 echo "== Docker integration status =="
 report="$parent/yss-component-redis-cache/target/surefire-reports/TEST-com.yss.cloud.cache.redis.config.RedisStandaloneIntegrationTest.xml"
@@ -66,14 +66,14 @@ fi
 
 echo "== Diff whitespace =="
 if command -v git >/dev/null 2>&1 && git -C "$source_root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  git -C "$source_root" diff --check || exit 1
+  git -C "$source_root" diff --check -- yss-microservice-components/yss-component-cache-parent || exit 1
 else
   echo "SKIP: source root is not a Git worktree"
 fi
 
-echo "== Java 8 bytecode =="
-classes=$(find "$parent" -path '*/target/classes/*.class' -type f | head -1)
-if [ -z "$classes" ]; then
+echo "== $platform_line bytecode (major $expected_major) =="
+class_count=$(find "$parent" -path '*/target/classes/*.class' -type f | wc -l | tr -d ' ')
+if [ "$class_count" -eq 0 ]; then
   echo "ERROR: no compiled cache class found" >&2
   exit 1
 fi
@@ -81,12 +81,18 @@ if ! command -v javap >/dev/null 2>&1; then
   echo "ERROR: javap is required for bytecode verification" >&2
   exit 2
 fi
-majors=$(find "$parent" -path '*/target/classes/*.class' -type f -exec javap -verbose {} \; 2>/dev/null | sed -n 's/.*major version: *//p' | sort -u)
-if [ "$majors" != "52" ]; then
-  echo "ERROR: expected only Java 8 major version 52, found: $majors" >&2
+major_lines=$(find "$parent" -path '*/target/classes/*.class' -type f -exec javap -verbose {} \; 2>/dev/null | sed -n 's/.*major version: *//p')
+checked_count=$(printf '%s\n' "$major_lines" | sed '/^$/d' | wc -l | tr -d ' ')
+if [ "$checked_count" -ne "$class_count" ]; then
+  echo "ERROR: javap inspected $checked_count of $class_count compiled cache classes" >&2
+  exit 1
+fi
+majors=$(printf '%s\n' "$major_lines" | sort -u)
+if [ "$majors" != "$expected_major" ]; then
+  echo "ERROR: expected only $platform_line major version $expected_major, found: $majors" >&2
   exit 1
 fi
-echo "PASS: all cache classes use major version 52"
+echo "PASS: all cache classes use major version $expected_major"
 
 if [ -n "$consumer_root" ]; then
   echo "== Consumer build =="

package/template/.agents/skills/yss-distributed-id/SKILL.md

@@ -1,72 +1,28 @@
 ---
 name: yss-distributed-id
-description: "接入或排查 YSS 分布式 ID：Leaf、CosId、号段、雪花算法或 MyBatis 主键注入。"
+description: "接入或排查 YSS 分布式 ID 的 Segment、Snowflake、主键注入与迁移；旧 CosId/远程调用仅按既有平台线分诊。"
 ---
 
 # yss-distributed-id
 
-用于处理 `yss-component-distributed-id` 的配置、接入和问题定位。
+处理 `yss-component-distributed-id` 及 Leaf 消费项目的发号、主键填充与迁移。先从批准的 `platform_configuration.component_platform_line` 选择 [源码索引](references/source-index.md)；Boot 2 的历史能力不能推定为 Boot 3 可用能力。无批准合同的既有工程故障可只读分诊，不据此改策略或宣布兼容。
 
-## 何时使用
+## 接入决策
 
-- 用户要启用分布式 ID。
-- 用户提到 Leaf Segment、Snowflake、CosId、UUID。
-- 用户反馈批量插入未自动注入 ID、ID 冲突、ID 类型不匹配。
+1. 核对实际组件 GAV、平台线、依赖树及当前源码，再确定已有主键策略、注入模式和数据库约束。保持既有 Long 主键及调用方类型，策略变更单独评估数据和 API 影响。
+2. Boot 3 的数值分布式发号使用本地 Leaf Segment / Snowflake；拦截器仍有 String UUID 分支，但它不是数值发号方案。CosId、Feign/远程注入及旧注解参数是迁移分诊线索，不作为新接入选项；Boot 2 维护以其独立源码索引为准。
+3. Boot 3 默认 `local + Segment`：引入组件后核对 DataSource、JDBC 驱动、目标方言建表脚本及 `leaf_alloc`。不发号的应用应显式关闭注入及 Segment；选 Snowflake 时显式启用 Snowflake、关闭 Segment，并验证 worker-id 唯一、时钟回拨处理和节点重启行为。`local` 注入须且只能启用一种算法，不要把 ZooKeeper 当作当前 Snowflake 的默认依赖。
+4. Segment 缺失标签策略、声明、step 和初始水位必须与真实业务表及既有分配记录一致。自动建标签不建表、也不读取业务表最大 ID；迁移前固定停写/切换边界，起点不得低于已分配号段上界，不重置 `leaf_alloc`。
+5. 主键填充同时核对实体注解、插入方法和参数形态。`IdType.AUTO` 保留数据库自增；`ASSIGN_ID` 或显式 Segment/Snowflake 才走组件发号。已有非零值应保留；生成值与 `Long`、十进制 `String`、`Integer` 的转换及溢出必须验证，不能只凭注解推断批量入口已被拦截。
 
-## 工作方式
+## 排障与验证
 
-1. 先识别项目用的是哪种 ID 策略。
-2. 涉及真实类名、配置项、Leaf 服务或批量插入排障时，先读 `references/source-index.md`，再定位源码或文档。
-3. 再看实体注解、拦截器配置和底层表或注册中心依赖是否齐全。
-4. 修改时优先保持现有策略，不轻易切换算法。
+- 启动失败：按自动配置、注入模式、算法开关、DataSource、`leaf_alloc`、方言顺序定位。`disabled` 仅关闭自动注入；完全不用 Segment 时还须核对其算法开关。
+- 重号/错号：核对跨服务业务 tag、控制表唯一键、当前水位、历史号段、Snowflake worker-id 与时钟；先保留现场，不用重建表或清空控制记录排障。
+- 插入缺 ID：核对 `TableId`/生成策略、实体字段类型、当前公开批量方法及 MyBatis 参数包装是否经过拦截器；再检查消费者自定义 `IdentifierGenerator` 是否接管。
+- 行为修改使用组件父 reactor 的根 `./mvnw` 验证启动、单条/批量主键、迁移边界和目标数据库方言；H2 不能证明生产方言。只读故障分诊与已执行验证分别记录。
 
-## 源码索引
-
-- 源码位置不要假设固定目录；先按 `yss-skill-source-index-refresh/references/source-location.md` 定位。
-- 当前技能索引：`references/source-index.md`
-- 重点源码入口通常包括 `EnableDistributedId`、`AutoIdInterceptor`、Leaf 配置、Leaf REST/Feign/gRPC 模块、ID 策略相关类。
-
-当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
-
-## 检查清单
-
-- 启动类是否启用了分布式 ID 能力。
-- 当前策略是否与部署条件匹配。
-- 批量插入链路是否会经过拦截器。
-- 实体主键类型与生成策略是否兼容。
-- Leaf Segment 场景下 `leaf_alloc` 是否已初始化。
-- MyBatis/MyBatis-Plus 的插入方法是否绕过了自动 ID 拦截逻辑。
-- 多服务共享号段时，业务 tag/key 是否唯一且稳定。
-
-## 策略建议
-
-- 追求稳定和趋势递增时，优先 Leaf Segment。
-- 依赖 ZooKeeper 且要求高吞吐时，可考虑 Snowflake。
-- 若项目已有 CosId 统一方案，沿用现有生态。
-- 除非业务明确允许，否则不要把 Long 主键切到 String UUID。
-
-## 修改约束
-
-- 不要混用多种主键生成策略而不说明边界。
-- 不要仅改实体注解而忽略底层配置和依赖。
-- 如果用户只是在做普通 MyBatis-Plus 主键配置，不要过度引入新组件。
-- 不要在已有 Long 主键生态里随意改成 String UUID，除非调用方和数据库约束都确认兼容。
-
-## 排障顺序
-
-1. 确认启用注解和 starter 依赖。
-2. 确认实体主键类型、注解和插入方法。
-3. 确认拦截器是否参与 MyBatis 调用链。
-4. Leaf 场景确认服务、号段表和业务 key。
-5. Snowflake/CosId 场景确认机器号、时钟、注册中心或 worker 分配。
-6. 批量插入失败时确认是否调用了项目推荐批量方法。
-
-## 按需读取
-
-- 源码索引：`references/source-index.md`
-- 拦截器与自动注入：`assets/AutoIdInterceptor.java`
-- 启用注解：`assets/EnableDistributedId.java`
-- Leaf 配置相关：`assets/LeafConf.java`
+当前源码入口与平台差异见 [能力与迁移说明](references/README.md)。不要从 Skill 的历史示例或旧资产复制生产源码；精确类名、配置和默认值以选定平台线的当前源码为准。
 
 ## 平台与源码门禁
 

package/template/.agents/skills/yss-distributed-id/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS Distributed ID"
-  short_description: "Leaf、CosId 与分布式 ID 接入与配置规范"
-  default_prompt: "Use $yss-distributed-id to configure or debug distributed ID generation, Leaf, CosId, and MyBatis ID injection."
+  short_description: "Leaf Segment、Snowflake 与主键注入排障"
+  default_prompt: "Use $yss-distributed-id to configure or debug platform-bound Leaf Segment, Snowflake, and MyBatis ID injection; treat CosId and remote modes as legacy migration cases."

package/template/.agents/skills/yss-distributed-id/references/README.md

@@ -1,51 +1,15 @@
-# 参考资料
+# 分布式 ID 能力与迁移说明
 
-本文档详细介绍了 `yss-component-distributed-id` 框架的核心组件和实现原理。
+本文件只说明选择和核验边界。类名、配置默认值及方法签名以所选平台线的生成索引和匹配的干净源码为准，不复制组件实现。
 
-## 核心类 (Core Classes)
+| 场景 | Boot 3 / Java 17 当前工作树观察 | 核验重点 |
+|---|---|---|
+| Segment | 本地号段；默认 local + Segment | DataSource、目标方言建表、`biz_tag` 唯一键、已分配水位、缺失标签策略 |
+| Snowflake | 本地节点发号；可配置 worker-id，未指定时按节点地址派生 | 所有实例 worker-id 无冲突、时钟回拨和序列等待；不假设 ZooKeeper 注册 |
+| 主键自动填充 | MyBatis 拦截与 MyBatis-Plus `IdentifierGenerator` 两条入口 | `AUTO` 与 `ASSIGN_ID` 区分、已有值保留、批量参数形态、`Integer` 溢出 |
+| String UUID | 本地拦截器仍有 UUID 字符串分支 | 仅核对显式 UUID 策略及 String 字段，不当作 Segment/Snowflake 的数值主键迁移替代 |
+| CosId、Feign/远程注入 | 当前 Boot 3 主线不提供 | 仅对既有项目按其实际平台线和源码做迁移分诊，不把旧模块写成新接入依赖 |
 
-### 1. AutoIdInterceptor.java
-**位置**: `../assets/AutoIdInterceptor.java`
+Segment 从现有业务表接管 ID 时，先记录业务表最大值、`leaf_alloc.max_id` 和尚未用尽的已分配号段，再在停写窗口确定不回退的起点。缺失标签自动创建不会计算这些值；不得删除或重置控制记录。Snowflake 切换需验证新旧机器位语义及所有活跃节点，不在混合写流量时直接换算法。遗留 `feign_segment` 注解仍是明确的拒绝路径，迁移须清理旧注解及依赖，不能用已有非零 ID 掩盖它。
 
-MyBatis 拦截器，是实现自动 ID 注入的核心。
-
-**拦截逻辑**:
-- **拦截点**: `StatementHandler.prepare` 方法。
-- **判断条件**: 仅拦截 `INSERT` 语句。
-- **处理流程**:
-  1. 获取 SQL 绑定的参数对象 (`parameterObject`)。
-  2. 支持处理单对象、`List`、`Array` 和 `Map` (MyBatis 多参数封装)。
-  3. 遍历参数对象的实体类，检查是否有 `@Entity` (JPA) 或 `@TableName` (MP) 注解。
-  4. 扫描实体字段，查找 `@GeneratedValue` 或 `@TableId` 注解。
-  5. 根据注解指定的策略 (`segment`, `snowflake`, `cosid_segment` 等)，调用对应的 ID 生成器获取 ID。
-  6. 通过反射将 ID 设置到实体的相应字段中。
-
-### 2. EnableDistributedId.java
-**位置**: `../assets/EnableDistributedId.java`
-
-开启分布式 ID 功能的注解。
-
-**属性**:
-- `autoRegister`: 是否自动注册配置，默认为 `true`。
-- `cosid`: 是否开启 CosId 模式，默认为 `false` (即默认使用 Leaf 模式)。
-
-**作用**:
-- 导入 `LeafDataSourceConfiguration` 和 `EnableDistributedImportSelector`，从而根据配置加载相应的 Bean。
-
-### 3. LeafConf.java
-**位置**: `../assets/LeafConf.java`
-
-Leaf 模式的配置类，对应 `spring.leaf` 配置项。
-
-**属性**:
-- `leafSegmentEnable`: 是否开启号段模式。
-- `leafSnowflakeEnable`: 是否开启雪花算法模式。
-
-## ID 生成策略详解
-
-| 策略名称 | 依赖组件 | 描述 | 适用场景 |
-| :--- | :--- | :--- | :--- |
-| **Leaf Segment** | DB (MySQL) | 基于数据库号段，每次从 DB 获取一个号段到内存，高性能，ID 趋势递增。 | 大多数业务场景，高可用要求高。 |
-| **Leaf Snowflake** | Zookeeper | 基于 Twitter 雪花算法，依赖 ZK 进行 WorkerID 管理。 | 对 ID 生成速度要求极高，且不依赖 DB 的场景。 |
-| **CosId Segment** | DB (MySQL) | CosId 的号段模式实现，支持更丰富的配置（如步长动态调整）。 | 需要 CosId 特性或作为 Leaf 的替代方案。 |
-| **UUID** | JDK | 标准 UUID。 | 无需有序、不关心存储空间的场景。 |
+只读分诊可参考当前组件 `readme.md` 和源码路径提示；组件子树 dirty、索引 tree 不一致或兼容证据未 verified 时，这些观察不构成精确接入或发布结论。

package/template/.agents/skills/yss-implementation-contract-compiler/SKILL.md

@@ -5,6 +5,8 @@ description: "编译或重验 YSS Slice Implementation Contract、最小 Skill
 
 # YSS Implementation Contract Compiler
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 阶段 7 的实现合同编译器。它把已批准的生命周期资产、垂直切片、capability 和窄 Recipe 编译为 `Slice Implementation Contract` v3 草案；不批准合同、不写业务代码、不设置 `ready-for-agent`。
 
 文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。

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

@@ -33,6 +33,18 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 <!-- yss-rule {"id":"mybatis.transaction","when":"mybatis","level":"mandatory","evidence":"code-and-verification"} -->
 - 事务边界归批准的 Application 用例或 MVC service/core；Repository 不临时声明新的业务事务。
 
+## 能力选择记录
+
+| 既有工程调用 seam | 选择与核验 |
+|---|---|
+| `PageQuery` 经组件切面进入 Repository/Gateway | 核对代理切点、参数位置、PageHelper 开关、实际 SQL 与 `tempTotalCount`；不能因 Bean 注册就认定切面命中。 |
+| Mapper 使用 MyBatis-Plus `IPage` | 核对 MP 分页开关、方言、实际 SQL 与 total；同一次查询不得叠加 PageHelper 上下文。两插件都注册不等于查询已双分页。 |
+| 原生 Mapper/Example/ListMapper | 按当前源码和实体映射选择 `BaseRepository<T,D>`；与完整 MP `BasePlusRepository<T>` 不可直接互换，混用或复合键须验证主键方法、XML 与映射。 |
+| SQL 级批量写入 | 核对公开入口、分片大小、目标方言生成的单批 SQL、审计填充和 ID；多个分片整体回滚由上层用例事务保证。若 batch size 存在进程级可变状态，多 Spring Context 不得据此宣称配置隔离。 |
+| 命名数据源 | Holder 中有多个 DataSource 不证明动态路由；记录实际 Mapper 的 `SqlSessionFactory`/DataSource、主池与自建池所有权，以及事务绑定。 |
+
+以上仅对命中的能力记录，不改变两套分页插件的当前默认注册行为；选择由批准 Profile、消费工程配置和运行测试共同证明。
+
 ## 任务分流
 
 | 请求 | 本 Skill 动作 | 后续路由 |
@@ -48,8 +60,8 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 2. 装配与开关：自动配置、条件属性、Mapper 扫描和 XML location 是否真实生效。
 3. 调用 seam：代理是否命中、分页参数位置/类型、分页插件链和 total 回填责任。
 4. 映射：接口签名、XML namespace、resultMap、字段、逻辑删除和主键策略。
-5. 批量：是否调用当前公开批量入口、分批与方言是否匹配、是否退化为循环单条。
-6. 数据源：先确认组件只提供了什么，再检查上层路由与事务进入顺序；不得假设存在当前线程数据源上下文。
+5. 批量：是否调用当前公开批量入口、分批与方言是否匹配、是否退化为循环单条；核对 batch size 在多个应用上下文中的作用域。
+6. 数据源：先确认组件只提供了什么，再检查 Mapper 实际绑定的会话工厂、上层路由与事务进入顺序；不得假设存在当前线程数据源上下文。
 7. 最后检查 SQL、绑定参数、数据库方言与执行计划。
 
 ## Review 输入

package/template/.agents/skills/yss-openapi-draft-review/SKILL.md

@@ -5,6 +5,8 @@ description: "审查 YSS OpenAPI Draft 的需求覆盖、页面动作、响应
 
 # YSS OpenAPI Draft Review
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 Use this skill after OpenAPI Draft creation and before Engineering Baseline / YSS DDD Review. It is a fail-closed contract review skill for design-time OpenAPI files under `docs/.scratch/<feature>/api/`; it does not bundle JSON or generate Orval clients.
 
 ## Required Inputs

package/template/.agents/skills/yss-openapi-governance/SKILL.md

@@ -5,6 +5,8 @@ description: "维护、校验、冻结或导出 YSS OpenAPI 3.1 设计合同；
 
 # YSS OpenAPI Governance
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 本 skill 负责 YSS OpenAPI 的 **YAML-first** 工作流：
 
 ```text
@@ -114,3 +116,5 @@ pnpm exec redocly bundle \
 ## 输出契约
 
 执行治理或导出时，按 [输出契约](references/governance-output.md) 记录 YAML 权威、当前校验证据、JSON 派生与交接。不能只给自然语言完成声明；未冻结时不生成可供实现消费的 JSON。
+
+API Contract Decision 可用 `scripts/api-contract-decision prepare` 自动生成来源摘要；v1 显式迁移用 `migrate --version <新版本> --output <新路径>`。候选保持 draft，审查、Freeze 绑定和工程契约批准仍由现有生命周期核验。

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

@@ -1,11 +1,13 @@
 ---
 name: yss-product-lifecycle
-description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术契约、垂直切片实现、审查、发布和复盘；当阶段、产物、门禁或 YSS skill 不清晰时使用。
+description: 编排 YSS 研发全生命周期；当阶段、产物、门禁或 Skill 路由不清晰时使用。
 ---
 
 # YSS Product Lifecycle
 
-生命周期单一主控：识别请求、仓库身份和最近可信阶段，计算可执行 frontier，派发并验收工作单元；业务设计、实现和独立审查交给专项 skill。
+合同阅读：`scripts/contract view`；见 `docs/process/contract-reading.md`。
+
+主控识别请求、仓库身份和可信阶段，计算 frontier、派发与验收工作单元；专项 Skill 负责设计、实现和独立审查。
 
 文档按 `document_writing` 条件调用 `i-have-adhd`，并传递 `docs/process/document-writing.md` 规范。
 
@@ -21,7 +23,7 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 | 数字人角色、运行时和会签策略 | `docs/agents/digital-human-roles.yaml` |
 | 影响面、裁剪和模板维护强度 | `docs/process/harness-process-tailoring.md`、`docs/process/maintenance-intensity.yaml` |
 
-使用 `scripts/query-lifecycle-context` 获取确定性 JSON 投影，不要为普通路由整份读取编排合同：
+用 `scripts/query-lifecycle-context` 查询合同：
 
 ```bash
 scripts/query-lifecycle-context --mode route --stage stage.plan --work-unit work-unit.plan-requirements --include execution_efficiency
@@ -54,6 +56,8 @@ Plan 入口读取 `docs/plan/README.md` 和 `docs/process/plan-migration.md`，
 
 聚合批准见 `gate_consolidation`。普通功能默认一个独立审查者，按能力缺口、冲突或外部制度增员；相邻检查组合审查、逐项留证。
 
+项目职责与后端终点见 `execution_scopes`；恢复、编译和派发必须复验。保留产品设计门禁，后端交付不等于业务完成或发布。
+
 ### 用户决定
 
 按角色表 `user_decision_policy` 和 `references/user-decisions.md` 先展示可审阅资产、范围、风险及后续动作，再取得提问者或其指定生物人的原始回复。数字人、超时和默认项不能代答。已有授权优先用 `continuation_ref` 核验延续；未知/实质变化或强制审批缺失才重新决定。缺陷和缺证据阻断，建议记待办；合同、验证及外部动作授权仍须满足。
@@ -71,7 +75,7 @@ Plan 入口读取 `docs/plan/README.md` 和 `docs/process/plan-migration.md`，
 5. 先对照用户目标逐项验收，检查遗漏诉求、错误假设与尚未解决的问题，再验收 `Workflow Execution Result`：工作单元、合同、允许写路径、`context_reconciliation`、证据、实际验证、延期 seam、漂移和下一路由必须可核验。实现派发额外绑定当前 Slice Implementation Contract v3；其他阶段不得伪造该合同。
 6. 在授权边界内继续下一工作单元；遇到人工决定、新授权、证据冲突、专项失败或合并/发布结论时暂停。暂停不得阻断无依赖的独立工作。
 
-每个 `project-instance` 工作单元在申请批准或流转前，先把稳定术语回写到根目录唯一 `CONTEXT.md`，并生成通过校验的 `context_reconciliation`。候选术语、错误路径、摘要漂移或未决冲突必须阻断。质量标准只由 `engineering-baseline` 定义一次；高风险影响按裁剪合同补充反证和残余风险。
+每个 `project-instance` 工作单元批准或流转前，回写稳定术语到唯一根 `CONTEXT.md`，并生成通过校验的 `context_reconciliation`。候选术语、错误路径、摘要漂移或未决冲突必须阻断。质量标准只由 `engineering-baseline` 定义一次；高风险影响按裁剪合同补充反证和残余风险。
 
 ## 面向业务角色
 
@@ -85,10 +89,12 @@ Plan → Spec（含正式草稿、恢复与显式 `to-spec`）写入前，按 `d
 
 ## 结果与暂停
 
-普通咨询直接回答，不创建流程产物；复杂请求简述目标与下一步。实际工作单元仍记录完整结果，按适用边界同步，对外仅展示当前决定所需信息。
+咨询直接回答；工作单元保留完整结果，对外仅展示当前决定所需信息。
 
 工作单元结果至少包含：模式、仓库身份、当前阶段和工作单元、影响面、资产与门禁状态、证据、新鲜度、Ticket/垂直切片/合同状态、`ready-for-agent` 结论、阻塞项、本轮动作、下一工作单元、暂停或继续理由、Ticket 同步和 Git checkpoint 判断。
 
 暂停会签时追加门禁 ID、`role_id`、`runtime_id`、会签文件路径、推荐答案和恢复动作；恢复前运行适用验证器。只有同一候选快照通过全部适用审查轴与 fresh verification，才能提出合并、发布或完成结论；发布仍须生物人决定。
 
 专项合同加载索引见 `references/orchestration.md`。
+
+Plan / Spec / Design 追踪按 `docs/process/stage-tracking.md`。