create-yss-spec 1.1.4 → 2.0.0

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

@@ -1,73 +1,44 @@
 ---
 name: yss-cache
-description: 用于 YSS 缓存框架的接入、配置和排障。当用户提到 QueryCache、UpdateCache、ClearCache、多级缓存、Redis/Caffeine 切换、JetCache 或缓存不生效时调用。
+description: 用于 YSS 缓存框架的接入、配置、代码修改和故障诊断。Use when tasks involve QueryCache、UpdateCache、ClearCache、TTL、SpEL key、事务提交后缓存操作、Redis/Caffeine/Hazelcast 后端切换、Redis Standalone/Sentinel/Cluster、Jedis 连接池、Redis fallback、JetCache、多级缓存、序列化兼容、缓存不命中或失效不一致。
 ---
 
 # yss-cache
 
-用于处理 `yss-component-cache-parent` 相关的缓存接入、配置修复和使用规范问题。
+处理 `yss-component-cache-parent` 及其消费项目的缓存任务。
 
-## 何时使用
+## 工作流
 
-- 用户要新增或修改缓存注解。
-- 用户提到 `@QueryCache`、`@UpdateCache`、`@ClearCache`。
-- 用户在排查 Redis、Caffeine、JetCache、多级缓存切换问题。
-- 用户反馈缓存命中异常、缓存未失效、Redis 不可用时降级异常。
+1. 按 `yss-source-index/references/source-location.md` 定位真实源码。当前工作区有 `.codegraph/` 时先用 CodeGraph；否则读取 [source-index.md](references/source-index.md) 后用符号或 Maven 模块搜索。
+2. 识别使用模型：Spring Cache 单后端路由、Redis 故障降级，或 JetCache local + remote。不要混用三者的行为假设。
+3. 明确缓存名、key、TTL、更新/删除路径、跨节点一致性和序列化兼容要求。
+4. 先检查现有依赖、启动注解、配置和注解用法，再决定修改业务代码、配置还是组件。
+5. 修改后执行对应 reference 的验证；组件跨模块修改必须从父 reactor 构建，不要依赖本地旧 SNAPSHOT。
 
-## 工作方式
+## 不变量
 
-1. 先识别项目当前用的是 Spring Cache 扩展、Redis/Caffeine/Hazelcast 后端还是 JetCache 扩展。
-2. 涉及真实类名、配置项、模块依赖或排障时，先读 `references/source-index.md`，再定位源码或文档。
-3. 先查现有配置与注解用法，再决定是否改代码、改配置或两者都改。
-4. 只围绕当前问题解释缓存策略、key、失效与降级，不输出整套框架宣传材料。
+- 新增查询缓存时同时覆盖更新、删除和状态变更的失效路径。
+- key 必须稳定并显式包含租户、机构、账套等隔离维度；不要依赖 DTO 的不稳定序列化结果。
+- 不要把 Redis fallback 当作正常二级缓存。Caffeine fallback 存在节点间不一致窗口。
+- 不要声称纯 Redis 后端会广播本地缓存失效。只有确认 JetCache 配置了 local、remote 和 broadcast channel 后才能作此判断。
+- 不要在没有双读、版本前缀、灰度清理或迁移窗口时修改 serializer、key prefix 或 cache name。
+- 不明确一致性要求时，不默认启用本地缓存或 fallback。
 
-## 源码索引
+## 按场景读取
 
-- 源码位置不要假设固定目录；先按 `yss-source-index/references/source-location.md` 定位。
-- 当前技能索引：`references/source-index.md`
-- 重点源码入口通常包括 `EnableYssCloudCache`、`EnableYssCloudRedisCache`、`YssCacheInterceptor`、`YssCacheProperties`、`YssCacheAnnotationParser`、`QueryCache`、`UpdateCache`、`ClearCache`、各缓存后端 Provider/Resolver。
+- 模块、后端选择或多级缓存边界：[architecture.md](references/architecture.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)
+- Redis 故障、fallback、恢复清理和一致性：[redis-fallback.md](references/redis-fallback.md)
+- RedisTemplate/RedisCacheManager 数据格式或迁移：[serialization.md](references/serialization.md)
+- 缓存不生效、未失效、启动失败、Redis 异常：[troubleshooting.md](references/troubleshooting.md)
+- 完成修改后的组件与消费项目验收：[verification.md](references/verification.md)
 
-当组件源码变化后，用 `yss-source-index` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
+## 工具
 
-## 检查清单
+- `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/check-skill-freshness.sh [source-root]`：比较技能契约与当前组件源码；发现漂移返回 1。
 
-- 启动类是否开启了缓存能力。
-- 当前启用的是 `redis` 还是 `caffeine`。
-- 缓存 key 是否稳定且能表达业务唯一性。
-- 更新和删除路径是否同时处理了缓存刷新或失效。
-- 读方法是否被 Spring 代理调用，而不是类内自调用绕过 AOP。
-- Redis 异常时是否有预期中的降级路径。
-- 多级缓存场景下，本地缓存和远端缓存的一致性边界是否被业务接受。
-- key 中涉及用户、租户、机构、账套等上下文时，是否显式纳入 key 设计。
-
-## 实施建议
-
-- 查询接口优先用 `@QueryCache`。
-- 更新接口优先用 `@UpdateCache` 或显式失效。
-- 删除或状态变更接口优先用 `@ClearCache`。
-- 对跨节点一致性要求高的场景，优先确认是否需要 JetCache 或 Redis 广播。
-- 读多写少、允许短暂不一致的场景才考虑本地缓存。
-- 多服务共享缓存时，优先复用项目既有缓存 key 常量、枚举或命名约定。
-
-## 排障顺序
-
-1. 依赖和启动注解是否引入正确。
-2. 配置项是否启用了预期缓存后端。
-3. 目标方法是否能被 Spring AOP 代理。
-4. 注解 key 表达式是否能解析到方法参数。
-5. 更新/删除链路是否命中失效逻辑。
-6. Redis/Caffeine/JetCache 后端是否实际创建了缓存管理器。
-7. 降级行为是否与配置和业务预期一致。
-
-## 修改约束
-
-- 不要只加查询缓存而不处理更新失效。
-- 不要把缓存 key 绑定到不稳定对象序列化结果。
-- 不要在不明确一致性要求时默认启用本地缓存。
-- 如果项目已经有统一缓存 key 常量或枚举，沿用现有约定。
-
-## 按需读取
-
-- 源码索引：`references/source-index.md`
-- 注解定义：`assets/QueryCache.java`、`assets/UpdateCache.java`、`assets/ClearCache.java`
-- 复杂实现细节：`references/README.md`
+当组件源码变化后，用 `yss-source-index` 刷新 [source-index.md](references/source-index.md)，再运行 freshness 检查。不要手工修改生成索引。

package/template/.codex/skills/yss-cache/agents/openai.yaml

@@ -1,5 +1,5 @@
 version: 1
 interface:
   display_name: "YSS Cache"
-  short_description: "QueryCache、缓存更新、失效刷新与排障规范"
-  default_prompt: "Use $yss-cache to configure or debug QueryCache, UpdateCache, ClearCache, and Redis or Caffeine caching behavior."
+  short_description: "YSS 缓存注解、Redis 拓扑、降级与序列化诊断"
+  default_prompt: "Use $yss-cache to configure or diagnose YSS cache annotations, Redis topology, fallback, TTL, and serialization behavior."

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

@@ -0,0 +1,39 @@
+# 注解契约
+
+## 映射
+
+- `@QueryCache` -> Spring `CacheableOperation`。
+- `@UpdateCache` -> Spring `CachePutOperation`。
+- `@ClearCache` -> Spring `CacheEvictOperation`。
+- `value` 与 `cacheNames` 是别名；非空 `cacheName` 会覆盖枚举 cache names。
+- 默认 resolver 是 `cacheComposeResolver`。
+- `key` 与 `keyGenerator` 互斥。
+
+## 参数语义
+
+- `condition`：调用前判断，false 时跳过缓存操作。
+- `unless`：结果产生后判断；Query/Update 支持。ClearCache 虽保留该字段，但当前解析器不映射它。
+- `sync`：QueryCache 映射到同步加载；UpdateCache 和 ClearCache 当前不映射该字段。
+- `allEntries=true`：明确清空整个 cache。
+- `beforeInvocation=true`：业务方法执行前清理；后续业务失败不会恢复旧缓存。
+
+## Key 与清理
+
+```java
+@QueryCache(cacheName = "valuation:plan", key = "#tenantId + ':' + #planId")
+public PlanDTO get(String tenantId, Long planId) { ... }
+
+@ClearCache(cacheName = "valuation:plan", key = "#tenantId + ':' + #planId")
+public void delete(String tenantId, Long planId) { ... }
+```
+
+- 未配置 key 时由 Spring KeyGenerator 生成；无参数方法会得到 `SimpleKey.EMPTY`。
+- 当前 YSS 拦截器将 `SimpleKey.EMPTY` 视为全量清理。需要单 key 清理时必须给出稳定 key。
+- 全量清理优先显式写 `allEntries=true`，不要依赖偶然 key 形态。
+- 集合参数先稳定排序；null、大小写和空白必须归一化。
+
+## AOP 与事务
+
+- 缓存方法必须通过 Spring 代理调用；同类 `this.method()` 自调用会绕过拦截。
+- private 方法不能作为代理入口；final 方法/类受代理方式限制。
+- `put`、`evict`、`clear` 在事务同步激活时延迟到 `afterCommit`；回滚不执行缓存变更。

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

@@ -0,0 +1,25 @@
+# 架构与选择
+
+## 三种模型
+
+| 模型 | 行为 | 一致性边界 |
+|---|---|---|
+| Spring Cache 后端路由 | `yss.cache.active-type` 在 Redis、Caffeine、Hazelcast 中选择一个 Provider | 同一时刻是单后端，不是多级缓存 |
+| Redis fallback | Redis 故障时可临时改用另一个 Provider | 是故障降级；Caffeine 会产生节点间不一致窗口 |
+| JetCache | 独立扩展，可配置 local + remote | 只有实际配置 broadcast channel 才能认为本地失效会同步 |
+
+## 模块
+
+- `yss-component-spring-cache`：注解、解析器、拦截器、路由和公共属性。
+- `yss-component-redis-cache`：Jedis 连接、RedisTemplate、RedisCacheManager、健康检查和 fallback。
+- `yss-component-caffeine-cache`：节点本地缓存。
+- `yss-component-hazelcast-cache`：显式依赖的集群内存后端。
+- `yss-component-cache-starter`：默认聚合 Spring Cache、Redis 和 Caffeine。
+- `yss-component-jetcache`：与 Spring Cache 路由模型分开分析。
+
+## 选择规则
+
+- 跨节点共享且不接受节点本地旧值：使用纯 Redis。
+- 读多写少并允许短暂节点差异：可选择 Caffeine。
+- Redis 故障期间业务可用性高于缓存一致性：评估后启用 fallback。
+- 需要 local + remote：先确认 JetCache 的 local、remote、序列化和广播配置，不要只看依赖名称。

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

@@ -0,0 +1,34 @@
+# 接入与配置
+
+## 推荐接入
+
+```xml
+<dependency>
+  <groupId>com.yss.cloud</groupId>
+  <artifactId>yss-component-cache-starter</artifactId>
+</dependency>
+```
+
+启动类使用 `@EnableYssCloudCache`。`@EnableYssCloudRedisCache` 仅为兼容保留并已废弃。
+
+## 公共属性
+
+```yaml
+yss:
+  cache:
+    active-type: redis       # redis | caffeine | hazelcast
+    default-ttl: 1h
+    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` 可覆盖默认构建规格，修改前检查项目现有配置。
+- Hazelcast 不在 starter 生产依赖中；使用时显式引入模块并配置 `active-type=hazelcast`。
+
+## 自定义 Bean
+
+默认配置会对用户提供的 `RedisProperties`、`RedisConnectionFactory`、`JedisClientConfiguration`、pool config、RedisCacheManager、resolver、provider、serializer、RedisTemplate 和 RedisMappingContext 回退。排障时按类型和名称检查实际 Bean，不能假设框架默认 Bean 一定生效。

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

@@ -0,0 +1,23 @@
+# Redis 故障降级与恢复
+
+## 状态流
+
+```text
+Redis 健康 -> 命令或健康检查失败 -> 标记不健康 -> 跳过 Redis
+-> 可选 fallback -> 周期健康检查 -> Redis 可连接
+-> 清理脏 Redis cache 与本地 fallback cache -> 恢复 Redis
+```
+
+- fallback 默认关闭，默认目标是 Caffeine。
+- Redis 健康检查当前每 20 秒执行一次。
+- Redis 命令级连接故障也会立即报告不健康，不必等待下一轮检查。
+- 只读 fallback 不标记 Redis cache 为脏。
+- put、putIfAbsent、evict、clear、invalidate 和 valueLoader 产生的回退写入会标记为脏。
+- 恢复时先清理降级期间发生写操作的 Redis cache，再清理本地 fallback cache。
+- Redis 失效失败时继续保持不健康状态并在后续检查重试，不能提前切回旧 Redis 数据。
+
+## 一致性判断
+
+- Caffeine fallback 是每节点独立数据，不能保证跨节点读到相同值。
+- `clear-fallback-on-recovery=false` 会跳过恢复清理，可能重新暴露 Redis 旧值；除非业务明确接受，不要关闭。
+- 强一致、锁、幂等状态或余额类数据不应依赖缓存 fallback 保证正确性。

package/template/.codex/skills/yss-cache/references/redis-topology.md

@@ -0,0 +1,62 @@
+# Redis 拓扑
+
+框架使用 Spring Boot `spring.redis` 属性和 Jedis 客户端。
+
+## Standalone
+
+```yaml
+spring:
+  redis:
+    host: localhost
+    port: 6379
+    database: 10
+    username: ${REDIS_USERNAME:}
+    password: ${REDIS_PASSWORD:}
+    connect-timeout: 5s
+    timeout: 10s
+    client-type: jedis
+    jedis:
+      pool:
+        enabled: true
+        max-active: 16
+        max-idle: 8
+        min-idle: 2
+        max-wait: 2s
+```
+
+## Sentinel
+
+```yaml
+spring:
+  redis:
+    database: 10
+    username: ${REDIS_USERNAME:}
+    password: ${REDIS_PASSWORD:}
+    sentinel:
+      master: mymaster
+      nodes: host1:26379,host2:26379,host3:26379
+      username: ${SENTINEL_USERNAME:}
+      password: ${SENTINEL_PASSWORD:}
+```
+
+业务 Redis 认证与 Sentinel 自身认证相互独立。
+
+## Cluster
+
+```yaml
+spring:
+  redis:
+    database: 0
+    username: ${REDIS_USERNAME:}
+    password: ${REDIS_PASSWORD:}
+    cluster:
+      nodes: host1:6379,host2:6379,host3:6379
+      max-redirects: 5
+```
+
+## 强制约束
+
+- Sentinel 和 Cluster 不能同时配置，违反时启动失败。
+- Redis Cluster 只允许 DB 0，非零 `spring.redis.database` 会启动失败。
+- username/password、SSL、client-name、连接/读取超时和 Jedis pool 参数会传入连接配置。
+- 不要提供 Lettuce 专属调优参数；当前实现明确使用 Jedis。

package/template/.codex/skills/yss-cache/references/serialization.md

@@ -0,0 +1,17 @@
+# 序列化兼容
+
+当前存在两条不同数据路径：
+
+- 框架 `RedisTemplate` 使用 Jackson JSON serializer。
+- Spring `RedisCacheManager` 沿用默认 JDK value serialization。
+
+两者的数据不可假设互相可读。`RedisTemplate` 的历史泛型声明与通用 JSON 行为也不完全一致，修改前必须检查消费方注入类型和实际操作。
+
+以下变化都属于 Redis 数据协议变更：
+
+- 修改 value/hash serializer。
+- 修改 key serializer 或 cache prefix。
+- 重命名 cache name。
+- 改变 key 的字段、顺序、归一化或版本。
+
+实施协议迁移前至少选择一种策略：双读单写、双写、版本化前缀、灰度清理或停机迁移。必须验证旧值读取、新值写入、回滚和混合版本节点；禁止把“统一 serializer”当作无风险重构。

package/template/.codex/skills/yss-cache/references/source-index.md

@@ -1,6 +1,6 @@
 # yss-cache Source Index
 
-Generated: 2026-06-29T16:11:14+00:00
+Generated: 2026-07-17T10:08:00+00:00
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
 This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.

package/template/.codex/skills/yss-cache/references/troubleshooting.md

@@ -0,0 +1,33 @@
+# 证据化排障
+
+## 缓存未命中
+
+1. 检查 starter/后端依赖和 `@EnableYssCloudCache`。
+2. 检查 `active-type` 与实际 Provider/CacheManager Bean。
+3. 确认调用经过 Spring 代理，不是同类自调用。
+4. 检查 SpEL 参数名、null、集合顺序和租户维度。
+5. 比较两次调用生成的 cache name/key，并检查 Redis 实际 key。
+6. 检查 `condition`、`unless`、TTL 和序列化异常。
+
+## 更新后仍读旧值
+
+1. 列出所有写、删、状态变更入口，确认每条路径都更新或清理相同 cache/key。
+2. 检查事务是否尚未提交；YSS 写/删/清理可能在 `afterCommit` 执行。
+3. 检查是否误用了 Caffeine、fallback 或 JetCache local cache。
+4. 检查 `allEntries`、`beforeInvocation` 和空 key 产生的 `SimpleKey.EMPTY`。
+
+## Redis 启动或连接失败
+
+1. 判定 Standalone/Sentinel/Cluster，检查拓扑互斥和 Cluster DB 0。
+2. 分别核对 Redis 数据节点与 Sentinel 认证。
+3. 检查 SSL、DNS、端口、connect/read timeout 和 Jedis pool。
+4. 检查用户自定义连接工厂是否使默认配置回退。
+
+## Redis 故障后行为异常
+
+1. 检查 fallback 是否明确开启、目标 Provider 是否存在且 available。
+2. 区分只读回退与脏写回退。
+3. 查看恢复时 Redis 清理失败日志；失败时框架应保持降级并重试。
+4. 多节点差异优先按 fallback 一致性窗口分析，不要误判为 Redis 广播失效。
+
+可先运行 `scripts/inspect-cache-usage.sh <project-root>` 取得静态证据，再进入源码路径。

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

@@ -0,0 +1,34 @@
+# 验证与完成标准
+
+## 组件
+
+```bash
+./mvnw -f yss-microservice-components/yss-component-cache-parent/pom.xml verify
+```
+
+跨模块测试使用父 reactor 的 `-pl <module> -am`，避免解析本地旧 SNAPSHOT。也可运行：
+
+```bash
+scripts/verify-cache-component.sh --source-root /path/to/yss-cloud-microservice
+```
+
+## 消费项目
+
+```bash
+./mvnw -pl <starter-module> -am -DskipTests package
+```
+
+完整启动依赖数据库、注册中心等外部服务时，构建验证与启动验证分开报告。
+
+## 验收矩阵
+
+- 首次调用执行业务，第二次相同 key 命中缓存。
+- 不同租户/业务 key 不串值。
+- 更新、删除、状态变更后旧值失效。
+- `condition`、`unless` 和异常返回行为符合预期。
+- 默认 TTL 和枚举覆盖 TTL 在后端物理存在。
+- Redis 停止后行为符合 fallback 配置；恢复后旧 Redis 值不会重新出现。
+- Sentinel/Cluster 创建正确连接工厂，Cluster 使用 DB 0。
+- Docker 可用时真实 Redis 认证、JSON template、JDK cache serialization 和 TTL 测试实际执行。
+- Java 8 组件 class major version 为 52。
+- `git diff --check` 通过，消费 starter 构建通过。

package/template/.codex/skills/yss-cache/scripts/check-skill-freshness.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -u
+
+skill_dir=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+
+locate_source() {
+  if [ "$#" -gt 0 ] && [ -n "$1" ]; then
+    if [ -d "$1/yss-microservice-components/yss-component-cache-parent" ]; then
+      echo "$1"
+      return 0
+    fi
+    return 1
+  fi
+  if [ -n "${YSS_SOURCE_ROOT:-}" ] && [ -d "$YSS_SOURCE_ROOT/yss-microservice-components/yss-component-cache-parent" ]; then
+    echo "$YSS_SOURCE_ROOT"
+    return 0
+  fi
+  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
+      (CDPATH= cd -- "$candidate" && pwd)
+      return 0
+    fi
+  done
+  return 1
+}
+
+source_root=$(locate_source "${1:-}") || {
+  echo "ERROR: cannot locate yss-component-cache-parent; pass source root or set YSS_SOURCE_ROOT" >&2
+  exit 2
+}
+
+parent="$source_root/yss-microservice-components/yss-component-cache-parent"
+annotation="$parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/annotation/ClearCache.java"
+properties="$parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/YssCacheProperties.java"
+connection="$parent/yss-component-redis-cache/src/main/java/com/yss/cloud/cache/redis/config/RedisConnFactoryConfig.java"
+index="$skill_dir/references/source-index.md"
+fail=0
+
+require_text() {
+  file=$1
+  pattern=$2
+  label=$3
+  if ! grep -Eq "$pattern" "$file"; then
+    echo "STALE: $label not found in $file"
+    fail=1
+  fi
+}
+
+require_text "$annotation" 'boolean allEntries\(\)' 'ClearCache.allEntries'
+require_text "$annotation" 'boolean beforeInvocation\(\)' 'ClearCache.beforeInvocation'
+require_text "$properties" 'private Duration defaultTtl' 'yss.cache.default-ttl'
+require_text "$properties" 'private boolean fallbackEnabled' 'Redis fallback-enabled'
+require_text "$properties" 'private String fallbackType' 'Redis fallback-type'
+require_text "$properties" 'private boolean clearFallbackOnRecovery' 'Redis clear-fallback-on-recovery'
+require_text "$connection" 'cannot be configured together' 'Sentinel/Cluster mutual exclusion'
+require_text "$connection" 'database must be 0' 'Cluster database 0 guard'
+
+for module in yss-component-spring-cache yss-component-redis-cache yss-component-caffeine-cache yss-component-cache-starter yss-component-jetcache; do
+  if ! grep -q "$module" "$index"; then
+    echo "STALE: source-index is missing module $module"
+    fail=1
+  fi
+done
+
+generated=$(sed -n 's/^Generated: //p' "$index" | head -1)
+if [ -z "$generated" ]; then
+  echo "STALE: source-index has no Generated timestamp"
+  fail=1
+else
+  echo "INFO: source-index generated at $generated"
+fi
+
+if [ "$annotation" -nt "$index" ] || [ "$properties" -nt "$index" ] || [ "$connection" -nt "$index" ]; then
+  echo "STALE: critical cache source is newer than source-index"
+  fail=1
+fi
+
+if [ "$fail" -ne 0 ]; then
+  echo "RESULT: skill/source contract drift detected; refresh with yss-source-index and review semantic references"
+  exit 1
+fi
+
+echo "RESULT: yss-cache critical contracts match source at $source_root"
+exit 0

package/template/.codex/skills/yss-cache/scripts/inspect-cache-usage.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+set -u
+
+usage() {
+  echo "Usage: $0 <project-root>" >&2
+}
+
+if [ "$#" -ne 1 ]; then
+  usage
+  exit 2
+fi
+
+root=$1
+if [ ! -d "$root" ]; then
+  echo "ERROR: project root does not exist: $root" >&2
+  exit 2
+fi
+
+if command -v rg >/dev/null 2>&1; then
+  search() { rg -n --hidden --glob '!target/**' --glob '!.git/**' --glob '*.java' --glob '*.yml' --glob '*.yaml' --glob '*.properties' --glob 'pom.xml' "$1" "$root" 2>/dev/null || true; }
+  files() { rg --files "$root" -g '*.yml' -g '*.yaml' -g '*.properties' -g '*.java' -g 'pom.xml'; }
+else
+  search() { grep -REn "$1" "$root" --include='*.java' --include='*.yml' --include='*.yaml' --include='*.properties' --include='pom.xml' 2>/dev/null || true; }
+  files() { find "$root" -type f \( -name '*.java' -o -name '*.yml' -o -name '*.yaml' -o -name '*.properties' -o -name 'pom.xml' \); }
+fi
+
+tmp=${TMPDIR:-/tmp}/yss-cache-inspect.$$
+trap 'rm -f "$tmp"' EXIT HUP INT TERM
+files >"$tmp"
+if [ ! -s "$tmp" ]; then
+  echo "ERROR: no Java, Maven, or configuration files found under $root" >&2
+  exit 2
+fi
+
+fail=0
+echo "YSS cache usage inspection: $root"
+
+report() {
+  level=$1
+  title=$2
+  pattern=$3
+  result=$(search "$pattern")
+  if [ -n "$result" ]; then
+    echo
+    echo "[$level] $title"
+    echo "$result" | sed -n '1,20p'
+  fi
+}
+
+report INFO "Cache component dependencies" 'yss-component-(cache-starter|spring-cache|redis-cache|caffeine-cache|hazelcast-cache|jetcache)'
+report INFO "Cache enable annotations" '@EnableYssCloud(Cache|RedisCache)'
+report INFO "YSS cache annotations" '@(QueryCache|UpdateCache|ClearCache)'
+report INFO "Configured backend and TTL" 'yss\.cache\.(active-type|default-ttl)|active-type:|default-ttl:'
+report INFO "Redis fallback configuration" 'fallback-(enabled|type)|clear-fallback-on-recovery'
+report INFO "RedisTemplate injection contracts" 'RedisTemplate[[:space:]]*<'
+
+sentinel=$(search 'spring\.redis\.sentinel|sentinel:')
+cluster=$(search 'spring\.redis\.cluster|cluster:')
+if [ -n "$sentinel" ] && [ -n "$cluster" ]; then
+  echo
+  echo "[ERROR] Both Redis Sentinel and Cluster configuration markers were found. Confirm they are not active in the same profile."
+  fail=1
+fi
+
+if [ -n "$cluster" ]; then
+  nonzero=$(search 'spring\.redis\.database[[:space:]]*=[[:space:]]*[1-9][0-9]*|database:[[:space:]]*[1-9][0-9]*')
+  if [ -n "$nonzero" ]; then
+    echo
+    echo "[ERROR] Redis Cluster requires database 0."
+    echo "$nonzero" | sed -n '1,20p'
+    fail=1
+  fi
+fi
+
+clear_without_key=$(search '@ClearCache[[:space:]]*(\([^)]*\))?')
+if [ -n "$clear_without_key" ]; then
+  echo
+  echo "[REVIEW] ClearCache usages found. Verify each use has a stable key or explicit allEntries=true; no-arg methods produce SimpleKey.EMPTY."
+fi
+
+query=$(search '@QueryCache')
+update=$(search '@(UpdateCache|ClearCache)')
+if [ -n "$query" ] && [ -z "$update" ]; then
+  echo
+  echo "[REVIEW] QueryCache is used but no UpdateCache/ClearCache annotation was found. Inspect explicit invalidation paths."
+fi
+
+if [ "$fail" -ne 0 ]; then
+  echo
+  echo "RESULT: blocking cache configuration defects found"
+  exit 1
+fi
+
+echo
+echo "RESULT: no statically provable blocking cache defect found; REVIEW items still require code inspection"
+exit 0