<!--
  This is the upgrade plan template generated by the "Generate Upgrade Plan" agent.
  SESSION_ID should be replaced with the actual session id.

  ## PLANNING RULES

  !!! DON'T REMOVE THIS COMMENT BLOCK BEFORE FINAL PLAN IS GENERATED AS IT CONTAINS IMPORTANT INSTRUCTIONS.

  ### Strategy
  - **Incremental upgrades**: Use intermediates to avoid large jumps breaking builds
  - **Minimal changes**: Only upgrade dependencies essential for compatibility
  - **Risk-first**: Handle EOL/challenging deps early in isolated steps
  - **Necessary/Meaningful steps only**: Each step MUST change code/config. NO steps for pure analysis/validation. Merge small related changes.

  ### Intermediate Version Strategy
  Use intermediates when direct upgrade risks breaking builds. Good intermediate has:
  - **Stability**: Stable LTS release with production track record
  - **Compatibility bridge**: Bridges compatibility between current and target versions

  ### Mandatory Steps
  - **Step 1 (MANDATORY)**: Setup Environment - Install all JDKs/build tools marked `<TO_BE_INSTALLED>`
  - **Step 2 (MANDATORY)**: Setup Baseline - Run compile/test with current JDK, document results.
  - **Steps 3-N**: Upgrade steps - dependency order, high-risk early, isolated breaking changes
  - **Final step (MANDATORY)**: Final Validation - verify all goals met, all TODOs resolved, 100% tests pass (if tests enabled in Options)

  ### Verification Expectations
  - **Steps 1-N (Setup/Upgrade)**: Focus on COMPILATION SUCCESS. Tests may fail during intermediate steps.
  - **Final Validation**: COMPILATION SUCCESS + 100% TEST PASS (if tests enabled in Options)
  ### Efficiency (IMPORTANT)
  - **Targeted reads**: Use `grep` over full file reads; read specific sections, not entire files. Template files are large - only read the sections you need.
  - **Quiet commands**: Use `-q`, `--quiet` for build/test commands when appropriate
  - **Progressive writes**: Update plan.md incrementally, not at end
-->

# Upgrade Plan: <PROJECT_NAME> (<SESSION_ID>)

- **Generated**: <datetime> <!-- replace with actual date and time when generating -->
- **HEAD Branch**: <current_branch> <!-- replace with actual head branch; use "N/A" when GIT_AVAILABLE=false -->
- **HEAD Commit ID**: <current_commit_id> <!-- replace with actual head commit id; use "N/A" when GIT_AVAILABLE=false -->

## Available Tools

<!--
  List ONLY the JDKs and build tools that are required/used during the upgrade (not all discovered ones).
  Use #list_jdks and #list_mavens results from Environment Analysis to check availability.
  Mark missing required JDKs as "**<TO_BE_INSTALLED>**" with a note indicating which step needs it.
  Mark build tools that need upgrading for target JDK compatibility as "**<TO_BE_UPGRADED>**".
  If a wrapper (mvnw/gradlew) is present, also check the wrapper-defined version in
  `.mvn/wrapper/maven-wrapper.properties` or `gradle/wrapper/gradle-wrapper.properties`.
  Installation/upgrade happens during execution, not planning.

  BUILD TOOL COMPATIBILITY REFERENCE (non-exhaustive — verify from official docs when uncertain):
  - Maven 3.9+: required for Java 21
  - Maven 4.0+: required for Java 25
  - Gradle 8.5+: required for Java 21 (first full support)
  - Gradle 8.8+: required for Java 22
  - Gradle 9.1+: required for Java 25
  - maven-compiler-plugin 3.11+: required for Java 21
  - maven-surefire-plugin 3.1+: recommended for Java 17+
  - Reference: https://docs.gradle.org/current/userguide/compatibility.html

  NOTE: This section is finalized during Upgrade Path Design (after step sequence is known), not during Environment Analysis.

  SAMPLE:
  **JDKs**
  - JDK 1.8.0: /path/to/jdk-8 (current project JDK, used by step 2)
  - JDK 17: **<TO_BE_INSTALLED>** (required by step 3)
  - JDK 21: **<TO_BE_INSTALLED>** (required by step 6)

  **Build Tools**
  - Maven 3.9.6: /path/to/maven
  - Maven Wrapper: 3.8.1 → **<TO_BE_UPGRADED>** to 3.9.6+ (current version incompatible with Java 21)
-->

## Guidelines

<!--
  User-specified guidelines or constraints in bullet points for this upgrade.
  Extract these from the user's prompt if provided, or leave empty if none specified.
  These guidelines take precedence over default upgrade strategies.
-->

> Note: You can add any specific guidelines or constraints for the upgrade process here if needed, bullet points are preferred. <!-- this note is for users, NEVER remove it -->

## Options

- Working branch: appmod/java-upgrade-<SESSION_ID> <!-- user specified, NEVER remove it -->
- Run tests before and after the upgrade: true <!-- user specified, NEVER remove it -->

## Upgrade Goals

<!--
  List ONLY the explicitly user-requested target versions.
  These are the primary goals that drive all other upgrade decisions.

  SAMPLE:
  - Upgrade Java from 8 to 21
  - Upgrade Spring Boot from 2.5.x to 3.2.x
-->

### Technology Stack

<!--
  Table of core dependencies and their compatibility with upgrade goals.
  IMPORTANT: Analyze ALL modules in multi-module projects, not just the root module.
  Only include: direct dependencies + those critical for upgrade compatibility.
  CRITICAL: Identify and clearly flag EOL (End of Life) dependencies - these pose security risks and must be upgraded.

  Columns:
  - Technology/Dependency: Name of the dependency (mark EOL dependencies with "⚠️ EOL" suffix)
  - Current: Version currently in use
  - Min Compatible Version: Minimum version that works with upgrade goals (or N/A if replaced)
  - Why Incompatible: Explanation of incompatibility, or "-" if already compatible. For EOL deps, mention security/support concerns.

  IMPORTANT: Include build tools (Maven/Gradle), wrappers, and key build plugins in this table.
  Build tools and plugins are upgrade-critical even though they are not runtime dependencies.

  SAMPLE:
  | Technology/Dependency    | Current | Min Compatible | Why Incompatible                               |
  | ------------------------ | ------- | -------------- | ---------------------------------------------- |
  | Java                     | 8       | 21             | User requested                                 |
  | Spring Boot              | 2.5.0   | 3.2.0          | User requested                                 |
  | Spring Framework         | 5.3.x   | 6.1.x          | Spring Boot 3.2 requires Spring Framework 6.1+ |
  | Maven (wrapper)          | 3.6.3   | 3.9.0          | Maven 3.6.x does not support Java 21           |
  | maven-compiler-plugin    | 3.8.1   | 3.11.0         | Older versions cannot compile Java 21 bytecode |
  | maven-surefire-plugin    | 2.22.2  | 3.1.0          | Older versions may fail with Java 17+ module system |
  | Hibernate                | 5.4.x   | 6.1.x          | Spring Boot 3.x requires Hibernate 6+          |
  | javax.servlet ⚠️ EOL     | 4.0     | N/A            | Replaced by jakarta.servlet in Spring Boot 3.x; javax namespace EOL |
  | Log4j ⚠️ EOL             | 1.2.17  | N/A            | EOL since 2015, critical security vulnerabilities; replace with Logback/Log4j2 |
  | DWR ⚠️ EOL             | 3.0.1.rc  | N/A            | EOL since 2017, no longer maintained; consider replacing with modern alternatives |
  | Lombok                   | 1.18.20 | 1.18.20        | -                                              |
-->

| Technology/Dependency | Current | Min Compatible | Why Incompatible |
| --------------------- | ------- | -------------- | ---------------- |

### Derived Upgrades

<!--
  Required upgrades inferred from user targets based on compatibility rules.
  Each derived upgrade must have a justification explaining WHY it's required.
  Common derivations:
  - Spring Boot 3.x → Java 17+, Jakarta EE 9+, Hibernate 6.x, Spring Framework 6.x
  - Spring Boot 3.2+ → Spring Framework 6.1+
  - Spring Boot 4.x → Java 17+, Jakarta EE 10+, Spring Framework 7.x
  - Java 21 → Maven 3.9+, Gradle 8.5+, maven-compiler-plugin 3.11+
  - Java 25 → Maven 4.0+, Gradle 9.1+
  - Build tool upgrade → update wrapper version in `.mvn/wrapper/maven-wrapper.properties` or `gradle/wrapper/gradle-wrapper.properties`

  NOTE: LLM training data may be outdated. If a target version is not recognized,
  verify it from the web before making derivation decisions.

  SAMPLE:
  - Upgrade Spring Framework from 5.3.x to 6.1.x (Spring Boot 3.2 requires Spring 6.1)
  - Upgrade Hibernate from 5.4.x to 6.1.x (Spring Boot 3.x requires Hibernate 6)
  - Migrate from javax.* to jakarta.* (Spring Boot 3.x uses jakarta.*)
  - Upgrade Maven from 3.6.3 to 3.9.6 (Maven 3.6.x does not support Java 21 compilation); update wrapper version
  - Upgrade maven-compiler-plugin from 3.8.1 to 3.11.0 (required for Java 21 target/source)
-->

## Upgrade Steps

<!--
  Step-by-step upgrade plan. Each step should follow this format:
  - **Step N: <Descriptive Title>**
    - **Rationale**: Why this step is needed and why at this position
    - **Changes to Make**: ≤5 bullet points (concise)
    - **Verification**: Command, JDK, Expected Result

  VERIFICATION EXPECTATIONS:
  - Steps 1-N (Setup and Upgrade steps): Focus on COMPILATION SUCCESS. Tests may fail during intermediate steps.
  - Final step: COMPILATION SUCCESS + TEST PASS (if tests enabled in Options) through iterative fix loop.

  MANDATORY FIRST STEPS:
  The first two steps MUST always be:
  1. Setup Environment (install missing JDKs/build tools)
  2. Setup Baseline (establish pre-upgrade compile/test results)

  MANDATORY SETUP ENVIRONMENT STEP SAMPLE:

  - Step 1: Setup Environment
    - **Rationale**: Install required JDKs and build tools identified as missing in "Available Tools" section.
    - **Changes to Make**:
      - [ ] Install JDK 17 (required for Spring Boot 3.x compilation)
      - [ ] Install JDK 21 (target version for final validation)
      - [ ] Verify Maven Wrapper is executable
    - **Verification**:
      - Command: `#list_jdks` to confirm installations
      - Expected: All required JDKs available at specified paths

  ---

  MANDATORY SETUP BASELINE STEP SAMPLE:

  - Step 2: Setup Baseline
    - **Rationale**: Establish pre-upgrade compile and test results to measure upgrade success against.
    - **Changes to Make**:
      - [ ] Run baseline compilation with current JDK
      - [ ] Run baseline tests with current JDK
    - **Verification**:
      - Command: `mvn clean compile test-compile -q && mvn clean test -q` // run both compile and test
      - JDK: <current project JDK path>
      - Expected: Document SUCCESS/FAILURE, test pass rate (forms acceptance criteria)

  ---

  SAMPLE STEP (framework upgrade):

  - Step N: Upgrade to Spring Boot 3.2
    - **Rationale**: Core framework upgrade. Hibernate and other deps will auto-upgrade via Spring Boot BOM.
    - **Prerequisites**: <only if JDK 17 not available>
      - `#install_jdk version=17`
    - **Changes to Make**:
      - [ ] Update spring-boot-starter-parent to 3.2.x
      - [ ] Update Spring Framework to 6.1.x (if explicitly declared)
      - [ ] Run jakarta namespace migration (javax.* → jakarta.*)
      - [ ] Fix compilation errors
    - **Verification**:
      - Command: `mvn clean test-compile -q` // compile only
      - JDK: <JDK 17 path>
      - Expected: Compilation SUCCESS (tests may fail - will be fixed in Final Validation)

  ---

  MANDATORY FINAL STEP (must always be the last step):

  - Step N: Final Validation
    - **Rationale**: Verify all upgrade goals met, project compiles successfully, all tests pass (if tests enabled in Options).
    - **Prerequisites**: <only if target JDK not available>
      - `#install_jdk version=21` (if upgrading to Java 21)
    - **Changes to Make**:
      - [ ] Verify all target versions in pom.xml/build.gradle
      - [ ] Resolve ALL TODOs and temporary workarounds from previous steps
      - [ ] Clean rebuild with target JDK
      - [ ] Fix any remaining compilation errors
      - [ ] Run full test suite and fix ALL test failures (iterative fix loop until 100% pass) — **skip if "Run tests before and after the upgrade: false" in Options**
    - **Verification**:
      - Command: `mvn clean test -q` (if tests enabled) or `mvn clean test-compile -q` (if tests disabled)
      - JDK: <target JDK path>
      - Expected: Compilation SUCCESS + 100% tests pass (if tests enabled)
-->

## Key Challenges

<!--
  Document high-risk areas that require special attention during upgrade.
  Each challenge should have a mitigation strategy. Be concise.
  Common challenges:
  - Breaking API changes (javax→jakarta)
  - EOL library replacements
  - Complex multi-dependency coordination
  - Custom framework extensions that may break

  SAMPLE:
  - **Jakarta EE Namespace Migration**
     - **Challenge**: Entire codebase uses javax.* packages (servlet, persistence, validation, inject, mail) that must migrate to jakarta.* in Spring Boot 3+.
     - **Strategy**: Use OpenRewrite's automated migration recipes after reaching Spring Boot 2.7.x to handle bulk namespace changes. Spring Boot 2.7.x provides javax-to-jakarta bridge making it ideal intermediate target.
  - **Hibernate 4.3 to 6.x Major Version Jump**
     - **Challenge**: Breaking changes in Hibernate 6 including removed APIs, behavior changes, and updated query syntax.
     - **Strategy**: Upgrade incrementally: Hibernate 5.6.x with Spring Boot 2.7.x, validate, then Hibernate 6.x with Spring Boot 3.2.x. Update jackson-datatype-hibernate4 → hibernate6 module. Expect schema validation and query adjustments.
-->
