create-yss-spec 3.4.10 → 3.5.2

package/template/.codex/skills/yss-technical-design/SKILL.md

@@ -5,24 +5,24 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 # YSS 技术设计
 
-已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `.template-spec/process/contract-reading.md`。
 
 由 `yss-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
 
 ## 文档写作
 
-起草或修订技术设计解释正文前，读取 `docs/process/document-writing.md` 的共用写法及工程契约指引，并在分支派发中传递该引用；结构化合同保持原 schema 和验证要求。
+起草或修订技术设计解释正文前，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约指引，并在分支派发中传递该引用；结构化合同保持原 schema 和验证要求。
 
 ## 输入与架构选择
 
 先读根 `CONTEXT.md`、已批准且当前的 Spec、业务规则、关键场景、适用的 API 契约、ADR 和工程约束。没有 API 或其他专项影响时记录有依据的不适用，不生成占位设计。
 
-按项目绑定架构选择的来源及摘要。新工程必须先通过 `gate.backend-architecture-platform-approved`：Agent 展示 DDD / MVC 推荐依据及平台清单中的精确 Spring Boot、Java 版本，用户在同一次决定中确认两项内容；决定持久化到 `scaffold-architecture-decisions.yaml`，再进入对应分支，后续脚手架消费同一决定。既有工程核验并沿用当前登记架构及固定工程基线/POM 中的实际 Spring Boot 版本，该门禁记录为 `not-applicable`，不重复询问；架构转换或平台升级另行立项。只有 `domain-driven` 和 `layered-mvc` 两种架构族，不能从目录推断或默认 DDD、MVC 或 Spring Boot 版本。具体 Profile 及模块边界消费技能注册表与 `docs/agents/backend-architecture-profiles.md`。
+按项目绑定架构选择的来源及摘要。新工程必须先通过 `gate.backend-architecture-platform-approved`：Agent 展示 DDD / MVC 推荐依据及平台清单中的精确 Spring Boot、Java 版本，用户在同一次决定中确认两项内容；决定持久化到 `scaffold-architecture-decisions.yaml`，再进入对应分支，后续脚手架消费同一决定。既有工程核验并沿用当前登记架构及固定工程基线/POM 中的实际 Spring Boot 版本，该门禁记录为 `not-applicable`，不重复询问；架构转换或平台升级另行立项。只有 `domain-driven` 和 `layered-mvc` 两种架构族，不能从目录推断或默认 DDD、MVC 或 Spring Boot 版本。具体 Profile 及模块边界消费技能注册表与 `.template-spec/agents/backend-architecture-profiles.md`。
 
 - `domain-driven`：调用 `yss-tactical-design`，补齐适用的战略领域输入。
-- `layered-mvc`：由本 skill 直接设计模块职责与依赖方向、用例流程、业务规则、状态转换、事务与回滚、幂等与并发、持久化映射、外部集成和公开测试 seam；不要求战略 DDD、聚合、值对象、Domain Event 或 DDD Gateway。分层边界消费 `docs/agents/backend-architecture-profiles.md`，不得为 MVC 加载 `yss-domain` 或生成 DDD Gateway。
+- `layered-mvc`：由本 skill 直接设计模块职责与依赖方向、用例流程、业务规则、状态转换、事务与回滚、幂等与并发、持久化映射、外部集成和公开测试 seam；不要求战略 DDD、聚合、值对象、Domain Event 或 DDD Gateway。分层边界消费 `.template-spec/agents/backend-architecture-profiles.md`，不得为 MVC 加载 `yss-domain` 或生成 DDD Gateway。
 
 已有 Strategic Design Handoff 时，两种分支都必须先完成导入和目标词汇对账，再逐条承接规则与关键场景。没有战略交接包的项目直接消费批准需求，不能为 MVC 补造战略 DDD。
 
@@ -44,4 +44,4 @@ schema v1 战术合同只按 DDD 显式兼容读取；使用 `--legacy-ddd`，
 
 ## 后端脚手架平台承接
 
-消费生命周期已确认的架构与 `platform_configuration` v2；不得自行选择、批准或静默升级 Boot/Java。平台清单执行 `scripts/backend-platforms` 查询；只允许已验证 YSS 组合，新生成缺少配置或证据即阻断。决定、合同、Manifest 与下游架构身份须绑定同一平台及兼容摘要。详见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+消费生命周期已确认的架构与 `platform_configuration` v2；不得自行选择、批准或静默升级 Boot/Java。平台清单执行 `scripts/backend-platforms` 查询；只允许已验证 YSS 组合，新生成缺少配置或证据即阻断。决定、合同、Manifest 与下游架构身份须绑定同一平台及兼容摘要。详见 仓库共享合同 `.template-spec/engineering/backend-platforms.md`。

package/template/.codex/skills/yss-technical-design/references/technical-design-contract.md

@@ -9,7 +9,7 @@
 - `inputs`：每行 `{kind, ref, version, digest}`，kind 为 context/spec/rules/scenarios/api/adr/engineering/strategic；至少包含根 CONTEXT.md 与 Spec。适用的工程/API 约束同样绑定。无 API 影响理由记录在需求或工程输入中。DDD 另须 strategic 输入，MVC 不要求。
 - `source_items`：无战略包时从批准需求提取稳定规则和场景 `{source_id, kind: rule | scenario, critical, source_ref}`。source_ref 必须对应 inputs，不复制源正文成为第二事实源。
 - `traceability`：逐项对应 source_items。沿用 `tactical_refs` 字段名以兼容承接协议，其值在新合同中可指向 MVC 用例、规则或 DDD 对象；其他字段与战略承接 rows 相同。implemented 仅表示设计承接已落实，不表示代码已实现。
-- 有战略包时追加 `strategic_handoff`，按 `docs/process/strategic-handoff-package.md` 绑定导入收据、摘要、正式对账及 rows；本地补充规则仍可写 source_items / traceability，但不能重复维护包内来源。
+- 有战略包时追加 `strategic_handoff`，按 `.template-spec/process/strategic-handoff-package.md` 绑定导入收据、摘要、正式对账及 rows；本地补充规则仍可写 source_items / traceability，但不能重复维护包内来源。
 - `evidence_refs`：现有审查证据的可读取路径。approved 状态必须有评审证据，真正批准仍由生命周期核验适用批准记录；本校验器不产生批准。
 - `digest`：删除根 digest 后按键排序、数组保持顺序的 canonical JSON SHA-256，前缀 `sha256:`。来源文件的 digest 使用原始字节 SHA-256；这两种摘要不可混用。
 

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

@@ -22,7 +22,7 @@ description: "选择和核验 YSS Vue 生产页面组件及 Ant Design Vue 兼
 
 ## 2. 执行前版本预检
 
-采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `docs/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
+采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `.template-spec/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
 
 进入实现前从前端工程根目录执行：
 

package/template/.codex/skills/yss-up-springboot3/SKILL.md

@@ -7,7 +7,7 @@ description: "审查或迁移 YSS Spring Boot 2 到 3 的依赖、Jakarta 与 Sp
 
 Use this skill for catalog-driven YSS backend upgrade analysis and approved migrations from an exact Spring Boot 2 platform to an exact Spring Boot 3 platform.
 
-中文说明：这个技能是平台迁移编排入口，不替代具体组件 Skill。源平台、目标平台和组件能力只从 `docs/engineering/backend-platforms.json`、批准的 `platform_configuration`、工程 Manifest、effective POM 与实际依赖树解析，不按版本记忆或源码可编译状态推断兼容。
+中文说明：这个技能是平台迁移编排入口，不替代具体组件 Skill。源平台、目标平台和组件能力只从 `.template-spec/engineering/backend-platforms.json`、批准的 `platform_configuration`、工程 Manifest、effective POM 与实际依赖树解析，不按版本记忆或源码可编译状态推断兼容。
 
 ## When To Use
 

package/template/.codex/skills/yss-web-controller/SKILL.md

@@ -101,4 +101,4 @@ node scripts/generate_controller.mjs \
 
 ## 新脚手架平台约束
 
-消费批准切片架构身份中的 `platform_configuration`，并与工程 Manifest、effective POM 和依赖树核对。DTO、Validation、Exception 或其他 YSS 组件命中时，逐项消费合同中的 `component_bindings`；缺少 verified 架构证据、构件摘要或绑定发生漂移时回合同编译器阻断。Validation namespace、Jackson wire 行为、Web starter 和自动配置机制只来自解析后的精确平台事实；命令参数必须使用该解析值，不在本 Skill 中按 Boot 大版本硬编码。不得在业务实现中升级、降级或替换组件；平台迁移使用独立迁移工作单元。详见仓库共享合同 `docs/engineering/backend-platforms.md`。
+消费批准切片架构身份中的 `platform_configuration`，并与工程 Manifest、effective POM 和依赖树核对。DTO、Validation、Exception 或其他 YSS 组件命中时，逐项消费合同中的 `component_bindings`；缺少 verified 架构证据、构件摘要或绑定发生漂移时回合同编译器阻断。Validation namespace、Jackson wire 行为、Web starter 和自动配置机制只来自解析后的精确平台事实；命令参数必须使用该解析值，不在本 Skill 中按 Boot 大版本硬编码。不得在业务实现中升级、降级或替换组件；平台迁移使用独立迁移工作单元。详见仓库共享合同 `.template-spec/engineering/backend-platforms.md`。

package/template/.codex/skills/yss-web-controller/references/profiles/layered-mvc-service.md

@@ -1,3 +1,3 @@
 # layered-mvc-service
 
-先读仓库 `docs/agents/backend-architecture-profiles.md`。server 的 Controller 只调用 service；私有 DTO 在 server，已批准 published-client 的公开 DTO 在 client。server 持有 MapStruct WebConvertor、HTTP 校验与错误脱敏。不得从表结构反推 OpenAPI，不得直连 Repository。执行脚本前确认其接受当前 Profile；不接受时返回 blocked，禁止伪造 DDD Manifest 绕过。
+先读仓库 `.template-spec/agents/backend-architecture-profiles.md`。server 的 Controller 只调用 service；私有 DTO 在 server，已批准 published-client 的公开 DTO 在 client。server 持有 MapStruct WebConvertor、HTTP 校验与错误脱敏。不得从表结构反推 OpenAPI，不得直连 Repository。执行脚本前确认其接受当前 Profile；不接受时返回 blocked，禁止伪造 DDD Manifest 绕过。

package/template/.cursor/skills/alibaba-java-code-style/SKILL.md

@@ -20,7 +20,7 @@ This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into
 
 ## Core Priorities
 
-- 先消费 architecture_identity 与工程 Java/数据库基线。MVC 分层按 `docs/agents/backend-architecture-profiles.md`；MySQL 专属方言规则仅对批准的 MySQL 存储生效，不能要求 H2 骨架引入 MySQL 驱动。YSS 包装、命名及处理器差异逐项记录基线例外，安全、权限、敏感信息与 SQL 参数绑定不得豁免。
+- 先消费 architecture_identity 与工程 Java/数据库基线。MVC 分层按 `.template-spec/agents/backend-architecture-profiles.md`；MySQL 专属方言规则仅对批准的 MySQL 存储生效，不能要求 H2 骨架引入 MySQL 驱动。YSS 包装、命名及处理器差异逐项记录基线例外，安全、权限、敏感信息与 SQL 参数绑定不得豁免。
 - Keep names readable, English, and consistent with Java layer conventions.
 - Avoid null, equality, wrapper comparison, collection, and concurrency traps that compile cleanly but fail at runtime.
 - Make logs useful without wasting CPU, disk, or alert budget.

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

@@ -11,13 +11,13 @@ Review of a pinned candidate against a fixed point on two core axes, plus UI fid
 
 普通功能默认由一名与实现者独立的审查者完成 Standards、Spec 和适用的 UI fidelity 检查，分别报告结论。只有专业能力缺口、结论冲突、明确外部制度或用户指定时，才拆成多个审查者；多个无依赖审查可以并行。检查轴不等于会签人数，不能要求用户为每个轴重复确认。
 
-If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
+If `.template-spec/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
 
 ## 文档写作
 
-撰写审查报告时，读取 `docs/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。
+撰写审查报告时，读取 `.template-spec/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。
 
 ## Process
 
@@ -30,13 +30,13 @@ If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-
 Look for the originating spec, in this order:
 
 1. A spec/Ticket/contract reference supplied by the user or an upstream lifecycle review input.
-2. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+2. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `.template-spec/agents/issue-tracker.md`.
 3. A spec file under `docs/`, `specs/`, or `docs/.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
 
-Compile sources **before** review. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `docs/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
+Compile sources **before** review. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `.template-spec/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
 
 For YSS backend review, derive the review roots from the candidate project root, implementation-repository registry, Slice `project_roots` and `allowed_write_paths`. Review only the project itself and registered backend development projects; exclude frontend roots, unrelated submodules/vendor trees and unregistered directories. Never replace this resolution with a fixed `apps/backend` assumption.
 
@@ -89,7 +89,7 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor
 
 For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. Round 1 blocking findings return to the implementer and require a new digest plus all review axes. If Round 2 still has an open `violation`, `drift`, or `new_impacts`, return `needs-human` and stop; do not silently start Round 3. Candidate byte changes invalidate every earlier axis report.
 
-Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `docs/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun affected axes and their dependencies; explicitly rebind unchanged evidence. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
+Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `.template-spec/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun affected axes and their dependencies; explicitly rebind unchanged evidence. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
 
 For Worktree mode, recapture the candidate digest after all applicable checks finish. If it differs from `candidate_digest`, mark the affected reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 

package/template/.cursor/skills/code-review/references/yss-review-standards.md

@@ -2,7 +2,7 @@
 
 本文件只服务唯一默认审查技能 `code-review`。Alibaba Java、YSS 前端 / 后端 skill 是 **Standards 轴的专项检查输入**，不是第二个通用审查 skill。
 
-权威接线：`yss-product-lifecycle/references/orchestration-contract.yaml` 的 `work-unit.code-review.review_standards_route` 与 `review_input`。报告形状：`docs/templates/review-report-template.md`。
+权威接线：`yss-product-lifecycle/references/orchestration-contract.yaml` 的 `work-unit.code-review.review_standards_route` 与 `review_input`。报告形状：`.template-spec/templates/review-report-template.md`。
 
 ## 1. 编译标准源
 

package/template/.cursor/skills/cross-repo-implementation-routing/SKILL.md

@@ -16,12 +16,12 @@ description: Use when a Harness change or vertical slice may require work across
 
 ## Workflow
 
-1. 读取 `docs/process/implementation-repo-integration.md` 和当前 change 资产。
+1. 读取 `.template-spec/process/implementation-repo-integration.md` 和当前 change 资产。
 2. 判断影响面：Harness-only、backend-only、frontend-only、backend+frontend、contract-only、release-only。
 3. 确认每个受影响实现仓库已有登记记录；缺失则阻断并要求 onboarding。
 4. 核对项目根路径：Harness 内 `harness-apps` 与 `git-submodule` 项目必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径必须阻断。`git-submodule` 另核 gitlink、`.gitmodules` 和独立 `git_url`。外部 `external-repository` 记录各自的真实项目根。
 5. 输出最小任务分配：Harness 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。`git-submodule` 必须追加 `superproject-gitlink-update`。
-6. 按 `docs/templates/cross-repo-slice-template.md` 生成切片记录草案。
+6. 按 `.template-spec/templates/cross-repo-slice-template.md` 生成切片记录草案。
 7. 给出 fresh verification 命令和阶段 checkpoint 回写字段。
 
 ## Routing Matrix

package/template/.cursor/skills/i-have-adhd/SKILL.md

@@ -6,7 +6,7 @@ license: MIT
 
 # i-have-adhd · YSS 适配
 
-为当前产物应用 `docs/process/document-writing.md`；该文是中文写法的唯一权威来源。需要例子时读取 `docs/templates/examples/lifecycle-writing-examples.md`。本技能是原资产所有者的配套技能，不持有业务决定、批准或生命周期状态。
+为当前产物应用 `.template-spec/process/document-writing.md`；该文是中文写法的唯一权威来源。需要例子时读取 `.template-spec/templates/examples/lifecycle-writing-examples.md`。本技能是原资产所有者的配套技能，不持有业务决定、批准或生命周期状态。
 
 ## 触发与作用域
 

package/template/.cursor/skills/i-have-adhd/references/yss-adaptation.md

@@ -14,7 +14,7 @@
 | 原因与修复直接陈述 | 区分已知现象、待验证原因和实际验证结果 |
 | 平台专属 agent 配置 | 不安装上游 Gemini 持久提示；项目 OpenAI 配置只描述当前文档配套用途 |
 
-生命周期仍拥有门禁、状态、批准和资产；本技能没有独立授权、审批或分支流程。正文规则只在 `docs/process/document-writing.md` 维护；本文件只解释来源差异。
+生命周期仍拥有门禁、状态、批准和资产；本技能没有独立授权、审批或分支流程。正文规则只在 `.template-spec/process/document-writing.md` 维护；本文件只解释来源差异。
 
 注册表将本技能声明为模型可调用、实例默认可发现的通用工作流 core 技能（仍只作为文档配套）；调用者以条件依赖加载。上游 `disable-model-invocation: true` 在适配版移除；作用域由本技能触发条件限定，不延续上游会话开关。
 

package/template/.cursor/skills/i-have-adhd/tests/verify-integration.mjs

@@ -7,7 +7,7 @@ import {pathToFileURL} from 'node:url';
 const root=path.resolve(process.argv[2] || '.');
 const read=ref=>fs.readFileSync(path.join(root,ref),'utf8');
 const {parse}=await import(pathToFileURL(path.join(root,'scripts/vendor/yaml.mjs')));
-const registry=parse(read('docs/agents/yss-skill-registry.yaml'));
+const registry=parse(read('.template-spec/agents/yss-skill-registry.yaml'));
 const skill=registry.skills.find(x=>x.id==='i-have-adhd');
 assert.equal(skill.instance_default_discoverable,true);
 assert.equal(registry.invocation_contract.overrides['i-have-adhd'].invocation_mode,'model');
@@ -27,7 +27,7 @@ for (const target of locked.targets) {
   const skillPath=target.endsWith('/i-have-adhd')?target:path.join(target,'i-have-adhd');
   assert.equal(treeHash(path.join(root,skillPath)),locked.effectiveHash,`projection ${target}`);
 }
-for(const ref of ['docs/process/document-writing.md','docs/templates/examples/lifecycle-writing-examples.md']) {
+for(const ref of ['.template-spec/process/document-writing.md','.template-spec/templates/examples/lifecycle-writing-examples.md']) {
   assert.ok(read(ref).length);
   assert.ok(!read(ref).includes('.template-source/'));
 }

package/template/.cursor/skills/implementation-repo-onboarding/SKILL.md

@@ -16,12 +16,12 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 
 ## Workflow
 
-1. 按根 `yss-project.yaml` 确认 `project-instance` 身份并消费根 `CONTEXT.md`，读取 `docs/process/implementation-repo-integration.md`。命中既有 Java/Maven 跨仓交付接入时，先按 `docs/process/delivery-preflight.md` 以已知原始引用准备清单并运行 `scripts/preflight-delivery --input <file> --stage prepare --json`；缺失来源保持缺失，不伪造 scope、批准、生成器或模块事实。预检可在拟初始化目标上列出当前缺项，但不会创建工程或执行输入命令。
+1. 按根 `yss-project.yaml` 确认 `project-instance` 身份并消费根 `CONTEXT.md`，读取 `.template-spec/process/implementation-repo-integration.md`。命中既有 Java/Maven 跨仓交付接入时，先按 `.template-spec/process/delivery-preflight.md` 以已知原始引用准备清单并运行 `scripts/preflight-delivery --input <file> --stage prepare --json`；缺失来源保持缺失，不伪造 scope、批准、生成器或模块事实。预检可在拟初始化目标上列出当前缺项，但不会创建工程或执行输入命令。
 2. 如果输入是本地路径，只读检查 Git remote、当前分支、目录结构、构建文件和测试脚本。
 3. 如果输入是远端 URL，优先使用只读 Git 查询。需要完整工作树时：`external-repository` 只能 clone 到临时目录；`git-submodule` 只能通过 `git submodule add` / `git submodule update --init` 在已批准的 `apps/backend/<project>/` 或 `apps/frontend/<project>/` gitlink 挂载点检出，禁止普通 clone 或复制源码进 Harness。
 4. 识别技术栈、包管理器、CI、测试命令、构建命令、OpenAPI 接入和设计 token 接入。
 5. 判定实现位置与 `repository_scope`：`external-repository` 记录真实项目根；`harness-apps` 与 `git-submodule` 只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`。`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。gitlink（mode `160000`）必须登记为 `git-submodule` 和 `layout_policy: git-submodule-harness-apps`，不得写成 `harness-apps`。必须对照工作树：`git ls-files --stage`、`.gitmodules` 与声明 scope 不一致时阻断；缺少 `git_entry_mode: 160000` 不得把挂载点当普通目录。
-6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。`git-submodule` 必填 `gitmodules_name`、`gitlink_path`、`git_entry_mode`、`superproject_git_url` 和 `checkout_state`。`harness-apps` / `external-repository` 这些字段填 `不适用`。
+6. 按 `.template-spec/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。`git-submodule` 必填 `gitmodules_name`、`gitlink_path`、`git_entry_mode`、`superproject_git_url` 和 `checkout_state`。`harness-apps` / `external-repository` 这些字段填 `不适用`。
 7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。命中交付预检时，登记和工程基线补齐后重跑 `prepare`；将结构化诊断的责任来源和恢复入口纳入缺口清单，在初始化或构建前关闭当前阶段阻断。后续阶段证据尚未形成不能被当作本阶段失败；其他技术栈/不涉及该交付协议的接入记录不适用原因，不能冒充后端 v2 正例。空 gitlink、detached HEAD、`--force` 覆盖挂载点或缺少递归检出凭据时标记阻断。需要转入已授权写入时，先按 [写范围核验](references/write-scope.md) 检查工具对象结果；只有 `.writable === true` 可写，其他形态或状态一律阻断。
 
 ## Baseline Checks

package/template/.cursor/skills/llm-wiki/references/discover.md

@@ -17,9 +17,9 @@ Unless the user replaces this list with the host's single source-of-truth table:
 
 - Root authoritative files (for example `README`, `AGENTS`, `CONTEXT`, repository-identity manifest)
 - `docs/adr/`
-- `docs/process/`
-- `docs/agents/`
-- `docs/templates/`
+- `.template-spec/process/`
+- `.template-spec/agents/`
+- `.template-spec/templates/`
 - Frozen contracts the user names
 
 `full` adds only roots the user listed. It is not "everything under `docs/`".

package/template/.cursor/skills/prototype-review/SKILL.md

@@ -7,7 +7,7 @@ description: Use when independently reviewing low-fidelity UI, interaction specs
 
 Use this skill as the independent low-fidelity review in `yss-prototype-stage`. The review is fail-closed: if the design cannot drive calibrated requirements, API, frontend acceptance, and slices, send it back to product design. `yss-product-lifecycle` alone records the resulting `check.prototype-reviewed` decision.
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
 
 ## Trigger Boundary
 
@@ -17,9 +17,9 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 
 - Spec baseline or confirmed user stories.
 - `docs/.scratch/<feature>/design/<feature>-interaction-spec.md` or prototype link.
-- State matrix, preferably based on `docs/design/templates/state-matrix-template.md`.
+- State matrix, preferably based on `.template-spec/design/templates/state-matrix-template.md`.
 - Existing OpenAPI Draft only if the review is checking alignment; do not require OpenAPI before product design.
-- `docs/.scratch/<feature>/verification/prototype-evidence.yaml` may be created as a pending Prototype Evidence schema v4 record from `docs/design/templates/prototype-evidence-template.yaml`, but档位构建与浏览器验证属于后续 `check.prototype-verified`。
+- `docs/.scratch/<feature>/verification/prototype-evidence.yaml` may be created as a pending Prototype Evidence schema v4 record from `.template-spec/design/templates/prototype-evidence-template.yaml`, but档位构建与浏览器验证属于后续 `check.prototype-verified`。
 
 ## Review Gates
 
@@ -74,4 +74,4 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 - <yss-prototype-stage / return to product design>
 ```
 
-Use `docs/design/templates/prototype-review-checklist.md` when writing a persistent review artifact.
+Use `.template-spec/design/templates/prototype-review-checklist.md` when writing a persistent review artifact.

package/template/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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 保证正确性。