create-yss-spec 3.4.4 → 3.4.6

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

package/template/.agents/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;
+  });
+}