create-yss-spec 3.4.10 → 3.5.2

package/template/.pi/skills/setup-matt-pocock-skills/SKILL.md

@@ -24,7 +24,7 @@ Look at the current repo to understand its starting state. Read whatever exists;
 - Root `AGENTS.md` — does it exist, and is there already an `## Agent skills` section?
 - The case-sensitive `CONTEXT.md` at the Git repository root; also detect lowercase, nested, or duplicate context files as migration problems
 - `docs/adr/` and any `src/*/docs/adr/` directories
-- `docs/agents/` — does this skill's prior output already exist?
+- `.template-spec/agents/` — does this skill's prior output already exist?
 - `docs/.scratch/` — sign that the canonical local-markdown issue tracker convention is already in use
 - `.scratch/` and `docs/requirements/tickets/` — legacy local-tracker roots; inspect them read-only for migration and never use them as new write targets
 - Is the `triage` skill installed? (a `triage` skill folder alongside this one, or `triage` in your available skills.) This decides whether Section B runs at all.
@@ -40,7 +40,7 @@ Lead each section with the recommended answer so the user can accept it in a wor
 > Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, and `to-spec` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `docs/.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
 
 Path resolution is configuration-first: every Local-aware skill must read the
-persisted `tracker.root` from `docs/agents/issue-tracker.md` before resolving an
+persisted `tracker.root` from `.template-spec/agents/issue-tracker.md` before resolving an
 artifact path. If the field is absent, use `docs/.scratch` as the default. Do
 not infer a tracker or replace the configured root from `git remote`; the legacy
 `.scratch/` and `docs/requirements/tickets/` roots are read-only migration
@@ -54,7 +54,7 @@ The supported tracker choices in this template are exactly `local-markdown`, `gi
 
 Do not offer an `Other` tracker or write an unsupported platform into the project configuration; extending the YSS tracker contract must happen before adding another platform.
 
-Record the choice in `docs/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
+Record the choice in `.template-spec/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
 
 **Section B — Triage label vocabulary.** Skip this section entirely if the `triage` skill isn't installed (exploration told you) — an uninstalled skill needs no labels.
 
@@ -73,7 +73,7 @@ If the root `CONTEXT.md` is missing, initialize it with `context_schema_version:
 Show the user a draft of:
 
 - The `## Agent skills` block to add to `AGENTS.md`
-- The contents of `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, and `docs/agents/triage-labels.md` (the last only when `triage` is installed)
+- The contents of `.template-spec/agents/issue-tracker.md`, `.template-spec/agents/domain.md`, and `.template-spec/agents/triage-labels.md` (the last only when `triage` is installed)
 
 Let them edit before writing.
 
@@ -93,18 +93,18 @@ The block:
 
 ### Issue tracker
 
-[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
+[one-line summary of where issues are tracked]. See `.template-spec/agents/issue-tracker.md`.
 
 ### Triage labels
 
-[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
+[one-line summary of the label vocabulary]. See `.template-spec/agents/triage-labels.md`.
 
 ### Domain docs
 
-[one-line summary: one root `CONTEXT.md`, with bounded contexts represented inside its business glossary]. See `docs/agents/domain.md`.
+[one-line summary: one root `CONTEXT.md`, with bounded contexts represented inside its business glossary]. See `.template-spec/agents/domain.md`.
 ```
 
-Include the `### Triage labels` sub-block, and write `docs/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted.
+Include the `### Triage labels` sub-block, and write `.template-spec/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted.
 
 Then write the docs files using the seed templates in this skill folder as a starting point:
 
@@ -114,8 +114,8 @@ Then write the docs files using the seed templates in this skill folder as a sta
 - [triage-labels.md](./triage-labels.md) — label mapping (only if `triage` is installed)
 - [domain.md](./domain.md) — domain doc consumer rules + layout
 
-For an unsupported tracker request, stop and require a YSS tracker-contract extension; do not write an unsupported platform into `docs/agents/issue-tracker.md`.
+For an unsupported tracker request, stop and require a YSS tracker-contract extension; do not write an unsupported platform into `.template-spec/agents/issue-tracker.md`.
 
 ### 5. Done
 
-Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.
+Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `.template-spec/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

package/template/.pi/skills/triage/SKILL.md

@@ -30,7 +30,7 @@ Two categories:
 - `bug` — something is broken
 - `enhancement` — new feature or improvement
 
-五态语义由 `docs/agents/triage-labels.md` 定义：
+五态语义由 `.template-spec/agents/triage-labels.md` 定义：
 
 - `needs-triage` — maintainer needs to evaluate
 - `needs-info` — waiting on reporter for more information

package/template/.pi/skills/yss-application/references/profiles/layered-mvc-service.md

@@ -1,3 +1,3 @@
 # layered-mvc-service
 
-先读仓库 `docs/agents/backend-architecture-profiles.md` 的 MVC 约定。写入 `service` 的 command/query/result/service 包；事务与业务行为通过公开用例 seam 做 behavior-tdd。调用 Repository/Adapter；不得生成 Domain Gateway 或引用 client DTO、Spring MVC、生产驱动。需要 HTTP 协议变更时返回 new_impacts，由 Web 工作单元处理。
+先读仓库 `.template-spec/agents/backend-architecture-profiles.md` 的 MVC 约定。写入 `service` 的 command/query/result/service 包；事务与业务行为通过公开用例 seam 做 behavior-tdd。调用 Repository/Adapter；不得生成 Domain Gateway 或引用 client DTO、Spring MVC、生产驱动。需要 HTTP 协议变更时返回 new_impacts，由 Web 工作单元处理。

package/template/.pi/skills/yss-application/references/profiles/mvc-data-analysis-v1.md

@@ -1,3 +1,3 @@
 # mvc-data-analysis-v1
 
-先读仓库 `docs/agents/backend-architecture-profiles.md` 的 MVC 约定。写入 `core` 的 command/query/result/service 包；core 是薄应用层，拥有事务与内部模型，不依赖 client/server。读取/计算/导出编排不能自动扩大 SQL 或 API 合同；数据行为采用 behavior-tdd。不要套用 DDD application-layer-guide。
+先读仓库 `.template-spec/agents/backend-architecture-profiles.md` 的 MVC 约定。写入 `core` 的 command/query/result/service 包；core 是薄应用层，拥有事务与内部模型，不依赖 client/server。读取/计算/导出编排不能自动扩大 SQL 或 API 合同；数据行为采用 behavior-tdd。不要套用 DDD application-layer-guide。

package/template/.pi/skills/yss-backend-spec-review/SKILL.md

@@ -35,7 +35,7 @@ description: 审计既有 Java 后端工程对 YSS 技能规范和已批准业
 
 ## 输出与完成依据
 
-复用 `docs/templates/review-report-template.md`、当前 Slice 的 YSS Skill Execution Result 和 [审计与整改流程中的记录要求](references/remediation-workflow.md#证据与交接)。报告列明审查覆盖、Standards / Spec 分轴结论、修复前后 finding、候选/规则摘要、实际验证、独立 Reviewer 身份和剩余阻塞。只对本次覆盖且有证据的范围声明符合规范，不自动证明平台已认证或允许发布。
+复用 `.template-spec/templates/review-report-template.md`、当前 Slice 的 YSS Skill Execution Result 和 [审计与整改流程中的记录要求](references/remediation-workflow.md#证据与交接)。报告列明审查覆盖、Standards / Spec 分轴结论、修复前后 finding、候选/规则摘要、实际验证、独立 Reviewer 身份和剩余阻塞。只对本次覆盖且有证据的范围声明符合规范，不自动证明平台已认证或允许发布。
 
 ## 必须评估、适用必审
 

package/template/.pi/skills/yss-backend-spec-review/references/check-inputs.md

@@ -12,7 +12,7 @@
 | wire / 参数 / 错误 | `yss-dto`、`yss-validation`、`yss-exception` | 真实响应/分页/错误协议、Bean Validation、命名空间、敏感字段与冻结 OpenAPI 一致 |
 | 映射 / 注解处理 | `mapstruct`、`lombok` | 显式字段策略、处理器版本、领域工厂重建；不强迫聚合开放 setter |
 | 实际组件调用 | Registry 中对应组件 Skill 与精确平台源码索引 | cache、userinfo、audit、ID、Excel、resilience 等按能力加载；不因“审查全面”要求安装不用的组件 |
-| 工程和平台 | `docs/engineering/backend-platforms.json`、当前工程基线、effective POM、依赖树 | 精确 JDK/Boot、父/BOM、starter、javax/jakarta 和源码索引；源码可编译不等于兼容认证 |
+| 工程和平台 | `.template-spec/engineering/backend-platforms.json`、当前工程基线、effective POM、依赖树 | 精确 JDK/Boot、父/BOM、starter、javax/jakarta 和源码索引；源码可编译不等于兼容认证 |
 
 每个后端范围显式评估 `yss-web-controller` / `yss-dto` / `yss-domain` / `yss-application` / `yss-repository` / `yss-mybatis`。无持久化或 MyBatis 影响时分别说明原因；不可跳过适用项，也不可为了填表增加实现。MVC 不强制构造 DDD 聚合/Gateway；没有展示分页需求就不要求分页类。
 

package/template/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.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-ddd-scaffold-generator/SKILL.md

@@ -32,7 +32,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 - Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Java 下限和允许组合由当前平台条目决定。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
 - 平台候选维护验证产物标记 `platform_verification=candidate`，不能交给业务生成、升级完成等级或进入首切片验证。测试夹具不证明 YSS 兼容。
 
-版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `.template-spec/engineering/backend-platforms.md`。
 
 ## 优先流程
 
@@ -74,7 +74,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
 - 脚手架合同必须携带 `contract_id`、`contract_version`、实现合同编译器 draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
-- 新脚手架只接受统一 Project Scaffold Contract schema v4，并必须以原始字节摘要绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 必须闭包绑定同一 OpenAPI YAML 字节的 Validation、独立 Review、Freeze 与工程批准；`not-applicable` 必须绑定评估、明确原因和证据且禁止空占位资产。历史 Manifest 只读审计见 [历史兼容边界](references/generator-maintenance.md)，不得用于新生成。
+- 新脚手架只接受统一 Project Scaffold Contract schema v4，并必须以原始字节摘要绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`） 和真实工程合同批准记录。API `required` 必须闭包绑定同一 OpenAPI YAML 字节的 Validation、独立 Review、Freeze 与工程批准；`not-applicable` 必须绑定评估、明确原因和证据且禁止空占位资产。历史 Manifest 只读审计见 [历史兼容边界](references/generator-maintenance.md)，不得用于新生成。
 - DDD 固定 `target-domain-model`、`mybatis-plus`、H2 验证、`web` DTO、`yss-internal`；平台与 Validation 命名空间由共享清单约束。普通 MyBatis、独立 client module、client-in-domain 和其他旧架构仍为 `unsupported`。
 - 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation`、实际输出路径和固定三条验证命令，不接受仅凭任意字符串引用的放行。
 - 生成项目必须写入 Manifest v4 `.yss/scaffold-generation.json`，记录技术、数据与 API 设计门禁、架构选择及 digest、生成器、合同 digest、Target Profile、模块闭包、模板 digest、下游完整 当前合同 freshness、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 实现合同编译器。

package/template/.pi/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs

@@ -209,7 +209,7 @@ export class ScaffoldGenerator {
     if (!contract || Array.isArray(contract) || typeof contract !== "object") fail("脚手架合同必须是 JSON 对象");
     if (contract.schema_version !== 4) fail(`unsupported: 后端新生成只接受 Project Scaffold Contract v4，收到 v${contract.schema_version}`);
     if (contract.kind !== "project-scaffold-contract" || contract.delivery_role !== "backend" || contract.scaffold_kind !== "backend-ddd") fail("schema v4 合同必须绑定 backend/backend-ddd");
-    validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
+    validateJsonSchema(contract, path.join(REPOSITORY_ROOT, ".template-spec/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
     const requiredMetadata = [["--contract-id", this.options.contractId], ["--contract-version", this.options.contractVersion], ["--approval-ref", this.options.approvalRef], ["--compiler-draft-ref", this.options.compilerDraftRef], ["--persisted-ref", this.options.persistedRef]];
     const missing = requiredMetadata.filter(([, value]) => !isPresent(value)).map(([flag]) => flag);
     if (missing.length) fail(`生成项目必须提供当前已批准脚手架合同的完整元数据: ${missing.join(", ")}`);

package/template/.pi/skills/yss-design-system/SKILL.md

@@ -10,24 +10,24 @@ description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一
 ## 权威资料
 
 - 规范源：根 `DESIGN.md`，是项目视觉 Token 与组件视觉变体的唯一事实来源，使用 Google `design.md` alpha canonical H2 章节。
-- 团队治理说明：`docs/design/design.md`，解释 YSS 生命周期、组件路线、状态与验收，不重新定义 `DESIGN.md` 中的具体值。
-- 项目 Token 快照：`docs/design/tokens/theme.json`、`docs/design/tokens/tokens.default.json`、`docs/design/tokens/tokens.dark.json`、`docs/design/tokens/tokens.compact.json`、`docs/design/tokens/variables.css`、`docs/design/tokens/variables.dark.css`；它们是派生实现视图，不得反向覆盖规范源。
-- 本技能执行清单：`references/design-system.md`，用于 Agent 执行和评审，不替代 `docs/design/design.md`。
+- 团队治理说明：`.template-spec/design/design.md`，解释 YSS 生命周期、组件路线、状态与验收，不重新定义 `DESIGN.md` 中的具体值。
+- 项目 Token 快照：`.template-spec/design/tokens/theme.json`、`.template-spec/design/tokens/tokens.default.json`、`.template-spec/design/tokens/tokens.dark.json`、`.template-spec/design/tokens/tokens.compact.json`、`.template-spec/design/tokens/variables.css`、`.template-spec/design/tokens/variables.dark.css`；它们是派生实现视图，不得反向覆盖规范源。
+- 本技能执行清单：`references/design-system.md`，用于 Agent 执行和评审，不替代 `.template-spec/design/design.md`。
 - 历史输入包：`/Users/zhudaoming/Downloads/Product-Design-System`，只用于追溯首次引入来源，不作为后续工程依赖。
 - 默认主题来源：Data Quality 主题经项目适配后落到根 `DESIGN.md`；来源与 AntD v6 设计参考 / Vue 运行时的区别见 `references/data-quality-theme.md`。
 - Codex `$design-qa` 项目对照：`references/design-qa-theme.md`，不替代官方 `design-qa` 流程，也不改上游插件正文。
 - 原型阶段合同：`yss-prototype-stage`，用于统一 H1/H2 原型资产和浏览器验证证据。H1/H2 默认使用项目 Token 驱动的 HTML/CSS/JavaScript 离线原型。
 
-如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 Token，必须按 `DESIGN.md` → `docs/design/design.md` 顺序读取，再按当前主题、密度与输出表面选择对应 Token 文件，不全量预读所有主题；若要执行评审或实现检查，再读 `references/design-system.md`。
+如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 Token，必须按 `DESIGN.md` → `.template-spec/design/design.md` 顺序读取，再按当前主题、密度与输出表面选择对应 Token 文件，不全量预读所有主题；若要执行评审或实现检查，再读 `references/design-system.md`。
 
 ## 使用流程
 
 1. 先判断任务阶段：设计系统引入 / 产品设计 / 原型评审 / 前端实现 / UI 改造 / 主题 token 落地。
-2. 读取已有资产：先读根 `DESIGN.md`，再读 `docs/design/design.md` 和 Token 派生快照，最后按任务读取相关 Spec、交互说明、状态矩阵、OpenAPI Draft、现有页面代码。
+2. 读取已有资产：先读根 `DESIGN.md`，再读 `.template-spec/design/design.md` 和 Token 派生快照，最后按任务读取相关 Spec、交互说明、状态矩阵、OpenAPI Draft、现有页面代码。
 3. 按设计系统基线约束输出或修改产物：颜色、排版、间距、圆角、动效、组件、状态、响应式。
 4. 若是产品设计阶段，先使用 `yss-prototype-stage`；规范直出由 YSS HTML adapter 执行；存在已选视觉稿时条件使用 `product-design:index`，其他 Agent 交付等价证据。
 5. 若是前端实现阶段，配合 `yss-ui`、`yss-ui-business-page-generation`、`yss-formily` 及实际命中的组件专项，但本技能负责风格与体验一致性门禁。
-6. 若发现视觉 Token 或组件变体不足，先更新根 `DESIGN.md` 并重新生成投影；只有治理、流程或验收说明不足时才更新 `docs/design/design.md`。
+6. 若发现视觉 Token 或组件变体不足，先更新根 `DESIGN.md` 并重新生成投影；只有治理、流程或验收说明不足时才更新 `.template-spec/design/design.md`。
 
 ## 核心基线
 
@@ -62,7 +62,7 @@ description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一
 
 设计类任务至少输出：
 
-- 设计系统引用：明确引用根 `DESIGN.md`、治理说明 `docs/design/design.md` 和所选主题的 Token 快照；原型证据记录规范与 Token 摘要。
+- 设计系统引用：明确引用根 `DESIGN.md`、治理说明 `.template-spec/design/design.md` 和所选主题的 Token 快照；原型证据记录规范与 Token 摘要。
 - 页面和模块：页面清单、布局结构、主路径、异常路径。
 - 组件选择：YSS UI / Ant Design 组件映射。
 - 状态矩阵：加载、空、错、禁用、只读、无权限、冲突、成功。
@@ -99,10 +99,10 @@ description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一
 当用户要求“引入设计系统”“形成项目规范”“更新设计系统 skill”时：
 
 1. 分析来源设计系统，不原样堆拷贝。
-2. 将稳定视觉 Token 与组件变体先落到根 `DESIGN.md`；治理、流程和验收说明再落到 `docs/design/design.md`。
-3. 运行 `node .template-source/tooling/node/scripts/design-md.mjs export dtcg --write --write-manifest --antd-toolchain <固定antd6.6.4作者目录>` 更新派生视图；运行前先更新 `docs/design/design-system-sync.yaml` 的规范源摘要。
+2. 将稳定视觉 Token 与组件变体先落到根 `DESIGN.md`；治理、流程和验收说明再落到 `.template-spec/design/design.md`。
+3. 运行 `node .template-source/tooling/node/scripts/design-md.mjs export dtcg --write --write-manifest --antd-toolchain <固定antd6.6.4作者目录>` 更新派生视图；运行前先更新 `.template-source/design/design-system-sync.yaml` 的规范源摘要。
 4. 将 Agent 执行入口落到 `.agents/skills/yss-design-system/SKILL.md`，执行清单落到 `references/design-system.md`；两者只引用 Token 名和角色，不复制具体值。
-5. 更新 `docs/design/README.md` 和必要的 `AGENTS.md` 入口规则。
+5. 更新 `.template-spec/design/README.md` 和必要的 `AGENTS.md` 入口规则。
 6. 运行 frontmatter、对应 `node --test`、`design-md lint/drift`、技能投影与 lock 校验。
 
 默认主题事实见 `references/data-quality-theme.md`；运行时 Ant Design Vue 4 与 AntD v6 设计参考分别记录。

package/template/.pi/skills/yss-design-system/references/design-qa-theme.md

@@ -5,8 +5,8 @@
 ## Source visual truth
 
 - 规范：根 `DESIGN.md`
-- 治理说明：`docs/design/design.md`
-- Token 投影：`docs/design/tokens/theme.json`、`docs/design/tokens/tokens.default.json`、`docs/design/tokens/variables.css`
+- 治理说明：`.template-spec/design/design.md`
+- Token 投影：`.template-spec/design/tokens/theme.json`、`.template-spec/design/tokens/tokens.default.json`、`.template-spec/design/tokens/variables.css`
 - 主题选择：默认采用根 `DESIGN.md` 的 Data Quality 浅色主题；仅显式暗色 / 紧凑模式使用对应的 `tokens.dark.json` / `variables.dark.css` / `tokens.compact.json`，以实际消费文件记录摘要。
 - 实现截图：当前原型或页面在同一 viewport / 主题 / 状态下的渲染
 
@@ -23,7 +23,7 @@
 | 功能状态 | `colors.success*` / `warning*` / `error*` / `info-bg` | 改成非功能色装饰 |
 | 页面 / 容器 / 浮层 | `colors.canvas-layout` / `surface*` | 用阴影或局部硬编码堆叠表面层级 |
 | 主次文本 | `colors.text*` | 使用历史文本值或页面特例 |
-| 运行时变量 | `docs/design/tokens/variables.css` 必须与根规范 digest 同步 | 页面另写一套 Less/CSS 色值 |
+| 运行时变量 | `.template-spec/design/tokens/variables.css` 必须与根规范 digest 同步 | 页面另写一套 Less/CSS 色值 |
 
 上游预设色板不是品牌 seed，不要据此判定规范漂移。
 

package/template/.pi/skills/yss-design-system/references/design-system.md

@@ -5,8 +5,8 @@
 权威资料：
 
 - 规范源：根 `DESIGN.md`（项目视觉 Token 与组件视觉变体）
-- 治理说明：`docs/design/design.md`（生命周期、组件路线、状态与验收）
-- 派生快照：`docs/design/tokens/*`（实现映射，不得反向覆盖规范源）
+- 治理说明：`.template-spec/design/design.md`（生命周期、组件路线、状态与验收）
+- 派生快照：`.template-spec/design/tokens/*`（实现映射，不得反向覆盖规范源）
 - Skill 入口：`.agents/skills/yss-design-system/SKILL.md`
 
 ## 设计定位
@@ -205,7 +205,7 @@ YSS UI / Vue：
 
 设计评审时检查：
 
-- 是否引用根 `DESIGN.md`、治理说明 `docs/design/design.md` 与所选主题快照，并在原型证据中记录摘要。
+- 是否引用根 `DESIGN.md`、治理说明 `.template-spec/design/design.md` 与所选主题快照，并在原型证据中记录摘要。
 - 是否符合中后台定位。
 - 页面清单、主路径、异常路径是否清楚。
 - 状态矩阵是否完整。