S8 integrate pinned Palantir formatting through OpenRewrite

README.md

@@ -253,3 +253,58 @@ Only successful `main` runs publish images to the Synology registry. See
 [the CI management guide](docs/gitea-ci.md) for runner setup, registry secrets,
 image names, diagnostics and recovery, and [validation evidence](docs/s4-validation.md)
 for the current operational status.
+
+### Java formatting (S8)
+
+Maven is the authoritative formatting path. The root build runs the actual
+Palantir Java Format **2.101.0**, Palantir style, through a custom OpenRewrite
+**8.63.4** text recipe in `tooling/format/Format.java`. The pinned
+`exec-maven-plugin` **3.6.3** launches that helper with JDK 25. Native import
+ordering and unused-import removal are enabled; extra Javadoc formatting is off.
+No OpenRewrite AutoFormat or additional refactoring recipes run.
+
+From the repository root:
+
+```sh
+mvn -N exec:exec@format                       # apply, without application compilation
+mvn -N exec:exec@format -Dformat.mode=check   # check, without application compilation
+mvn compile                                 # applies during validate, before compilation
+mvn -Dformat.mode=check clean verify         # CI: fails before compilation on differences
+```
+
+Root `compile`, `test`, `verify` and `install` may rewrite maintained Java files
+in the validate phase. CI's Java orchestration passes `-Dformat.mode=check` and
+never repairs source files. On failure, the output lists paths and the apply
+command. Apply locally, inspect and commit the result, then repeat the check.
+Run root Maven commands; selecting only the backend with `-pl agiledancers-be`
+bypasses the root formatting execution.
+
+The scope is every `.java` file recursively under `agiledancers-be/src/main/java`,
+`agiledancers-be/src/test/java`, `ci` (including the runner helper), and the
+formatter helper itself. Generated `target` files and frontend files are excluded.
+The adapter keeps paths and UTF-8 content, computes changes before writing, and
+uses atomic per-file replacements. Unsupported syntax fails with its path/cause.
+The source launcher compiles the adapter directly in memory from a clean checkout;
+no custom recipe jar needs compiling or installing beforehand. Maven downloads
+only pinned external tooling dependencies on first use.
+
+Successfully checked/formatted content hashes are cached in
+`target/palantir-cache.properties`; new or changed files are always processed.
+The root POM, adapter source, dependency classpath and JDK version invalidate the cache. `clean` removes
+it. Check and apply share the engine, options, scope and successful-content cache;
+a failing check does not write sources or update the cache. For controlled timing
+comparisons only, `-Dformat.skip=true` disables the execution.
+
+Editors are optional. Palantir supplies an IntelliJ plugin (see the
+[upstream instructions](https://github.com/palantir/palantir-java-format#intellij-plugin)).
+Use it only with the same engine version/style and Javadoc setting; if the editor
+cannot match them, use Maven to format instead. Editor import optimization or
+format-on-save must not override Maven's result. Other editors can invoke the
+standalone Maven apply command as an external tool.
+
+Verification and measurements are recorded in
+[the S8 evidence](specs/S8-formatting-evidence.md). Reproduce the isolated failure,
+UTF-8, import, cache and idempotence checks with
+`python3 tooling/format/test.py`, and the sequential end-to-end build measurements
+with `python3 tooling/format/benchmark.py` (requires the ordinary backend test
+prerequisites). Results are written under `target/`.