create-yss-spec 3.4.5 → 3.4.6

package/template/.pi/skills/yss-technical-design/references/mvc-design.schema.json

@@ -0,0 +1,315 @@
+{
+  "type": "object",
+  "properties": {
+    "module_catalog": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "module_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "responsibility": {
+            "type": "string",
+            "minLength": 1
+          },
+          "layer": {
+            "enum": [
+              "server",
+              "service",
+              "core",
+              "repository",
+              "adapter",
+              "client",
+              "feign-client"
+            ]
+          },
+          "depends_on": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true
+          }
+        },
+        "required": [
+          "module_id",
+          "responsibility",
+          "layer",
+          "depends_on"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "use_case_catalog": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "use_case_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "module_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "flow": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true,
+            "minItems": 1
+          },
+          "rule_refs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true,
+            "minItems": 1
+          },
+          "failure_handling": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "use_case_id",
+          "module_ref",
+          "flow",
+          "rule_refs",
+          "failure_handling"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "rule_catalog": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "rule_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "statement": {
+            "type": "string",
+            "minLength": 1
+          },
+          "use_case_refs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true,
+            "minItems": 1
+          }
+        },
+        "required": [
+          "rule_id",
+          "statement",
+          "use_case_refs"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "state_transition_catalog": {
+      "type": "array",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "properties": {
+          "transition_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "use_case_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "from": {
+            "type": "string",
+            "minLength": 1
+          },
+          "to": {
+            "type": "string",
+            "minLength": 1
+          },
+          "guard": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "transition_id",
+          "use_case_ref",
+          "from",
+          "to",
+          "guard"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "state_not_applicable_reason": {
+      "type": "string"
+    },
+    "consistency_policy": {
+      "type": "object",
+      "properties": {
+        "transaction_boundary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "rollback": {
+          "type": "string",
+          "minLength": 1
+        },
+        "concurrency": {
+          "type": "string",
+          "minLength": 1
+        },
+        "idempotency": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "transaction_boundary",
+        "rollback",
+        "concurrency",
+        "idempotency"
+      ],
+      "additionalProperties": false
+    },
+    "persistence_mapping": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "mapping_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "use_case_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "repository_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "storage_model": {
+            "type": "string",
+            "minLength": 1
+          },
+          "notes": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "mapping_id",
+          "use_case_ref",
+          "repository_ref",
+          "storage_model",
+          "notes"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "integration_catalog": {
+      "type": "array",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "properties": {
+          "integration_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "adapter_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "capability": {
+            "type": "string",
+            "minLength": 1
+          },
+          "failure_handling": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "integration_id",
+          "adapter_ref",
+          "capability",
+          "failure_handling"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "integration_not_applicable_reason": {
+      "type": "string"
+    },
+    "test_seams": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "seam_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "kind": {
+            "type": "string",
+            "minLength": 1
+          },
+          "subject_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "assertion": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "seam_id",
+          "kind",
+          "subject_ref",
+          "assertion"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "module_catalog",
+    "use_case_catalog",
+    "rule_catalog",
+    "state_transition_catalog",
+    "state_not_applicable_reason",
+    "consistency_policy",
+    "persistence_mapping",
+    "integration_catalog",
+    "integration_not_applicable_reason",
+    "test_seams"
+  ],
+  "additionalProperties": false,
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.dev/schemas/mvc-design-v1.json",
+  "title": "YSS MVC 技术设计内容"
+}

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

@@ -1,6 +1,6 @@
 # Technical Design Contract v2
 
-共同合同字段由 `technical-design-common.schema.json` 定义，完整 `technical-design.schema.json` 通过 `scripts/generate-schema.mjs` 合并专项 Schema 派生，使用 `--check` 检查同步，`design` 按 `architecture.family` 校验：`domain-driven` 沿用 DDD v1 内容结构，`layered-mvc` 使用 `yss-mvc-design/references/mvc-design.schema.json`。DDD 内层的 schema/version/status 是分支内容版本，status 必须与共同头一致；战略交接绑定只写共同头，避免双重维护。
+共同合同字段由 `technical-design-common.schema.json` 定义，完整 `technical-design.schema.json` 通过 `scripts/generate-schema.mjs` 合并专项 Schema 派生，使用 `--check` 检查同步，`design` 按 `architecture.family` 校验：`domain-driven` 沿用 DDD v1 内容结构，`layered-mvc` 使用本 skill 的 `references/mvc-design.schema.json`。DDD 内层的 schema/version/status 是分支内容版本，status 必须与共同头一致；战略交接绑定只写共同头，避免双重维护。历史 `yss-mvc-design/references/mvc-design.schema.json` 只用于退役期等价核验，不是新合同依赖。
 
 ## 共同头
 

package/template/.pi/skills/yss-technical-design/scripts/generate-schema.mjs

@@ -5,7 +5,7 @@ const load = ref => JSON.parse(readFileSync(new URL(ref, import.meta.url), 'utf8
 const schema = load('../references/technical-design-common.schema.json');
 const branches = [
   ['domain-driven', '../../yss-tactical-design/references/tactical-design.schema.json'],
-  ['layered-mvc', '../../yss-mvc-design/references/mvc-design.schema.json']
+  ['layered-mvc', '../references/mvc-design.schema.json']
 ];
 schema.$comment = 'Generated by scripts/generate-schema.mjs from common and specialist schemas. Do not hand-edit.';
 schema.allOf = branches.map(([family, ref]) => {

package/template/.pi/skills/yss-technical-design/tests/run-scenarios.mjs

@@ -14,6 +14,9 @@ import { loadSkillRegistry } from '../../../../scripts/lib/skill-registry.mjs';
 const root = mkdtempSync(path.join(tmpdir(), 'yss-technical-design-'));
 let checks = 0;
 try {
+  const activeMvcSchema = JSON.parse(readFileSync(fileURLToPath(new URL('../references/mvc-design.schema.json', import.meta.url)), 'utf8'));
+  const deprecatedMvcSchema = JSON.parse(readFileSync(fileURLToPath(new URL('../../yss-mvc-design/references/mvc-design.schema.json', import.meta.url)), 'utf8'));
+  assert.deepEqual(activeMvcSchema, deprecatedMvcSchema); checks++;
   const mvc = mvcFixture(root);
   const validate = data => validateTechnicalDesign(data, { root });
   assert.equal((await validate(mvc)).architecture_family, 'layered-mvc'); checks++;
@@ -74,7 +77,7 @@ try {
   enforceTechnicalDesign(state, { root }); checks++;
   assert.throws(() => enforceTechnicalDesign({ ...state, technical_design: undefined }, { root }), /缺少已批准技术设计/); checks++;
   assert.throws(() => enforceTechnicalDesign({ ...state, architecture_identity: { architecture_family: 'domain-driven' } }, { root }), /架构不匹配/); checks++;
-  const resolution = compileDefaultImplementationContract({ ...state, root, requiredCapabilities: ['contract.request-validation'], architecture_evidence: { engineering_baseline: identity, repository_registration: identity, manifest: identity } });
+  const resolution = compileDefaultImplementationContract({ ...state, root, requiredCapabilities: ['quality.java-code-style'], architecture_evidence: { engineering_baseline: identity, repository_registration: identity, manifest: identity } });
   assert.deepEqual(resolution.technical_design, technical_design); assert(!resolution.required_skills.includes('yss-domain')); checks++;
   writeFileSync(path.join(root, 'spec.md'), 'changed again');
   assert.equal(evaluateContractFreshness({ schema_version: 2, resolution }, { registry: loadSkillRegistry(), compilerContract: loadCompilerContract(), root }).freshness, 'stale'); checks++;

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

@@ -5,24 +5,33 @@ description: "审查或迁移 YSS Spring Boot 2 到 3 的依赖、Jakarta 与 Sp
 
 # yss-up-springboot3
 
-Use this skill for YSS backend upgrade analysis and migration tasks around Spring Boot 3 / Spring Cloud compatibility.
+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.
 
-中文说明：这个技能是升级核查入口，不替代具体组件技能。遇到缓存、审计、MyBatis、DTO、Excel、JDBC 等组件细节时，应同时读取对应专项技能和源码索引。
+中文说明：这个技能是平台迁移编排入口，不替代具体组件 Skill。源平台、目标平台和组件能力只从 `docs/engineering/backend-platforms.json`、批准的 `platform_configuration`、工程 Manifest、effective POM 与实际依赖树解析，不按版本记忆或源码可编译状态推断兼容。
 
 ## When To Use
 
-- The user asks to upgrade YSS backend code to Spring Boot 3 or newer Spring Cloud baselines.
+- The user asks to assess or migrate a YSS backend from Spring Boot 2 to Spring Boot 3.
 - The task mentions `javax.*` to `jakarta.*`, Spring Security migration, validation changes, Servlet API changes, Gateway/OpenFeign compatibility, or dependency BOM changes.
 - The task involves checking whether a YSS component can run on Spring Boot 3.
 
+## 准入与阻断
+
+- 先运行 `scripts/backend-platforms` 查询精确 profile。目标 profile 不可选择、缺 compatibility 条目或任一必需 `component_capabilities` 不是 `verified` 时，只能输出差距分析，迁移实现返回 `component-unavailable-for-platform` 或对应组件绑定错误。
+- Spring Boot 4 不属于本 Skill 的 2→3 迁移执行范围。Boot 4 命中 Jackson 3、starter/自动配置结构或现有 YSS 组件时返回 `blocked`，建立独立平台迁移工作单元；不得把已完成的 Boot 3 改造解释为 Boot 4 兼容。
+- 既有工程的源码编译、单元测试或 `javax`→`jakarta` 替换不等于平台认证。没有目标架构的真实构件、启动和组件 seam 证据时不得宣称迁移完成。
+- 平台迁移不得夹带业务重构、架构族转换或组件替换。发现这些影响时返回 `new_impacts`，交实现合同编译器重新路由。
+
 ## Workflow
 
-1. Identify affected modules and current dependency versions from the local repository.
-2. Check for Jakarta namespace changes (`javax.servlet`, `javax.validation`, `javax.annotation`, JPA APIs, and related imports).
-3. Check Spring Security configuration style, deprecated adapters, authorization server dependencies, and filter registration behavior.
-4. Check component-specific integration by loading specialist skills such as `yss-mybatis`, `yss-dto`, `yss-cache`, `yss-audit-log`, `yss-excel-mvc`, or `yss-jdbc`.
-5. Prefer source-backed evidence from the local workspace or a source root resolved via `yss-skill-source-index-refresh/references/source-location.md` before recommending code changes.
-6. Produce an upgrade checklist or patch with explicit compatibility risks and verification commands.
+1. 从工程登记、Manifest、父/BOM、effective POM 和依赖树冻结源 `platform_configuration`、架构 Profile、全部 YSS GAV、组件绑定及基线验证命令；缺失或相互冲突时停止。
+2. 从平台目录选择一个精确 Spring Boot 3 目标 profile，记录 compatibility id/digest；不得使用 `3.x`、`latest`、范围版本或自行拼装父/BOM。
+3. 由当前 Slice/迁移合同解析所需 capability，再逐项核验目标 profile 的组件状态、架构证据、timestamped SNAPSHOT、POM/JAR 摘要和源码 tree。未登记的 JDBC 等能力记为缺口，不虚构 `yss-jdbc` Skill 或绕过 catalog。
+4. 按命中能力加载已登记专项 Skill，例如 `yss-mybatis`、`yss-dto`、`yss-validation`、`yss-exception`、`yss-cache`、`yss-audit-log`、`yss-excel-mvc`、`yss-userinfo`、`yss-resilience4j` 和 `yss-security-algorithm`；分别用 `boot2-java8` 与 `boot3-java17` 索引核验源/目标组件 tree，源码索引只用于定位风险，不代替 compatibility evidence。
+5. 编制迁移增量：Java 与编译插件、Servlet/Validation/JPA namespace、Spring Security、Spring Cloud/OpenFeign、MyBatis starter、自动配置注册、配置属性、Jackson 2 wire 行为、测试工具和打包方式。`javax.sql`、`javax.crypto` 等 Java SE API 不迁移。
+6. 在批准的迁移工作单元内分批实施，每批保持可构建和可回滚；组件坐标或平台配方发生变化时重新编译合同，不在业务代码中临时替换依赖。
+7. 使用工程根 `./mvnw` 记录 effective POM、依赖树、`validate`、`test`、`package`、随机端口启动和真实组件 seam；DDD 与 MVC 证据不可互相代替。
+8. 重新解析全部组件绑定并比较摘要；通过只表示该工程的批准迁移结果，不自动把共享平台或其他工程标记为 verified。
 
 ## Common Checks
 
@@ -32,9 +41,14 @@ Use this skill for YSS backend upgrade analysis and migration tasks around Sprin
 - Validation annotations and exception handlers still map to the expected DTO/Result contract.
 - MyBatis interceptors, auto configurations, and starter metadata are compatible with Spring Boot 3 auto-configuration loading.
 - Tests or sample modules are updated together with framework code.
+- Jackson 2 的 Result/PageResult、日期、枚举、nullability 和错误响应 wire fixture 与冻结 OpenAPI 一致。
+- `spring.factories` 与 `AutoConfiguration.imports` 的目标机制以真实 starter 为准，不能仅移动文件名后宣称自动配置生效。
+- 输出包含源/目标 profile、compatibility digest、组件逐项结论、阻塞项、实际命令与回滚点。
 
 ## Do Not
 
 - Do not blindly rewrite all `javax.*` imports without checking whether the dependency still uses the old namespace.
 - Do not mix unrelated business refactors into migration patches.
 - Do not assume component compatibility from memory; inspect source and specialist skill indexes.
+- Do not bypass a blocked component by excluding its starter, copying component code into the service, or substituting an unapproved third-party dependency.
+- Do not execute a Boot 4 migration under this Skill or reuse Boot 3 evidence for Boot 4.

package/template/.pi/skills/yss-userinfo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-userinfo
-description: "接入或排查 YSS AuthUserInfoUtil、用户头透传、JWT、Redis 用户缓存与后台用户上下文。"
+description: "接入或排查 YSS CurrentUserProvider、已认证 SecurityContext、受信网关头适配与后台用户上下文。"
 ---
 
 # yss-userinfo
@@ -19,31 +19,38 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 
 ## Workflow
 
-1. Identify whether the task is current-user lookup, request header propagation, JWT parsing, Redis user cache lookup, or non-REST/background fallback behavior.
-2. Read `references/source-index.md`, then inspect `AuthUserInfoUtil`, `DmUser`, and `DmUserDetails`.
-3. Prefer `AuthUserInfoUtil.userInfo()`, `userName()`, `userCode()`, or `currentUserJson()` over manually parsing headers in business code, but treat the result as propagated context, not as JWT signature verification.
-4. Check lookup order before debugging: `X-Username`/`X-Usercode`/`X-LoginDisplayName` headers, Bearer JWT payload, then Redis cache via `CacheManagerCompose`.
-5. For scheduled/background tasks, expect fallback behavior such as default `system` user unless the caller explicitly provides context.
+1. 先按已批准平台线读取对应索引；以下当前行为针对 `boot3-java17`，Boot 2 旧工程只按其独立索引做只读分诊和迁移。
+2. Identify whether the task is authenticated current-user lookup, an explicitly trusted gateway adapter, a custom `CurrentUserProvider`, or non-REST/background fallback behavior.
+3. Read `references/source-index.md`, then inspect `CurrentUserProvider`, `SecurityContextCurrentUserProvider`, `TrustedGatewayHeaderCurrentUserProvider`, `AuthUserInfoUtil`, `DmUser`, and `DmUserDetails`.
+4. 默认使用 `SecurityContextCurrentUserProvider`，只消费 Spring Security 已认证且非 anonymous 的 `Authentication`。JWT 的 signature、issuer、audience、expiry 与算法校验必须在资源服务器认证链完成。
+5. `AuthUserInfoUtil` 是由 `CurrentUserProvider` 驱动的兼容 facade；业务代码可继续调用 `userInfo()`、`userName()`、`userCode()` 或 `currentUserJson()`，但不得自行解析 Header、JWT payload 或 Redis 身份缓存。
+6. 只有显式启用 `yss.userinfo.trusted-gateway.enabled` 且配置非空 `trusted-proxies` 时，才启用 `TrustedGatewayHeaderCurrentUserProvider`；它只接受 remote address 在 allow-list 中的请求，并且 SecurityContext 结果优先。
+7. For scheduled/background tasks, an empty provider result causes the compatibility facade to return the distinct `system` fallback; do not represent it as an authenticated system principal.
 
 ## Source-Backed Notes
 
-- Header names include `X-Username`, `X-Usercode`, and `X-LoginDisplayName`.
-- Bearer token parsing reads payload fields such as `sub`, `loginDisplayName`, `email`, and `userCode` without verifying signature/issuer/audience/expiry in this utility. Authentication decisions must use a verified security context.
-- The current source has a known reversed `userCode` header assignment condition; do not claim that header path is reliable until fixed and tested.
-- Redis cache lookup uses the JWT user-info cache key path; load `yss-cache` if changing cache behavior.
+- `SecurityContextCurrentUserProvider` supports a `UserInfo` principal and an authenticated `OAuth2AuthenticatedPrincipal`; claim mapping happens only after authentication.
+- Trusted gateway header names are `X-Username`, `X-Usercode`, and `X-LoginDisplayName`; the adapter requires a trusted proxy allow-list and a nonblank username.
+- `UserInfoAutoConfiguration` installs SecurityContext as the default and composes the optional gateway provider behind it. A project-supplied `CurrentUserProvider` remains the explicit extension seam.
+- The Boot 3 component does not parse an unverified Bearer payload and does not use Redis as an authentication fallback. Cache behavior is outside this identity provider contract.
 
 ## Checklist
 
 - Required dependency or starter module is present.
 - Request context exists before relying on servlet headers.
-- Gateway/auth service forwards expected user headers or Authorization token.
-- Cache fallback is checked when headers exist but detailed user info is incomplete.
-- Business code does not duplicate JWT parsing logic.
-- Header/JWT/cache/background precedence and overwrite behavior are covered by tests; `system` fallback is distinguished from an authenticated system user.
+- Spring Security has authenticated the request before the provider reads the principal.
+- When trusted gateway mode is enabled, at least one proxy address is allow-listed and untrusted remote addresses are rejected.
+- Business code does not duplicate JWT or header parsing logic.
+- SecurityContext/gateway/background precedence and empty-result behavior are covered by tests; `system` fallback is distinguished from an authenticated system user.
 - User info propagation is tested for REST calls and async/background execution separately.
 
 ## 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 treat raw `Authorization` payloads or gateway headers as authenticated identity.
 - Do not broaden the task into unrelated YSS components unless the user asks.
+
+## 平台与源码门禁
+
+接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../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-userinfo --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。

package/template/.pi/skills/yss-userinfo/references/source-index.boot2-java8.md

@@ -0,0 +1,49 @@
+# yss-userinfo Source Index
+
+Index schema: `backend-component-source-index-v2`
+Platform line: `boot2-java8`
+Generated: 2026-09-18T18:40:26.031Z
+Source commit: `a3be2b2e33dca4545782e2b31894aaa00d0305cd`
+Component worktree: `clean`
+Component tree `yss-microservice-components/yss-component-userinfo-starter`: `fc77d57e0be6ee81b10247c0746baed6a09c6bb4`
+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-userinfo-starter` (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-userinfo-starter/pom.xml` — GAV `com.yss.cloud:yss-component-userinfo-starter:2.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-microservice-components:2.0.0-SNAPSHOT`
+
+## Platform Signals
+
+- Inherited Java signals: `1.8`.
+- Inherited Spring Boot signals: `2.7.18`.
+- Namespace source signals: `javax.*` in 1 main Java files; `jakarta.*` in 0 main Java files.
+- Auto-configuration metadata: 0 `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-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUser.java` — `sha256:c25b546485977a7e28c23ed22735e0ea43eb166f6a856e43159b7d40677570fe`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUserDetails.java` — `sha256:ab34afc0f0e28fe85b405e56b12ee08b57884cfc120b6bd5d8b0e8e095e51a2c`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/AuthUserInfoUtil.java` — `sha256:2ed38a6357a7cc5a057cdb8c6e105c3d2c7455ede0ec1e822d36b7dbcd04df83`
+
+## 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/.pi/skills/yss-userinfo/references/source-index.boot3-java17.md

@@ -0,0 +1,54 @@
+# yss-userinfo Source Index
+
+Index schema: `backend-component-source-index-v2`
+Platform line: `boot3-java17`
+Generated: 2026-09-18T18:40:26.031Z
+Source commit: `5041c41fbe96c25821bbc15f688c0521b8c97a3d`
+Component worktree: `clean`
+Component tree `yss-microservice-components/yss-component-userinfo-starter`: `96c79dcb754df0dbcc59a465e45d6871601275ff`
+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-userinfo-starter` (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-userinfo-starter/pom.xml` — GAV `com.yss.cloud:yss-component-userinfo-starter:3.0.0-SNAPSHOT`; parent `com.yss.cloud:yss-microservice-components:3.0.0-SNAPSHOT`
+
+## Platform Signals
+
+- Inherited Java signals: `17`.
+- Inherited Spring Boot signals: `3.5.16`.
+- Namespace source signals: `javax.*` in 0 main Java files; `jakarta.*` in 1 main Java files.
+- Auto-configuration metadata: 0 `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-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUser.java` — `sha256:c25b546485977a7e28c23ed22735e0ea43eb166f6a856e43159b7d40677570fe`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUserDetails.java` — `sha256:ab34afc0f0e28fe85b405e56b12ee08b57884cfc120b6bd5d8b0e8e095e51a2c`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/AuthUserInfoUtil.java` — `sha256:e3c8cd0f18754644a95ccccb76a7ae66d5446af35f683a212daf7566b13a7eaf`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/CurrentUserProvider.java` — `sha256:4f76eab3eb10a24af0a3f40eacfbac6a7f1d367af532c6c30cf25d118ba4d1fa`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/SecurityContextCurrentUserProvider.java` — `sha256:fd83da91f69c016623c13efc33ef85de3dcc5864fb7ee42de3a0054a7c6d9e70`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/TrustedGatewayHeaderCurrentUserProvider.java` — `sha256:72c8e5e1f60e90f02685ec2e494efc0271ee35ddf2df989b96f3b76aa0401737`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/config/TrustedGatewayUserInfoProperties.java` — `sha256:30f34ac4b4d43f854e46d5078dd6ed84e86280a4c0150508091cd557919ddab2`
+- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/config/UserInfoAutoConfiguration.java` — `sha256:4bfc378fcba4f6dbb8f1bcc8e3ea4ee7c8fc9908f68cfb187c7945ebeee4dead`
+
+## 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/.pi/skills/yss-userinfo/references/source-index.md

@@ -1,34 +1,10 @@
-# yss-userinfo Source Index
+# yss-userinfo 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-userinfo-starter` (existed when indexed)
-
-## Documentation Files
-
-- No component documentation files found.
-
-## Maven Modules
-
-- `yss-microservice-components/yss-component-userinfo-starter`
-
-## Key Java Entry Points
-
-- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUser.java`
-- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/domain/DmUserDetails.java`
-- `yss-microservice-components/yss-component-userinfo-starter/src/main/java/com/yss/cloud/user/AuthUserInfoUtil.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.