1# Phase 3: Execute Upgrade Plan
2 
3Load this file when executing Phase 3. Refer back to [`upgrade-success-criteria`](../rules/upgrade-success-criteria.md) and [`upgrade-strategy`](../rules/upgrade-strategy.md) for success criteria and strategy, and [`../rules/troubleshooting.md`](../rules/troubleshooting.md) when failures occur.
4 
5## 1. Initialize
6 
71. Read `plan.md` for step details
82. Update `progress.md`:
9   - Replace `<RUN_ID>`, `<PROJECT_NAME>` and timestamp placeholders
10   - Create step entries for each step in `plan.md` (per **Template compliance** rule)
11 
12## 2. Execute
13 
14For each step:
15 
161. Read `plan.md` for step details and guidelines
172. Mark ⏳ in `progress.md`
183. Make changes as planned (use OpenRewrite if helpful, verify results)
19   - Add TODOs for any deferred work, e.g., temporary workarounds
204. **Review Code Changes** (per rules in Progress Template): Verify sufficiency (all required changes present) and necessity (no unnecessary changes, functional behavior preserved, security controls maintained).
21   - Add missing changes and revert unnecessary changes. Document any unavoidable behavior changes with justification.
225. Verify with specified command/JDK:
23   - **Steps 1-N (Setup/Upgrade)**: Compilation must pass (including both main and test code, fix immediately if not). Test failures acceptable — document count.
24   - **Final Validation Step**: Achieve **Upgrade Success Criteria** — iterative test & fix loop until 100% pass (or ≥ baseline). NO deferring. See [`../rules/troubleshooting.md`](../rules/troubleshooting.md) when stuck.
25   - Build: `mvn clean test-compile` (or `./gradlew compileTestJava` for Gradle)
26   - Test: `mvn clean test` (or `./gradlew test` for Gradle)
276. Commit on the `java-upgrade/{RUN_ID}` branch with message format (if git available; otherwise, log details in `progress.md`):
28   - First line: `Step <x>: <title> - Compile: <result>` or `Step <x>: <title> - Compile: <result>, Tests: <pass>/<total> passed` (if tests run)
29   - Body: Changes summary + concise known issues/limitations (≤5 lines)
30   - **Security note**: If any security-related changes were made, include "Security: <change description and justification>"
317. Update `progress.md` with step details and mark ✅ or ❗
32 
33## 3. Complete
34 
351. Validate all steps in `plan.md` have ✅ in `progress.md`
362. Validate all **Upgrade Success Criteria** are met, or otherwise go back to Final Validation step to fix
37