create-yss-spec 1.1.3 → 2.0.0

package/template/.claude/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/.claude/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/.claude/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/.claude/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/.claude/skills/yss-cache/references/source-index.md

@@ -0,0 +1,64 @@
+# yss-cache Source Index
+
+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.
+
+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.
+
+## Component Path Hints
+
+- `yss-microservice-components/yss-component-cache-parent` (existed when indexed)
+
+## Documentation Files
+
+- `yss-microservice-components/yss-component-cache-parent/readme.md`
+
+## Maven Modules
+
+- `yss-microservice-components/yss-component-cache-parent`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-cache-starter`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-caffeine-cache`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-hazelcast-cache`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-jetcache`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-redis-cache`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache`
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-cache-parent/yss-component-caffeine-cache/src/main/java/com/yss/cloud/cache/caffeine/config/CacheCaffeineManagerConfig.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-caffeine-cache/src/main/java/com/yss/cloud/cache/caffeine/config/CacheCaffeineResolver.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-caffeine-cache/src/main/java/com/yss/cloud/cache/caffeine/config/CaffeineCacheBackendProvider.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-hazelcast-cache/src/main/java/com/yss/cloud/cache/hazelcast/config/CacheHazelcastManagerConfig.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-hazelcast-cache/src/main/java/com/yss/cloud/cache/hazelcast/config/HazelcastCacheBackendProvider.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-hazelcast-cache/src/main/java/com/yss/cloud/cache/hazelcast/config/YssCacheHazelcastProperties.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-jetcache/src/main/java/com/yss/cloud/cache/jetcache/CacheManagerCompose.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-redis-cache/src/main/java/com/yss/cloud/cache/redis/config/RedisCacheBackendProvider.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-redis-cache/src/main/java/com/yss/cloud/cache/redis/config/RedisConnFactoryConfig.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-redis-cache/src/main/java/com/yss/cloud/cache/redis/config/RedisTemplateConfig.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-redis-cache/src/main/java/com/yss/cloud/cache/redis/config/SafeRedisCache.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-redis-cache/src/main/java/com/yss/cloud/cache/redis/config/YssCacheRedisResolver.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-redis-cache/src/main/java/com/yss/cloud/cache/repository/BaseRedisRepository.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-redis-cache/src/main/java/com/yss/cloud/cache/repository/YssDatamiddle.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/ApplicationContextCacheHelper.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/CacheComposeResolver.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/CacheManagerCompose.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/CacheMemResolver.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/CacheRedisResolver.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/EnableYssCloudCache.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/EnableYssCloudRedisCache.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/YssCacheBackendProvider.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/YssCacheInterceptor.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/YssCacheProperties.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/annotation/ClearCache.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/annotation/QueryCache.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/annotation/UpdateCache.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/annotation/YssCacheAnnotationParser.java`
+- `yss-microservice-components/yss-component-cache-parent/yss-component-spring-cache/src/main/java/com/yss/cloud/cache/config/CacheOperationSourceConfiguration.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.

package/template/.claude/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/.claude/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/.claude/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/.claude/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

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

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+set -u
+
+source_root=""
+consumer_root=""
+consumer_module=""
+
+usage() {
+  echo "Usage: $0 [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]" >&2
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --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 ;;
+    -h|--help) usage; exit 0 ;;
+    *) usage; exit 2 ;;
+  esac
+done
+
+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
+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
+  exit 2
+fi
+if [ ! -x "$source_root/mvnw" ]; then
+  echo "ERROR: Maven wrapper is missing or not executable: $source_root/mvnw" >&2
+  exit 2
+fi
+if { [ -n "$consumer_root" ] && [ -z "$consumer_module" ]; } || { [ -z "$consumer_root" ] && [ -n "$consumer_module" ]; }; then
+  echo "ERROR: --consumer-root and --consumer-module must be provided together" >&2
+  exit 2
+fi
+
+echo "== Cache reactor verify =="
+(cd "$source_root" && ./mvnw -f "$parent/pom.xml" 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"
+if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+  if [ ! -f "$report" ]; then
+    echo "ERROR: Docker is available but Redis integration report is missing" >&2
+    exit 1
+  fi
+  if grep -Eq 'skipped="[1-9]' "$report"; then
+    echo "ERROR: Docker is available but Redis integration test was skipped" >&2
+    exit 1
+  fi
+  echo "PASS: real Redis integration test executed"
+else
+  echo "SKIP: Docker is unavailable; Redis integration test may be skipped by assumption"
+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
+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 "ERROR: no compiled cache class found" >&2
+  exit 1
+fi
+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
+  exit 1
+fi
+echo "PASS: all cache classes use major version 52"
+
+if [ -n "$consumer_root" ]; then
+  echo "== Consumer build =="
+  if [ ! -x "$consumer_root/mvnw" ] || [ ! -f "$consumer_root/pom.xml" ]; then
+    echo "ERROR: invalid consumer root: $consumer_root" >&2
+    exit 2
+  fi
+  (cd "$consumer_root" && ./mvnw -pl "$consumer_module" -am -DskipTests package) || exit 1
+fi
+
+echo "RESULT: cache verification passed"
+exit 0

package/template/.codex/config.toml

@@ -0,0 +1,3 @@
+sandbox_mode = "danger-full-access"
+
+approval_policy = "never"

package/template/.codex/skills/ask-matt/SKILL.md

@@ -20,16 +20,16 @@ The route most work travels. You have an idea and want it built.
    - **`/prototype`** to answer the question with throwaway code,
    - **`/handoff`** back what you learned, and reference it from the original idea thread.
 3. **Branch — is this a multi-session build?**
-   - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues). Because the issues are independent, **clear context between each one**: start a fresh session per issue and kick off **`/implement`** by passing it the PRD and the single issue to work on.
+   - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `.scratch/<feature>/tickets/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **clearing context between each one**.
    - **No** → **`/implement`** right here, in the same context window.
 
    Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
 
 ### Context hygiene
 
-Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-issues` — so the grilling, PRD, and issues all build on the same thinking. Each `/implement` then starts fresh, working from the issue.
+Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket.
 
-The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-issues`, don't push on degraded — `/handoff` and continue in a fresh thread.
+The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/handoff` and continue in a fresh thread.
 
 ## On-ramps
 
@@ -37,10 +37,14 @@ A starting situation that generates work, then merges onto the main flow.
 
 - **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up.
 
-  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Issues that `/to-issues` produced are already agent-ready, so **don't triage them**.
+  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Tickets that `/to-tickets` produced are already agent-ready, so **don't triage them**.
 
 - **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down.
 
+- **A huge, foggy effort — a greenfield project or a huge feature build, too big for one session** → **`/wayfinder`**, the most cognitively demanding flow here. When the way from here to the destination isn't visible yet, it charts a **shared map** of **decision tickets** on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't — and it's slower and denser, so save it for exactly that, never a well-scoped feature.
+
+  When the map clears, **it hands off, it doesn't build**: merge onto the main flow at **`/to-spec`**, which collapses the map's linked decisions into a buildable plan, then `/to-tickets` and `/implement` as usual. Looping the map straight into `/implement` skips that collapse and throws the linked detail away — go straight to `/implement` only when the effort turned out genuinely small.
+
 ## Codebase health
 
 Not feature work — upkeep.

package/template/.codex/skills/ask-matt/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Ask Matt"
+  short_description: "Find the right skill or workflow"
+policy:
+  allow_implicit_invocation: false

package/template/.codex/skills/code-review/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: code-review
-description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/Spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
 ---
 
 Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
 
 - **Standards** — does the code conform to this repo's documented coding standards?
-- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+- **Spec** — does the code faithfully implement the originating Ticket / Spec?
 
 Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
 
@@ -26,9 +26,9 @@ Before going further, confirm the fixed point resolves (`git rev-parse <fixed-po
 
 Look for the originating spec, in this order:
 
-1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+1. Ticket references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
 2. A path the user passed as an argument.
-3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
+3. A Spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
 4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
 
 ### 3. Identify the standards sources

package/template/.codex/skills/code-review/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Code Review"
+  short_description: "Review a diff on standards and spec"

package/template/.codex/skills/code-review-process/references/automation-and-standards.md

@@ -49,7 +49,7 @@ sonarqube:
     paths:
       - .sonar/cache
   script:
-    - mvn clean org.jacoco:jacoco-maven-plugin:prepare-agent install sonar:sonar
+    - ./mvnw clean org.jacoco:jacoco-maven-plugin:prepare-agent install sonar:sonar
   allow_failure: true
 ```