docs: document -Ppre-commit as auto-fixing, not a pass/fail check

CLAUDE.md

@@ -17,7 +17,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # Run a single test method
 ./mvnw test -Dtest=ClassName#methodName
 
-# Pre-commit checks
+# Pre-commit auto-fix: license headers + every configured OpenRewrite recipe
+# (modernization, not just formatting) - review every resulting diff and commit it
 ./mvnw -Ppre-commit clean verify -DskipTests
 ```
 

doc/ai-rules.md

@@ -52,7 +52,8 @@ These rules govern ALL development activities:
 ### Validation Requirements
 Before any code implementation:
 1. **Standards Compliance Check**: Verify output matches CUI standards
-2. **Build Verification**: Ensure generated code compiles and passes pre-commit checks
+2. **Build Verification**: Ensure generated code compiles, then run the pre-commit profile and
+   commit the fixes it applies (it rewrites files; it is not a pass/fail check)
 3. **Security Review**: Check for security anti-patterns and vulnerabilities
 4. **Documentation Sync**: Verify documentation reflects any code changes
 5. **Test Coverage**: Ensure adequate test coverage for new functionality
@@ -69,7 +70,12 @@ Before any code implementation:
 ### Pre-Commit Checklist
 Execute in sequence before ANY commit:
 
-1. **Quality Verification**: `./mvnw -Ppre-commit clean verify`
+1. **Quality Auto-Fix**: `./mvnw -Ppre-commit clean verify`
+    - This REWRITES your files in place: `license:format` updates license headers and
+      `rewrite:run` applies every configured OpenRewrite recipe -- which includes
+      modernization, not only formatting, so a recipe can make semantic source changes.
+      Review every resulting diff and commit it. A run that repaired the tree and a run
+      that changed nothing both exit 0, so check `git status` afterwards.
     - Fix ALL errors and warnings (mandatory)
     - Some recipes may add markers: Either fix them, or suppress them with proper justification. Never commit the markers.
     - Address code quality, formatting, and linting issues
@@ -316,6 +322,7 @@ Common Maven commands for CUI projects:
 
 ### Integration with Development Workflows
 - **CI/CD Awareness**: Understand and respect automated build and deployment processes
-- **Quality Gate Integration**: Ensure all outputs pass automated quality checks
+- **Quality Gate Integration**: Run the automated quality tooling and commit the fixes it
+  applies; the pre-commit profile rewrites files rather than only reporting
 - **Collaborative Development**: Optimize for effective human-AI pair programming
 - **Knowledge Contribution**: Help maintain and improve team knowledge base and documentation