create-yss-spec 3.4.5 → 3.4.7

package/template/.codex/skills/yss-security-algorithm/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: yss-security-algorithm
-description: "接入或排查 YSS 加解密、JWT/JWK、密码编码、密钥加载与轮换。"
+description: "审查、迁移或排查既有 YSS 加解密、JWT/JWK、密码编码与密钥使用；当前组件禁止新生产接入。"
 ---
 
 # yss-security-algorithm
 
-Use this skill for YSS 安全算法组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+Use this skill as the governance, migration, and troubleshooting entry for the existing YSS 安全算法组件. Keep conclusions grounded in the local project, the approved platform catalog, and resolvable component source.
 
 中文说明：本技能用于 YSS 安全算法组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
 
@@ -17,19 +17,33 @@ Use this skill for YSS 安全算法组件. Keep implementation grounded in the l
 
 Read `references/source-index.md` as a path-hint index whenever the task depends on exact modules, annotations, auto configuration, properties, controllers, clients, repositories, DTOs, handlers, or troubleshooting.
 
+## 当前准入结论
+
+- `yss-component-security-algorithm` 当前只允许既有工程只读盘点、故障分诊、风险收敛和迁移；禁止为新项目、新 Slice 或新生产能力接入。
+- Registry provider 使用 `new_adoption: forbidden`，即 new-adoption-forbidden 语义；新接入必须返回稳定失败码 `component-new-adoption-forbidden`，不得因构件可编译、索引 fresh 或平台基础能力通过而放行。
+- 硬编码私钥、固定 key id、进程启动时临时生成密钥以及 `noop` password encoder 均不构成生产密钥管理。组件源码可定位或可编译也不能解除该结论。
+- 只有平台目录中的 `component.security-algorithm` 对目标架构为 `verified`，精确构件绑定仍有效，并且外部 KMS / Secret Manager、轮换撤销、兼容迁移、行为测试和安全责任人审查全部闭合后，才能通过独立决策重新开放新接入；本 Skill 不自行修改该状态。
+- 新接入请求返回 `component-new-adoption-forbidden` / `blocked-for-production`，并给出迁移或外部密钥服务方案；不得生成基于遗留工具类的生产代码。
+
 ## Workflow
 
-1. Identify whether the task is symmetric encryption, asymmetric encryption, SM algorithms, JWT key generation/configuration, or decryption troubleshooting.
-2. Read `references/source-index.md`, then inspect `CryptoType`, `SecurityCryptoUtil`, `KeyGeneratorUtils`, and `DefaultJwtConfiguration`.
-3. Use `CryptoType` to route algorithm-specific behavior; current enum values include `RSA`, `AES`, `DES`, `SM2`, and `SM4`.
-4. Treat `SecurityCryptoUtil` and `Jwks` as compatibility/legacy references only. The current `Jwks.generateRsa()` decodes hardcoded `PK`/`SK` constants rather than generating or loading a managed key, while EC/secret keys can be process-local or regenerated at startup; none is production key management.
-5. For production changes, externalize keys/secrets and avoid copying hardcoded sample keys into business modules.
+1. 识别任务是新接入、既有故障、风险止血还是迁移；新接入直接按上述准入结论阻断。
+2. 读取 `references/source-index.md`，再按需检查 `CryptoType`、`SecurityCryptoUtil`、`KeyGeneratorUtils` 和 `DefaultJwtConfiguration`，记录实际算法、模式、编码、key id、密钥来源、调用方和持久化数据范围。
+3. 对既有使用先完成暴露面和兼容盘点：源码/配置中的密钥材料、JWT 签发与验签方、密码散列格式、密文格式、历史数据、下游消费者及回滚要求。
+4. 在 `boot3-java17` 中，`Jwks.generateRsa()`、`generateEc()` 和 `generateSecret()` 是 deprecated fail-closed 入口：它们不生成、不解码密钥，必须抛出错误并要求 managed `JWKSource`。Boot 2 中可能存在的硬编码/临时密钥实现只用于风险盘点，不得迁入 Boot 3。
+5. `SecurityCryptoUtil` 是兼容 facade，只有显式安装获批 `SecurityCryptoProvider` 后才委派 encrypt/decrypt；未配置 provider 时 fail closed。provider 必须是外部 KMS / Secret Provider 或经批准的托管加密适配器。
+6. `RsaEcbOAEPWithSHA` 保留 deprecated 的 public constructor、`TextEncryptor` 类型和实例 `encrypt` / `decrypt` 签名作为二进制/源码兼容适配器；实现只委派 `SecurityCryptoUtil`，不得恢复内置私钥或自行执行遗留加密。
+7. 迁移目标必须使用批准的外部 KMS / Secret Manager 或等价受控密钥服务，应用只保存 key reference/version；密钥材料不得进入源码、普通配置、日志、证据文件或聊天记录。
+8. 设计分阶段轮换：冻结新旧写入边界，建立新 key version，双读/多版本解密或离线重加密，验证存量数据和 JWT 消费者，再撤销旧 key；不得直接覆盖旧密钥导致数据或令牌不可恢复。
+9. Boot 3 默认密码 Bean 与兼容 public static factory 都调用 `PasswordEncoderFactories.createDelegatingPasswordEncoder()`；不得把 delegating encoder 的默认 id 改回 `noop`。密码迁移仍需兼容升级策略。
+10. JWT 必须验证 signature、issuer、audience、expiry 和允许算法，payload parsing 不能充当认证。
+11. 输出迁移清单、数据/调用方影响、回滚点、验证结果和安全审查引用；缺任一生产前提时保持 `blocked-for-production`。
 
 ## Security Notes
 
-- The current utility contains a complete hardcoded RSA private key and fixed key material; do not use it for production data. Existing exposure requires rotation/revocation planning, not merely avoiding new constants.
-- `Jwks.generateRsa()` contains a complete hardcoded RSA private key; the key identifier is static and must be treated as compromised until rotated.
-- `DefaultJwtConfiguration` generates or selects JWK material at startup and currently selects `noop` as the DelegatingPasswordEncoder default; persistence, rotation, an external secret source, and an explicit password-encoder override are production prerequisites.
+- Boot 2 历史实现中的硬编码 RSA 私钥、固定 key id、临时 JWK 与 noop 默认值必须视为已暴露风险并进入轮换/撤销盘点；不得把这些历史事实误写成 Boot 3 当前实现。
+- Boot 3 `Jwks` fail closed，`DefaultJwtConfiguration` 只提供 `PasswordEncoderFactories` 的 delegating encoder；JWT/JWK 必须由应用安全层或外部 KMS 提供。
+- 兼容适配器只保留公开类型和方法契约，不恢复旧密钥、旧密文解密或隐式 provider。存量兼容仍需代表性 ciphertext/JWT/password fixtures、回滚点和安全责任人审查。
 - Verify whether callers need encryption for storage, transport, signing, or compatibility; choose algorithm and key lifecycle accordingly.
 - Prefer environment/config/secret-manager backed keys for deployable code.
 - Keep plaintext, ciphertext, encoding format, and key type explicit in API contracts.
@@ -44,9 +58,19 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 - Decrypt path uses the matching algorithm/key type.
 - No passwords, private keys, or long-lived secrets are added to source files.
 - If external key storage, rotation/revocation, algorithm parameters, compatibility tests, or security-owner review is missing, return `blocked-for-production` instead of generating crypto code.
+- `Jwks` without a managed source and `SecurityCryptoUtil` without an approved `SecurityCryptoProvider` both fail closed.
+- Deprecated compatibility adapters delegate to the approved provider and preserve public signatures only; they do not make the component eligible for new adoption.
+- Existing ciphertext/JWT/password compatibility is demonstrated with representative fixtures before disabling an old key or encoder.
+- Logs and verification evidence contain only key references and redacted metadata, never plaintext, private keys, seeds, shared secrets, or complete tokens.
 
 ## Do Not
 
 - Do not invent class names or configuration keys without checking the source index.
 - Do not replace component extension points with business-local framework code.
 - Do not broaden the task into unrelated YSS components unless the user asks.
+- Do not approve a new integration because the component compiles, a source index is fresh, or an existing project already depends on it.
+- Do not copy, print, rotate in place, or reissue any key material through Agent output.
+
+## 平台与源码门禁
+
+接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-security-algorithm --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。

package/template/.codex/skills/yss-security-algorithm/references/source-index.boot2-java8.md

@@ -0,0 +1,50 @@
+# yss-security-algorithm Source Index
+
+Index schema: `backend-component-source-index-v2`
+Platform line: `boot2-java8`
+Generated: 2026-09-18T19:31:25.688Z
+Source commit: `a3be2b2e33dca4545782e2b31894aaa00d0305cd`
+Component worktree: `clean`
+Component tree `yss-microservice-components/yss-component-security-algorithm`: `a28f507af00845909eef3ad6bdf8b716660f5b9d`
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT_BOOT2_JAVA8` to reproduce or refresh.
+
+This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+
+Paths are relocatable source hints. Exact guidance requires a matching component tree and a clean indexed component subtree; the repository commit is trace metadata and may differ when unrelated components change.
+
+## Component Path Hints
+
+- `yss-microservice-components/yss-component-security-algorithm` (existed when indexed)
+
+## Documentation Files
+
+- No component documentation files found.
+
+Component documentation is a discovery aid. For API signatures, conditions and defaults, prefer the indexed source facts below when documentation differs.
+
+## Maven Modules
+
+- `yss-microservice-components/yss-component-security-algorithm/pom.xml` — GAV `com.yss.cloud:yss-component-security-algorithm:2.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-cloud-microservice:2.0.0-SNAPSHOT`
+
+## Platform Signals
+
+- Inherited Java signals: `1.8`.
+- Inherited Spring Boot signals: `2.7.18`.
+- Namespace source signals: `javax.*` in 5 main Java files; `jakarta.*` in 0 main Java files.
+- Auto-configuration metadata: 1 `spring.factories`; 0 `AutoConfiguration.imports` files.
+- These are source observations, not compatibility certification. Use the approved `platform_configuration` and verified compatibility evidence before integration or generation.
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/CryptoType.java` — `sha256:8012f5f45f0038b4c994cd60cdf43db02805e41d938fbe928a50879feebba5b7`
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/config/DefaultJwtConfiguration.java` — `sha256:050afd7fefedd729d4548c34317faa35c4954a8731657cdcc71eae46571e8d2c`
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/jose/KeyGeneratorUtils.java` — `sha256:ae92d9c55b8f54ec476b472e0aa9c3b3cc4a238fd643030fc132a2bf86783bf8`
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/util/SecurityCryptoUtil.java` — `sha256:ba61c9d7908d258b810d997e27b12426f3c85dd5c17f5d5002b6d0a6053c436e`
+
+## Freshness and Use
+
+- Locate the current source root using `YSS_SOURCE_ROOT_BOOT2_JAVA8`, CodeGraph, Maven artifact names or repository search.
+- Compare each indexed `Component tree` with `git rev-parse HEAD:<component-path>` and require the current component subtree to be clean before exact guidance.
+- Run `node ../yss-skill-source-index-refresh/scripts/check-backend-skill-source-index.mjs --skill <skill-id> --platform-line boot2-java8 --source-root <root>` from the canonical skill root before exact integration guidance.
+- A repository commit difference alone is not stale when the component tree is unchanged; a component tree mismatch or component-local dirty state is stale.
+- Read only the source entries needed for the current decision or troubleshooting path.

package/template/.codex/skills/yss-security-algorithm/references/source-index.boot3-java17.md

@@ -0,0 +1,51 @@
+# yss-security-algorithm Source Index
+
+Index schema: `backend-component-source-index-v2`
+Platform line: `boot3-java17`
+Generated: 2026-09-18T19:31:25.688Z
+Source commit: `a1c284f1d4507894003eb7dfc7b0db263957e345`
+Component worktree: `clean`
+Component tree `yss-microservice-components/yss-component-security-algorithm`: `448ff7770709f4329a0e277526dbb0f2f4a83010`
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT_BOOT3_JAVA17` to reproduce or refresh.
+
+This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+
+Paths are relocatable source hints. Exact guidance requires a matching component tree and a clean indexed component subtree; the repository commit is trace metadata and may differ when unrelated components change.
+
+## Component Path Hints
+
+- `yss-microservice-components/yss-component-security-algorithm` (existed when indexed)
+
+## Documentation Files
+
+- No component documentation files found.
+
+Component documentation is a discovery aid. For API signatures, conditions and defaults, prefer the indexed source facts below when documentation differs.
+
+## Maven Modules
+
+- `yss-microservice-components/yss-component-security-algorithm/pom.xml` — GAV `com.yss.cloud:yss-component-security-algorithm:3.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-cloud-microservice:3.0.0-SNAPSHOT`
+
+## Platform Signals
+
+- Inherited Java signals: `17`.
+- Inherited Spring Boot signals: `3.5.16`.
+- Namespace source signals: `javax.*` in 3 main Java files; `jakarta.*` in 0 main Java files.
+- Auto-configuration metadata: 1 `spring.factories`; 1 `AutoConfiguration.imports` files.
+- These are source observations, not compatibility certification. Use the approved `platform_configuration` and verified compatibility evidence before integration or generation.
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/CryptoType.java` — `sha256:8012f5f45f0038b4c994cd60cdf43db02805e41d938fbe928a50879feebba5b7`
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/SecurityCryptoProvider.java` — `sha256:cdd98bd56701af5e2cc7d794017ca7caa139f358d7706eb3f66afb50cb370ecc`
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/config/DefaultJwtConfiguration.java` — `sha256:538f9fd8cc643efc44614642b47d03cee34d9a4e59e5714e3ec2740f26a92658`
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/jose/KeyGeneratorUtils.java` — `sha256:ae92d9c55b8f54ec476b472e0aa9c3b3cc4a238fd643030fc132a2bf86783bf8`
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/util/SecurityCryptoUtil.java` — `sha256:6e53bb3da3ef717723f473a3c965034bd90f8285e787f43e4a93d14e7a497c4d`
+
+## Freshness and Use
+
+- Locate the current source root using `YSS_SOURCE_ROOT_BOOT3_JAVA17`, CodeGraph, Maven artifact names or repository search.
+- Compare each indexed `Component tree` with `git rev-parse HEAD:<component-path>` and require the current component subtree to be clean before exact guidance.
+- Run `node ../yss-skill-source-index-refresh/scripts/check-backend-skill-source-index.mjs --skill <skill-id> --platform-line boot3-java17 --source-root <root>` from the canonical skill root before exact integration guidance.
+- A repository commit difference alone is not stale when the component tree is unchanged; a component tree mismatch or component-local dirty state is stale.
+- Read only the source entries needed for the current decision or troubleshooting path.

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

@@ -1,35 +1,10 @@
-# yss-security-algorithm Source Index
+# yss-security-algorithm Source Index Router
 
-Generated: 2026-08-17T12:03:37.436Z
-Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
-Source worktree: `dirty`
-Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
+Index schema: `backend-component-source-index-router-v1`
 
-This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
+Select the source index from the approved `platform_configuration.component_platform_line`; do not infer a line from imports, a branch name or a requested upgrade.
 
-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.
+- `boot2-java8` — [Spring Boot 2.7 / Java 8 maintenance line](source-index.boot2-java8.md)
+- `boot3-java17` — [Spring Boot 3.5 / Java 17 mainline](source-index.boot3-java17.md)
 
-## Component Path Hints
-
-- `yss-microservice-components/yss-component-security-algorithm` (existed when indexed)
-
-## Documentation Files
-
-- No component documentation files found.
-
-## Maven Modules
-
-- `yss-microservice-components/yss-component-security-algorithm`
-
-## Key Java Entry Points
-
-- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/CryptoType.java`
-- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/config/DefaultJwtConfiguration.java`
-- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/jose/KeyGeneratorUtils.java`
-- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/util/SecurityCryptoUtil.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.
+Run the freshness checker with the same explicit `--platform-line` and its matching clean source root before exact integration guidance.

package/template/.codex/skills/yss-skill-source-index-refresh/SKILL.md

@@ -11,8 +11,8 @@ Use this maintenance skill to keep YSS skills grounded in current source and doc
 
 ## Source Location Policy
 
-- Backend component source is environment-specific. Use `references/source-location.md` before trusting any generated path.
-- Preferred explicit setting: `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice`.
+- Backend component source is generation-specific. Use `references/source-location.md` before trusting any generated path.
+- Set both `YSS_SOURCE_ROOT_BOOT2_JAVA8` and `YSS_SOURCE_ROOT_BOOT3_JAVA17` to clean source trees. Do not point both variables at the same checkout or infer a platform line from a branch name.
 - Frontend YSS UI components: `http://192.168.164.27:3200/components`
 - Frontend YSS UI hooks: `http://192.168.164.27:3200/hooks`
 - Frontend YSS UI skill docs: `http://192.168.164.27:3200/skills`
@@ -23,7 +23,8 @@ Run:
 
 ```bash
 export YSS_SKILLS_ROOT="/path/to/.agents/skills"
-export YSS_SOURCE_ROOT="/path/to/yss-cloud-microservice"
+export YSS_SOURCE_ROOT_BOOT2_JAVA8="/path/to/boot2-java8/yss-cloud-microservice"
+export YSS_SOURCE_ROOT_BOOT3_JAVA17="/path/to/boot3-java17/yss-cloud-microservice"
 node "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs"
 ```
 
@@ -32,28 +33,31 @@ Use `YSS_REFRESH_BACKEND_SKILLS=yss-mybatis` (comma-separated) to refresh only s
 
 The script updates `references/source-index.md` for backend component skills and `references/frontend-docs.md` for frontend YSS UI skills. Read `references/source-map-config.md` for the full skill-to-source mapping.
 
+所有后端组件 Skill 共用 [平台与源码门禁](references/backend-component-platform-compatibility.md)。`references/source-index.md` 是稳定选择页；真实生成索引分别为 `source-index.boot2-java8.md` 与 `source-index.boot3-java17.md`。刷新后使用批准的 `platform_configuration.component_platform_line` 运行 `scripts/check-backend-skill-source-index.mjs --skill <skill-id> --platform-line <line> --source-root <matching-root>`，确认组件 tree、组件子树状态和 v2 平台信号与所选源码行一致。
+
 中文说明：脚本不会复制大段源码；通用组件生成可追踪的入口索引，持久化组件额外生成公开 API、配置开关和能力边界矩阵，方便 Agent 按需读取真实源码。
 
-If `YSS_SOURCE_ROOT` is omitted, the script tries to find a repository containing `yss-microservice-components` from the current workspace and common local project folders. If it cannot find one, set `YSS_SOURCE_ROOT` explicitly.
+The refresh command requires both generation-specific roots. A targeted refresh may still use `YSS_REFRESH_BACKEND_SKILLS`, but it updates both platform tracks for every selected Skill.
 
 ## Output Contract
 
 Generated source indexes should contain:
 
-- generated timestamp and trace-only source Git commit
+- explicit platform line, generated timestamp and trace-only source Git commit
 - component-relative tree hashes and component-scoped worktree state
 - component directories and documentation files
 - Maven modules
 - source file hashes and relocatable paths
 - for capability-sensitive components, concise public signatures, configuration keys/defaults, conditional activation and capability boundaries extracted from source
 - for other components, key Java classes matched by names such as annotations, auto configurations, properties, aspects, interceptors, handlers, repositories, DTOs, and result objects
+- local Maven lineage、精确组件 GAV，以及继承的 Java/Spring Boot、`javax`/`jakarta` 和自动配置注册信号；这些是源码观察，不是兼容认证
 - recommended next reads for Agent when performing implementation or troubleshooting
 
 Do not paste full component source into `SKILL.md`. Keep `SKILL.md` short and let specialists read generated indexes or targeted assets only when needed.
 
 ## Freshness Gate
 
-Before exact class/config/security guidance, compare each indexed `Component tree` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A tree mismatch or component-local dirty state means `stale`: refresh the index or return `blocked`; do not silently rely on the old snapshot. A repository commit difference alone is trace metadata and does not make the index stale when the component tree is unchanged. Historical path hints may still be used only to locate current source.
+Before exact class/config/security guidance, choose the index track from the approved platform configuration, compare each indexed `Component tree` with `git -C "$MATCHING_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A missing platform line, wrong-generation root, tree mismatch or component-local dirty state means `stale`: refresh the matching track or return `blocked`; do not fall back to the other generation. A repository commit difference alone is trace metadata and does not make the index stale when the component tree is unchanged. Historical path hints may still be used only to locate current source.
 
 中文说明：`SKILL.md` 保持短小，细节放到 `references/`，这是为了降低每次触发技能时的上下文成本。
 
@@ -64,3 +68,5 @@ Validate the migrated Node helper with:
 ```bash
 node --test "$YSS_SKILLS_ROOT/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.test.mjs"
 ```
+
+`yss-validation` 只索引当前仓库实际存在的 `yss-component-validation-jsr303`。历史 EL/parser 组件路径不存在时不得生成路径提示或宣称可接入；需要该能力时返回 `blocked` 并重新确认真实组件来源。

package/template/.codex/skills/yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md

@@ -0,0 +1,27 @@
+# 后端组件平台与源码门禁
+
+本合同适用于 `yss-cache`、`yss-mybatis`、`yss-dto`、`yss-audit-log`、`yss-excel-mvc`、`yss-distributed-id`、`yss-resilience4j`、`yss-validation`、`yss-security-algorithm`、`yss-userinfo` 和 `yss-exception`。
+
+## 执行入口
+
+1. 接入、修改、代码生成或给出精确类名/配置前，从批准的 `platform_configuration.component_platform_line` 选择目标 Skill 的 `references/source-index.boot2-java8.md` 或 `references/source-index.boot3-java17.md`，并执行：
+
+   ```bash
+     node ../yss-skill-source-index-refresh/scripts/check-backend-skill-source-index.mjs \
+       --skill <skill-id> \
+       --platform-line <boot2-java8|boot3-java17> \
+       --source-root <包含-yss-microservice-components-的仓库根>
+   ```
+
+2. 平台线与源码根不匹配、校验非零、组件 tree 不一致、组件子树 dirty、索引缺少平台信号或真实源码不可定位时，精确接入和实现返回 `blocked`。不得退回另一代索引。只读故障分诊可以继续，但必须把结论标为未完成源码核验。
+3. 新脚手架及其切片消费批准且当前的 `platform_configuration` v2，并核对工程 Manifest、解析后的组件 GAV 和兼容证据。缺少 verified 组合或目标组件证据时回实现合同编译器，不替换 YSS 组件、不降级 Boot/Java，也不把候选渲染或源码编译当作兼容认证。
+4. 既有工程以登记的架构身份、实际 POM/effective POM 和依赖树为准；平台升级或组件升级单独立项。源码索引中的 Java、Boot、命名空间和自动配置只用于发现风险，不能批准升级。
+
+## 平台边界
+
+- `yss-microservice-components` 当前源码行的 POM/namespace 信号不自动授权任意 Boot/JDK。最终支持范围只来自仓库共享平台目录中的 verified 兼容组合及其原始证据。
+- Boot 2.7 使用 Java 8 与 `javax` Web/Validation 基线；Boot 3.5/4.1 使用 Java 17 或 21 与 `jakarta`，Boot 4 还涉及 Jackson 3 和新的 starter/自动配置结构。目标组件没有对应证据时必须阻断。
+- BOM 版本不等于每个组件 artifact 的实际版本。比较依赖树中的精确 GAV；索引输出的本地 POM lineage 是定位证据，不代替 effective POM 和运行验证。
+- `javax.sql`、`javax.crypto` 等 Java SE 包不是 Jakarta 迁移目标，不能用简单字符串替换处理。
+
+共享平台事实源为 `docs/engineering/backend-platforms.json` 和 `docs/engineering/backend-platforms.md`。

package/template/.codex/skills/yss-skill-source-index-refresh/references/source-location.md

@@ -5,9 +5,9 @@ YSS skill references may mention paths such as `yss-microservice-components/yss-
 ## Lookup Order
 
 1. Check the current workspace first. If `.codegraph/` exists, use `codegraph explore "<class, module, or path hint>"` before text search.
-2. If the component source is outside the workspace, use `YSS_SOURCE_ROOT` when it is set. It should point to the repository root that contains `yss-microservice-components`.
-   Compare every indexed `Component tree` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A tree mismatch or component-local dirty state is `stale` and blocks exact implementation guidance until refresh. `Source commit` is trace metadata only; unrelated monorepo changes do not stale an unchanged component tree.
-3. If `YSS_SOURCE_ROOT` is not set, search common local roots such as the current repository parents, `~/Projects`, `~/Documents`, and `~/Documents/yss-project`.
+2. Resolve the approved `platform_configuration.component_platform_line`, then use `YSS_SOURCE_ROOT_BOOT2_JAVA8` or `YSS_SOURCE_ROOT_BOOT3_JAVA17`. Each variable points to a different generation-specific repository root containing `yss-microservice-components`.
+   Compare every indexed `Component tree` in the selected platform file with `git -C "$MATCHING_SOURCE_ROOT" rev-parse HEAD:<component-path>` and check `git status --porcelain -- <component-path>`. A line/root mismatch, tree mismatch or component-local dirty state is `stale` and blocks exact implementation guidance until refresh. `Source commit` is trace metadata only; unrelated monorepo changes do not stale an unchanged component tree.
+3. If the required generation-specific variable is absent, locate a clean checkout using CodeGraph, Git worktree inventory, Maven coordinates or repository search, then set the explicit variable. Do not use an arbitrary checkout discovered first.
 4. If the source still cannot be found, use the generated `references/source-index.md` as a stale-but-useful map of module names, package names, class names, and Maven artifacts. Do not assume listed files exist locally.
 
 ## For Skill Authors
@@ -16,4 +16,4 @@ YSS skill references may mention paths such as `yss-microservice-components/yss-
 - Keep generated indexes useful for search, but do not require agents to open those exact paths.
 - Prefer symbols, package names, Maven artifact names, and annotations in instructions; they survive repository relocation better than absolute paths.
 - Keep full production source out of skill `assets/`; generate concise signatures, activation conditions and file hashes instead.
-- When refreshing indexes, export `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice` if auto-detection cannot find the component repository.
+- When refreshing indexes, export both generation-specific variables; targeted skill refresh still regenerates both tracks for the selected Skill.

package/template/.codex/skills/yss-skill-source-index-refresh/references/source-map-config.md

@@ -1,19 +1,26 @@
 # YSS Source Index Mapping
 
-The refresh script maps component source path hints to skill references. These paths are relative to the detected or configured `YSS_SOURCE_ROOT`; they are not guaranteed to exist in every workspace.
+The refresh script maps component source path hints to two generated skill references: `source-index.boot2-java8.md` and `source-index.boot3-java17.md`. Paths are relative to the matching configured generation root and are not guaranteed to exist in every workspace.
 
 中文说明：这个文件记录“哪个组件源码目录生成到哪个 skill 的引用索引”，方便你以后维护映射关系。
 
+| Platform line | Source variable | Generated suffix |
+| --- | --- | --- |
+| `boot2-java8` | `YSS_SOURCE_ROOT_BOOT2_JAVA8` | `source-index.boot2-java8.md` |
+| `boot3-java17` | `YSS_SOURCE_ROOT_BOOT3_JAVA17` | `source-index.boot3-java17.md` |
+
+`references/source-index.md` only routes to these tracks. Refresh and freshness checks must keep the platform line and source root paired.
+
 | Skill | Backend source path hints |
 | --- | --- |
 | `yss-cache` | `yss-microservice-components/yss-component-cache-parent` |
 | `yss-mybatis` | `yss-microservice-components/yss-component-persistence` |
 | `yss-dto` | `yss-microservice-components/yss-component-dto` |
 | `yss-audit-log` | `yss-microservice-components/yss-component-audit-log` |
-| `yss-excel-mvc` | `yss-microservice-components/yss-component-excel-mvc`, `yss-microservice-components/yss-component-excel-starter` |
+| `yss-excel-mvc` | Boot 2: `yss-microservice-components/yss-component-excel-mvc`, `yss-microservice-components/yss-component-excel-starter`; Boot 3: `yss-microservice-components/yss-component-excel-mvc` |
 | `yss-distributed-id` | `yss-microservice-components/yss-component-distributed-id`, `yss-microservice-components/yss-component-leaf` |
 | `yss-resilience4j` | `yss-microservice-components/yss-component-resilience4j-starter` |
-| `yss-validation` | `yss-microservice-components/yss-component-validation-engine-parent`, `yss-microservice-components/yss-component-validation-jsr303` |
+| `yss-validation` | `yss-microservice-components/yss-component-validation-jsr303`；历史 `yss-component-validation-engine-parent` 在当前组件仓不存在，相关 EL/parser 路由保持 blocked |
 | `yss-security-algorithm` | `yss-microservice-components/yss-component-security-algorithm` |
 | `yss-userinfo` | `yss-microservice-components/yss-component-userinfo-starter` |
 | `yss-exception` | `yss-microservice-components/yss-component-exception` |
@@ -24,5 +31,6 @@ Frontend docs are written to these skills:
 | --- | --- |
 | `yss-ui` | components, hooks, skills docs |
 | `yss-hook` | hooks docs |
-| `yss-use-table-height` | hooks docs |
-| `yss-use-tree-height` | hooks docs |
+| `ytable-usage` | hooks docs |
+| `yedit-table-usage` | hooks docs |
+| `ytree-usage` | hooks docs |

package/template/.codex/skills/yss-skill-source-index-refresh/scripts/check-backend-skill-source-index.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { BACKEND, BACKEND_PLATFORM_LINES, assertSourcePlatformLine, backendComponentPaths, backendPlatformIndexPath, sourceState } from "./refresh-yss-skill-index.mjs";
+
+export async function checkBackendSkillSourceIndex({ skill, platformLine, skillsRoot, sourceRoot }) {
+  if (!BACKEND[skill]) throw new TypeError(`unknown backend component skill: ${skill}`);
+  if (!BACKEND_PLATFORM_LINES[platformLine]) throw new TypeError(`unknown backend component platform line: ${platformLine}`);
+  await assertSourcePlatformLine(sourceRoot, platformLine);
+  const componentPaths = backendComponentPaths(skill, platformLine);
+  const indexPath = backendPlatformIndexPath(skillsRoot, skill, platformLine);
+  const contents = await readFile(indexPath, "utf8");
+  const problems = [];
+  if (!contents.includes("Index schema: `backend-component-source-index-v2`")) problems.push("index schema is not backend-component-source-index-v2");
+  if (!contents.includes(`Platform line: \`${platformLine}\``)) problems.push(`platform line is not ${platformLine}`);
+  if (!contents.includes("## Platform Signals")) problems.push("platform signals are missing");
+  const indexedTrees = new Map([...contents.matchAll(/^Component tree `([^`]+)`: `([^`]+)`$/gm)]
+    .map((match) => [match[1], match[2]]));
+  if (indexedTrees.size !== componentPaths.length || componentPaths.some((item) => !indexedTrees.has(item))) problems.push("component tree set does not match the skill mapping");
+  const current = sourceState(sourceRoot, componentPaths);
+  if (current.componentWorktree !== "clean") problems.push(`component worktree is ${current.componentWorktree}`);
+  for (const item of current.componentTrees) {
+    const indexed = indexedTrees.get(item.path);
+    if (!/^[a-f0-9]{40}$/.test(item.tree)) problems.push(`${item.path} is not present in the current Git commit`);
+    else if (indexed !== item.tree) problems.push(`${item.path} tree changed: indexed=${indexed ?? "missing"}, current=${item.tree}`);
+  }
+  if (problems.length) throw new Error(`stale source index for ${skill}: ${problems.join("; ")}`);
+  return { skill, indexPath, componentPaths, componentTrees: current.componentTrees };
+}
+
+function parseArgs(argv) {
+  const result = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const name = argv[i];
+    if (!["--skill", "--platform-line", "--source-root", "--skills-root"].includes(name) || !argv[i + 1]) throw new TypeError("usage: check-backend-skill-source-index.mjs --skill <id> --platform-line <boot2-java8|boot3-java17> --source-root <root> [--skills-root <canonical-root>]");
+    result[name.slice(2).replaceAll("-", "_")] = argv[++i];
+  }
+  if (!result.skill || !result.platform_line || !result.source_root) throw new TypeError("usage: check-backend-skill-source-index.mjs --skill <id> --platform-line <boot2-java8|boot3-java17> --source-root <root> [--skills-root <canonical-root>]");
+  return result;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const result = await checkBackendSkillSourceIndex({
+    skill: args.skill,
+    platformLine: args.platform_line,
+    sourceRoot: path.resolve(args.source_root),
+    skillsRoot: path.resolve(args.skills_root ?? path.join(scriptDir, "../..")),
+  });
+  console.log(JSON.stringify({ status: "fresh", skill: result.skill, platform_line: args.platform_line, components: result.componentPaths }, null, 2));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}