create-yss-spec 3.4.10 → 3.5.0

package/template/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -286,7 +286,7 @@ task_package:
 # may prepare, validate and accept their results, but cannot invoke them or create
 # their formal artifacts on their behalf.
 matt_invocation_boundary:
-  user_invoked_skills: [grill-me, grill-with-docs, handoff, implement, improve-codebase-architecture, setup-matt-pocock-skills, to-questionnaire, to-spec, to-tickets, triage, wait-what, wayfinder]
+  user_invoked_skills: [grill-with-docs, handoff, implement, improve-codebase-architecture, setup-matt-pocock-skills, to-questionnaire, to-spec, to-tickets, triage, wait-what, wayfinder]
   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, prototype, resolving-merge-conflicts, tdd, writing-for-agents, yss-research]
   lifecycle_allowed_model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, prototype, tdd, yss-research]
@@ -299,7 +299,7 @@ skill_source_contract:
   lock_version: 3
   source_revisions_required: [mattpocock/skills, iloveZzz/yss-ui]
   adaptation_ref_required_when_effective_diff: true
-  retired_shared_skills: [yss-antd-design, yss-antdv-next-design, ask-matt, batch-grill-me, dispatching-parallel-agents, loop-me, migrate-to-shoehorn, product-design-prototype, prototype-page-acceptance, scaffold-exercises, setup-pre-commit, setup-ts-deep-modules, teach, writing-beats, writing-fragments, writing-shape, yss-components, yss-dictionary, yss-jdbc, yss-log, yss-microapp-commit, yss-mvc-scaffold-generator, yss-mvc-design, yss-mvc-data-analysis-project-initializer, yss-backend-scaffold-parent, yss-page-module-development, yss-taskflow, yss-backend-scaffold-application, yss-backend-scaffold-domain, yss-backend-scaffold-infrastructure, yss-backend-scaffold-web, yss-backend-scaffold-adapter, yss-application-layer-reference, yss-domain-layer-reference, yss-infrastructure-layer-reference, yss-web-layer-reference]
+  retired_shared_skills: [yss-antd-design, yss-antdv-next-design, ask-matt, batch-grill-me, grill-me, dispatching-parallel-agents, loop-me, migrate-to-shoehorn, product-design-prototype, prototype-page-acceptance, scaffold-exercises, setup-pre-commit, setup-ts-deep-modules, teach, writing-beats, writing-fragments, writing-shape, yss-components, yss-dictionary, yss-jdbc, yss-log, yss-microapp-commit, yss-mvc-scaffold-generator, yss-mvc-design, yss-mvc-data-analysis-project-initializer, yss-backend-scaffold-parent, yss-page-module-development, yss-taskflow, yss-backend-scaffold-application, yss-backend-scaffold-domain, yss-backend-scaffold-infrastructure, yss-backend-scaffold-web, yss-backend-scaffold-adapter, yss-application-layer-reference, yss-domain-layer-reference, yss-infrastructure-layer-reference, yss-web-layer-reference]
 
 # 生命周期默认走原生工作单元；Matt user-invoked skill 仅保留为兼容入口。
 lifecycle_native_entries:
@@ -1076,7 +1076,7 @@ impact_propagation:
     targets:
       - {kind: artifact, name: product-design, level: direct, when: ui_impact}
       - {kind: artifact, name: prototype, level: direct, when: ui_impact}
-      - {kind: gate, name: requirement-freeze, level: direct, when: ui_impact}
+      - {kind: gate, name: gate.product-design-approved, level: direct, when: ui_impact}
       - {kind: artifact, name: openapi-draft, level: transitive, when: api_impact}
       - {kind: gate, name: openapi-freeze, level: transitive, when: api_impact}
       - {kind: artifact, name: vertical-slice-tickets, level: transitive, when: always}
@@ -1097,7 +1097,8 @@ impact_propagation:
       - {kind: artifact, name: product-design, level: direct, when: ui_impact}
       - {kind: artifact, name: system-architecture, level: direct, when: always}
       - {kind: artifact, name: data-architecture, level: direct, when: data_impact}
-      - {kind: gate, name: requirement-freeze, level: direct, when: always}
+      - {kind: gate, name: gate.spec-baseline-approved, level: direct, when: always}
+      - {kind: gate, name: gate.product-design-approved, level: direct, when: ui_impact}
       - {kind: artifact, name: openapi-draft, level: transitive, when: api_impact}
       - {kind: gate, name: design-review, level: transitive, when: always}
       - {kind: gate, name: openapi-freeze, level: transitive, when: api_impact}

package/template/.pi/skills/yss-product-lifecycle/references/state-model.md

@@ -83,17 +83,17 @@ Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorizat
 lifecycle:
   schema_version: 1
   mode: resume
-  stage: system-data-architecture-and-contract-review
-  status: blocked
+  stage: stage.spec-architecture
+  status: needs-human
 workflow:
   matt_flow: main
-  active_skill: yss-openapi-draft-review
+  active_skill: yss-product-lifecycle
   status: paused
 artifacts:
-  spec: {status: approved, ref: docs/.scratch/example/spec.md}
+  spec: {status: ready-for-human, ref: docs/.scratch/example/spec.md}
   openapi: {status: stale, ref: docs/.scratch/example/api/example.yaml, stale_by: [spec]}
 gates:
-  openapi_freeze: {status: stale}
+  gate.spec-baseline-approved: {status: needs-human}
 tracker:
   kind: local-markdown
   root: docs/.scratch
@@ -101,10 +101,10 @@ tracker:
   role: ready-for-human
 pause:
   reason_code: human-gate
-  gate_ref: requirement-freeze
+  gate_ref: gate.spec-baseline-approved
   owner_or_authority: product-owner
-  resume_condition: requirement-freeze-approved
-  next_work_unit: api-impact-assessment
+  resume_condition: gate.spec-baseline-approved approved
+  next_work_unit: work-unit.technical-analysis
 ```
 
 ## Schema 兼容与迁移

package/template/.pi/skills/yss-prototype-stage/SKILL.md

@@ -53,7 +53,7 @@ Design QA 合并 visual、layout、interaction、content、accessibility、cross
 ## 按需读取
 
 - 档位、上游融合与迁移：[prototype-profile-routing.md](references/prototype-profile-routing.md)
-- 渲染适配、fact pack 与命令：[product-design-adapter.md](references/product-design-adapter.md)
+- 离线渲染适配与命令：[product-design-adapter.md](references/product-design-adapter.md)
 - 证据模板：`docs/design/templates/prototype-evidence-template.yaml`
 - Visual Baseline 模板与 schema：`docs/design/templates/visual-baseline-template.yaml`、`docs/design/schemas/visual-baseline.schema.json`
 
@@ -61,7 +61,7 @@ Design QA 合并 visual、layout、interaction、content、accessibility、cross
 
 - 把 H1/H2 当作低/高保真；把离线 HTML 降为静态截图，或继续要求 Provider、Node starter、预先生成图片。
 - 低保真未评审就选择技术栈；用主观评分代替确定性触发规则。
-- 空填 lockfile/fact pack；把自身生成图当成独立来源，或宣称已验证生产真实组件。
+- 编造组件版本或构建来源；把自身生成图当成独立来源，或宣称已验证生产真实组件。
 - 重复抄写机器可采集的版本、digest、截图和 console；创建第二份状态机、QA 或 handoff 资产。
 - 把原型源码直接复制进生产，或在原型阶段调用 `yss-ui`。
 

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

@@ -29,6 +29,7 @@ description: 用于按批准的 YSS 架构与持久化合同实现或重构 PO
 <a id="repository.mapping"></a>
 <!-- yss-rule {"id":"repository.mapping","when":"persistence","level":"mandatory","evidence":"code-and-verification"} -->
 - 数据合同必须显式覆盖主键、逻辑删除、审计字段、空值、枚举/值对象映射和敏感字段；动态排序、分组与过滤必须使用批准白名单和参数绑定。
+- 数据合同选择 YSS 分布式主键时，记录已选 `component.distributed-id` 绑定、Segment/Snowflake 策略、实体主键类型与批量插入路径，并消费 `yss-distributed-id` 的当前平台证据；不由 Repository 自行切换算法或创建发号合同。
 <a id="repository.transaction"></a>
 <!-- yss-rule {"id":"repository.transaction","when":"persistence","level":"mandatory","evidence":"code-and-verification"} -->
 - 事务归所选 Profile 的用例边界。Repository/Gateway Adapter 不临时新增业务事务，也不把数据库异常原文或凭据暴露给上层。

package/template/README.md

@@ -98,22 +98,20 @@ scripts/verify-template-fast
 
 ## 关键文档
 
+业务方可从[用户手册](./docs/user-guide/用户手册.md)了解工作入口；阶段、条件门禁和完成证据以生命周期注册表及流程裁剪规则为准。
+
 | 文档 | 内容 |
 |------|------|
 | [AGENTS.md](./AGENTS.md) | 全局 AI 指令 + 工程基线入口 + Agent 协作 |
 | [docs/user-guide/用户手册.md](./docs/user-guide/用户手册.md) | 从首次只读检查到需求、开发、审查、发布和 CLI 操作的统一用户手册 |
 | [阶段接入与产物复用使用手册](./docs/user-guide/阶段接入与产物复用使用手册.md) | 复用上游资产，从指定入口继续；含后端交付后前端开发操作 |
-| [docs/process/PDCA-SCRUM.md](./docs/process/PDCA-SCRUM.md) | PDCA × Scrum × AI |
 | [docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md](./docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md) | Matt Pocock Engineering Skills 集成与使用 |
 | [docs/process/lifecycle-registry.yaml](./docs/process/lifecycle-registry.yaml) | 生命周期结构事实源：主阶段、门禁、产物、工作单元、证据与稳定 ID |
 | [docs/process/harness-process-tailoring.md](./docs/process/harness-process-tailoring.md) | 小改动 / 中等变更 / 新模块的流程裁剪指南 |
-| [docs/process/harness-executive-blueprint.md](./docs/process/harness-executive-blueprint.md) | 面向业务方和管理者的 Harness 一页式蓝图 |
 | [docs/process/implementation-repo-integration.md](./docs/process/implementation-repo-integration.md) | 外部前端 / 后端实现仓库接入与跨仓库切片绑定 |
 | [docs/agents/README.md](./docs/agents/README.md) | Agent 协作文档目录说明 |
 | [docs/user-guide/yss-ui-mcp.md](./docs/user-guide/yss-ui-mcp.md) | YSS UI MCP 项目配置、全局安装边界与自检 |
-| [docs/plan/IDEATION.md](./docs/plan/IDEATION.md) | 机会构想方法 |
 | [docs/architecture/README.md](./docs/architecture/README.md) | 架构设计 + 审查清单 |
-| [docs/testing/README.md](./docs/testing/README.md) | 测试策略 |
 
 ## 核心模板
 
@@ -122,7 +120,6 @@ scripts/verify-template-fast
 | [docs/templates/spec-template.md](./docs/templates/spec-template.md) | Spec，包含 OpenAPI 影响、测试决策、AI / 人工审查点 |
 | [docs/templates/local-parent-ticket-template.md](./docs/templates/local-parent-ticket-template.md) | Local Markdown 功能父 Ticket 与生命周期索引 |
 | [docs/templates/vertical-slice-ticket-template.md](./docs/templates/vertical-slice-ticket-template.md) | 垂直切片 Ticket |
-| [docs/templates/agent-brief-template.md](./docs/templates/agent-brief-template.md) | `triage` 产出的 Agent Brief |
 | [docs/templates/implementation-repo-registry-template.md](./docs/templates/implementation-repo-registry-template.md) | 外部实现仓库登记 |
 | [docs/templates/cross-repo-slice-template.md](./docs/templates/cross-repo-slice-template.md) | 跨仓库垂直切片记录 |
 | [docs/architecture/templates/architecture-deepening-template.md](./docs/architecture/templates/architecture-deepening-template.md) | 架构 deepening 候选与 seam 设计 |

package/template/docs/agents/skill-migrations.md

@@ -2,6 +2,10 @@
 
 本文记录已退役技能入口的迁移路径。退役技能不保留物理目录、投影或 lock 条目；本文件是历史名称的唯一持久兼容说明。
 
+## `grill-me` 入口退役（2026-09-24）
+
+`grill-me` 仅转发到 `grilling`，现已硬退役。新请求直接使用 `grilling`；旧 ID 返回 `skill-retired`，不保留兼容目录、投影、Registry 或 lock 条目。历史候选与冻结证据只读保留。
+
 ## 后端组件源码索引双轨迁移（2026-09-19）
 
 后端组件 Skill 的单一 `references/source-index.md` 已迁移为平台线选择页。生成证据分别保存在 `source-index.boot2-java8.md` 与 `source-index.boot3-java17.md`，来源根分别由 `YSS_SOURCE_ROOT_BOOT2_JAVA8` 与 `YSS_SOURCE_ROOT_BOOT3_JAVA17` 显式提供。

package/template/docs/agents/yss-skill-registry.yaml

@@ -6,6 +6,13 @@ description: >-
   单一可执行注册表。实现合同编译器与生命周期编排器只消费通过本表校验的
   canonical 技能；skills-lock.json 继续独立持有来源、hash 与投影完整性。
 canonical_content_root: .agents/skills
+instance_distribution:
+  schema_version: 1
+  initial_skills: [yss-product-lifecycle, yss-research, i-have-adhd]
+  runtimes: [codex, cursor, pi]
+  projection_roots: { codex: .codex/skills, cursor: .cursor/skills, pi: .pi/skills }
+  dependency_types_for_ensure: [context-required, context-conditional]
+  initial_example_docs: false
 backend_skill_domains:
   schema_version: 1
   scope: active-yss-backend-capability-owners
@@ -354,12 +361,6 @@ skills:
     instance_default_discoverable: true
     aliases: []
     impacts: [discovery]
-  - id: grill-me
-    layer: compatibility
-    maturity: supported
-    instance_default_discoverable: false
-    aliases: []
-    impacts: [discovery]
   - id: grill-with-docs
     layer: compatibility
     maturity: supported

package/template/docs/design/README.md

@@ -46,7 +46,6 @@ Token 或组件视觉变体变更必须先修改 `DESIGN.md`，再更新派生
 - `product-design:index`：Codex 产品原型产出的主路由；根据输入是否有 URL、截图、Figma、代码目标或视觉方向，进入 `$get-context`、`$ideate`、`$prototype`、`$image-to-code`、`$url-to-code`、`$share` 或 `$design-qa` 等 focused skill。
 - Product Design focused skills：按 H1/H2 的问题边界产出视觉或流程设计资产；ideation 只在新/不确定视觉方向时强制。
 当前原型使用 `yss-prototype-stage` 的离线 HTML 适配器；历史 Provider 证据保持只读。
-当前原型使用 `yss-prototype-stage` 的离线 HTML 适配器；历史 Provider 证据保持只读。
 - `prototype-review`：原型阶段评审门禁；未通过则不要进入 Spec 校准 / API 影响分析 / 契约草案。
 - 兼容入口：`product-design-prototype`、`high-fidelity-html-prototype` 只读迁移；新资产统一使用 `artifact.prototype-deliverable`、`yss-prototype-stage`、Prototype Evidence schema v4 与 Visual Baseline schema v1。
 

package/template/docs/design/design.md

@@ -35,13 +35,13 @@
 
 ## 原型设计依据的优先级
 
-原型使用 Ant Design 或 Antdv Next 时，上游 `design.md` 与组件查询提供的是**上游默认**和组件事实；项目根 `DESIGN.md` 是**规范覆盖**，`docs/design/design.md` 是治理解释，`docs/design/tokens/*` 是派生实现视图。当前功能只能在这些层之下完成语义组件映射。若上游默认与项目 Token 不同，以根规范源为准，并在 `prototype-evidence.yaml` 中记录根规范与 Token digest；不得把上游默认直接写回项目实现。
+当前原型以项目根 `DESIGN.md` 为视觉规范源，`docs/design/design.md` 解释治理规则，`docs/design/tokens/*` 是派生实现视图。需要真实 AntD 控件辅助评审时，上游资料只提供组件事实，不覆盖项目规范；在 `prototype-evidence.yaml` 中记录根规范与 Token digest，不把上游默认直接写回项目实现。
 
 项目覆盖与官方默认的差异直接读取根 `DESIGN.md` 并用 `design-md diff` 核验；本文件不复制差异值。上游预设色板可以保留其自身颜色谱，但**色板预设 ≠ 品牌 seed**。
 
 Codex `$design-qa` 的 Colors/tokens 与 Fonts/typography 对照必须以根 `DESIGN.md` 为 source visual truth，并用 `docs/design/tokens/*` 复核实际投影；不得回退到上游默认或历史品牌值。执行清单见 `.agents/skills/yss-design-system/references/design-qa-theme.md`。
 
-原型 H1/H2 统一使用 `html-css-js`，以本地 Token CSS 保留 YSS 企业后台视觉语言。生产实现只在目标工程按 lockfile 核验组件 API；原型阶段不调用 `yss-ui`。已冻结的组件库原型和 fact pack 保留历史只读，不再生成新的 Provider 事实包。
+原型 H1/H2 默认使用 `html-css-js`，以本地 Token CSS 保留 YSS 企业后台视觉语言；复杂交互影响评审结论时可按集成说明选用 `react-antd-prebuilt`。生产实现只在目标工程按 lockfile 核验组件 API；原型阶段不调用 `yss-ui`。已有项目中冻结的组件库原型及其事实证据保持只读；模板不再预置 Antdv Next fact pack，也不生成新的 Provider 事实包。
 
 ### HTML 与生产主题的映射
 

package/template/docs/design/templates/interaction-spec-template.md

@@ -106,7 +106,7 @@
 - 每个表格列、筛选条件、表单字段、抽屉、弹窗和按钮都有数据来源或契约反推说明。
 - 设计可以拆成独立可演示的垂直切片。
 - 低保真评审通过后，记录档位触发与待确认决定；H1 覆盖视觉和少量交互，H2 覆盖主流程/关键异常。
-- H2 只有实际使用 React AntD 且 fact pack 不新鲜时才执行增量 CLI 查询；H1 不创建 AntD 证据。任何原型档位都不得调用 `yss-ui` 或声明已验证真实生产组件。
+- H2 仅在复杂交互影响评审结论且选用 `react-antd-prebuilt` 时，记录精确组件版本、选择理由与预构建来源；H1 不创建组件库证据。任何原型档位都不得调用 `yss-ui` 或声明已验证真实生产组件。
 
 ## 9. 决策与未决问题