fix azure-upgrade: improve Java Azure SDK BOM migration reliability

[XiaofeiCao]

Summary

• Tighten Java Azure SDK BOM migration guidance so agents must resolve the latest stable azure-sdk-bom from the Azure SDK source of truth during planning and validation.
• Update upgrade_bom.py to resolve the latest BOM internally, reject explicit version pins, enforce the supported stable-version floor, and keep the latest token only as a compatibility alias.
• Refresh Java migration guidance for Maven, Gradle, TOML catalogs, and validation so the resolved TARGET_AZURE_SDK_BOM_VERSION is carried through the full migration workflow.
• Refactor Java migration integration tests to use remote sample projects from java-update-examples via sparse checkout instead of storing local fixtures.

Benchmark impact

The benchmark pass rate improved from 60%+ to 94%+:

• Before: https://msbenchapp.azurewebsites.net/run-analysis/25540122197
• After: https://msbenchapp.azurewebsites.net/run-analysis/25898537401

Validation

• cd scripts && npm run references
• git --no-pager diff --check

Note: cd scripts && npm run frontmatter currently reports existing placeholder-version validation errors for plugin skills that use metadata.version: "0.0.0-placeholder"; this is unrelated to the changes in this PR.

integration tests pass:

[weidongxu-microsoft]

agent comment

 2. _parse_stable_semver return type hint — Uses tuple[int, int, int] (Python
  3.9+ syntax). The docstring says Python 3.8+ is required. Should use Tuple[int, int, int] from typing for 3.8 compat, or from __future__ import 
annotations.
 3. _resolve_latest_bom_version type hint — Uses str | None (Python
  3.10+), same 3.8 compat issue. Should use Optional[str]
 4. Network dependency in script — upgrade_bom.py now always fetches from GitHub on every run. No caching or timeout handling visible in the diff. If the
fetch fails mid-migration, the error path should be clear.

[XiaofeiCao]

agent comment

 2. _parse_stable_semver return type hint — Uses tuple[int, int, int] (Python
  3.9+ syntax). The docstring says Python 3.8+ is required. Should use Tuple[int, int, int] from typing for 3.8 compat, or from __future__ import 
annotations.
 3. _resolve_latest_bom_version type hint — Uses str | None (Python
  3.10+), same 3.8 compat issue. Should use Optional[str]
 4. Network dependency in script — upgrade_bom.py now always fetches from GitHub on every run. No caching or timeout handling visible in the diff. If the
fetch fails mid-migration, the error path should be clear.

Thanks.

• updated compatibility to 3.10+, to align with SKILL.md
• cached HTTP result
• explicit instructions on script failure

[Copilot]

Pull request overview

This PR tightens the azure-upgrade Java BOM migration workflow by forcing agents/tools to resolve the latest stable azure-sdk-bom from the Azure SDK for Java source-of-truth, and updates integration tests to use pinned remote sample projects (sparse checkout) instead of local fixtures.

Changes:

• Updated Java migration docs/templates to carry TARGET_AZURE_SDK_BOM_VERSION through planning and validation, and to re-resolve/verify the latest stable BOM at validation time.
• Updated upgrade_bom.py to internally resolve the latest BOM, reject explicit version pins, enforce a minimum stable BOM floor, and keep latest only as a compatibility token.
• Refactored azure-upgrade Java integration tests to pull sample projects from java-update-examples via sparse checkout (removing local fixture projects).

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/azure-upgrade/resources/java-legacy-sdk-eventhubs/src/main/java/com/microsoft/azure/eventprocessorhosts/EventProcessor.java	Removed local Java fixture source (now sourced from remote examples).
tests/azure-upgrade/resources/java-legacy-sdk-eventhubs/src/main/java/com/microsoft/azure/eventprocessorhosts/ErrorNotificationHandler.java	Removed local Java fixture source (now sourced from remote examples).
tests/azure-upgrade/resources/java-legacy-sdk-eventhubs/src/main/java/com/microsoft/azure/eventprocessorhosts/Consumer.java	Removed local Java fixture source (now sourced from remote examples).
tests/azure-upgrade/resources/java-legacy-sdk-eventhubs/README.md	Removed local fixture documentation.
tests/azure-upgrade/resources/java-legacy-sdk-eventhubs/pom.xml	Removed local Maven fixture config.
tests/azure-upgrade/resources/java-legacy-sdk-eventhubs/.gitignore	Removed local fixture ignore file.
tests/azure-upgrade/resources/java-legacy-sdk-client-init/src/main/java/com/example/legacy/App.java	Removed local Java fixture source (now sourced from remote examples).
tests/azure-upgrade/resources/java-legacy-sdk-client-init/README.md	Removed local fixture documentation.
tests/azure-upgrade/resources/java-legacy-sdk-client-init/pom.xml	Removed local Maven fixture config.
tests/azure-upgrade/resources/java-legacy-sdk-client-init/.gitignore	Removed local fixture ignore file.
tests/azure-upgrade/resources/java-legacy-sdk-batch/src/main/java/com/fabrikam/azure/batch/BatchManagementHelper.java	Removed local Java fixture source (now sourced from remote examples).
tests/azure-upgrade/resources/java-legacy-sdk-batch/README.md	Removed local fixture documentation.
tests/azure-upgrade/resources/java-legacy-sdk-batch/pom.xml	Removed local Maven fixture config.
tests/azure-upgrade/resources/java-legacy-sdk-batch/.gitignore	Removed local fixture ignore file.
tests/azure-upgrade/integration.test.ts	Switches Java migration E2E tests to sparse-checkout remote examples and improves legacy-dependency assertions.
plugin/skills/azure-upgrade/references/languages/java/templates/SUMMARY_TEMPLATE.md	Replaces hardcoded BOM version in template with <TARGET_AZURE_SDK_BOM_VERSION>.
plugin/skills/azure-upgrade/references/languages/java/scripts/upgrade_bom.py	Resolves latest BOM internally, rejects explicit pins, validates stable semver + minimum supported floor.
plugin/skills/azure-upgrade/references/languages/java/rules/upgrade-strategy.md	Updates guidance to Python 3.10+ and clarifies manual fallback behavior.
plugin/skills/azure-upgrade/references/languages/java/README.md	Minor wording tweak for plan phase reference.
plugin/skills/azure-upgrade/references/languages/java/package-specific/com.microsoft.azure.management.md	Clarifies env-var auth vs file-based auth and updates heading escaping.
plugin/skills/azure-upgrade/references/languages/java/INSTRUCTION.md	Tightens plan/validation requirements to record and enforce TARGET_AZURE_SDK_BOM_VERSION.
plugin/skills/azure-upgrade/references/languages/java/bom-migration/bom-validation.md	Updates validation checklist to re-resolve and match TARGET_AZURE_SDK_BOM_VERSION.
plugin/skills/azure-upgrade/references/languages/java/bom-migration/bom-migration.md	Updates BOM resolution rules and script usage to avoid version pinning.
plugin/skills/azure-upgrade/references/languages/java/bom-migration/bom-maven.md	Updates Maven automation instructions to script-resolved BOM and expands fallback guidance.
plugin/skills/azure-upgrade/references/languages/java/bom-migration/bom-gradle.md	Updates Gradle automation instructions to script-resolved BOM and expands fallback guidance.
plugin/skills/azure-upgrade/references/languages/java/bom-migration/bom-gradle-toml.md	Adds requirement to use TARGET_AZURE_SDK_BOM_VERSION in TOML catalogs.
plugin/skills/azure-upgrade/references/languages/java/bom-migration/bom-gradle-settings.md	Adds requirement to use TARGET_AZURE_SDK_BOM_VERSION in programmatic catalogs.

[jongio]

The BOM-resolution hardening and the switch from explicit version pins to auto-resolve look good - cleaner UX for agents and prevents stale versions. One concern about test resilience below.

[fanyang-mono]

This PR needs to be signed off by @XiaofeiCao's team.

[weidongxu-microsoft]

SDK dev has started moving the test data to e.g. Azure org, maybe azure-sdk-for-java-update-test-data. It likely going to take a few more days, as we discuss the org and repo name.

[XiaofeiCao]

@jongio Would you help approve the PR? Thanks!