Workflow: Java toolchain setup script + one preflight command for Java-conversion PRs #3654

Observations.

1. The local Java toolchain for java_target_matrix.py lives in session scratch: a portable Temurin 21 (the system java-21 package is a JRE, no javac) and Gradle 8.10.2. Every new session re-downloads it. Maven also needs JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64, or it fails with "release version 17 not supported".
2. PR LINK / XCTL / CALL -> service-to-service calls; CSD decks are not program declarers (#3616) #3640 reached CI with 5 mypy findings because I ran ruff_audit.py locally but not mypy_audit.py. A Java-conversion PR has about 7 gates, and I ran them by hand from memory.

Ask.

• scripts/setup_java_toolchain.sh: installs JDK 17 + 21 and Gradle into a stable, gitignored location (.tools/) and prints the JDK_17 / JDK_21 / JAVA_HOME / PATH exports.
• tests/tools/preflight.py [--java]: runs, in order,
  • ruff format --check on changed files;
  • ruff_audit.py --ci, mypy_audit.py --ci, dead_key_audit;
  • field_testing.py check;
  • refraction_snapshot.py check;
  • with --java, java_target_matrix.py --scan on CardDemo (default, plain-records, gradle-plain-21) plus one CICS corpus.
    It prints one PASS/FAIL table. Then reference it from the modernization skill's "Done means".

Part of #3625.

🤖 Generated with Claude Code