cisd/docs/plans/2026-02-28-jdk21-mockito-ci-stability-plan.md

JDK17 + Mockito + CI Stability Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Stabilize local/CI test execution by fixing Mockito agent startup behavior and pinning CI to JDK 17.

Architecture: Configure Maven Surefire to preload Mockito as a javaagent and set required JVM flags to avoid runtime self-attach failures. Add a CI workflow that always uses JDK 17 and runs compile/test checks. Update README for explicit developer/CI runtime expectations.

Tech Stack: Maven Surefire, Mockito, GitHub Actions, JDK 17, Spring Boot 3.5

---

Task 1: Build/Test runtime hardening

Files:

• Modify: pom.xml

1. Add explicit mockito.version property.
2. Add maven-surefire-plugin with argLine including:
   • -Djdk.attach.allowAttachSelf=true
   • -XX:+EnableDynamicAgentLoading
   • -javaagent:${settings.localRepository}/org/mockito/mockito-core/${mockito.version}/mockito-core-${mockito.version}.jar

Task 2: CI JDK pinning

Files:

• Create: .github/workflows/ci.yml

1. Add workflow on push + pull_request.
2. Use actions/setup-java with Temurin 17.
3. Run mvn -q -DskipTests compile then mvn -q test.

Task 3: Documentation sync

Files:

• Modify: README.md

1. Add explicit local recommended JDK 17 note.
2. Add CI note: workflow runs JDK 17 and compile+test.
3. Add troubleshooting note for Mockito agent behavior on newer JDKs.

Task 4: Verification

Commands:

1. mvn -q -DskipTests compile
2. mvn -q test (sandbox)
3. mvn -q test (escalated fallback if sandbox attach restrictions block)
4. Key checks with rg for workflow and surefire config.