docs: streamline CLAUDE.md for clarity and conciseness

CLAUDE.md

@@ -2,188 +2,141 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-This document outlines essential practices for working with Claude Code on the Apache Struts project. For detailed
-procedures, use the specialized agents and commands available in `.claude/agents/` and `.claude/commands/`.
+For detailed procedures, use the specialized agents and commands in `.claude/agents/` and `.claude/commands/`.
 
 ## Project Overview
 
-Apache Struts is a mature MVC web application framework for Java, originally based on WebWork 2. The project follows a
-modular architecture with clear separation between core framework, plugins, and applications.
+Apache Struts is a mature MVC web application framework for Java (originally WebWork 2). Current version: *
+*7.2.0-SNAPSHOT**.
 
-### Build System & Environment
-
-- **Build Tool**: Maven with multi-module structure
-- **Java Version**: Java 17+
-- **Testing**: JUnit 5 with AssertJ assertions
-- **IDE Support**: IntelliJ IDEA with project-specific configurations
-
-### Key Build Commands
+### Build Commands
 
 ```bash
 # Full build with tests
 mvn clean install
 
-# Run tests
+# Run all tests (faster, skips assembly)
 mvn test -DskipAssembly
 
-# Build without running tests
+# Run single test class
+mvn test -DskipAssembly -Dtest=MyClassTest
+
+# Run single test method
+mvn test -DskipAssembly -Dtest=MyClassTest#testMethodName
+
+# Run tests in a specific module
+mvn test -DskipAssembly -pl core
+
+# Build without tests
 mvn clean install -DskipTests
+
+# Build with code coverage (JaCoCo)
+mvn clean install -Pcoverage
+
+# Build with Jakarta EE 11 (Spring 7)
+mvn clean install -Pjakartaee11
+
+# Run OWASP dependency vulnerability check
+mvn verify -Pdependency-check
 ```
 
 ### Project Structure
 
 ```
 struts/
-├── core/           # Core framework (struts2-core)
-├── plugins/        # Plugin modules (tiles, json, etc.)
-├── apps/          # Sample applications (showcase, rest-showcase)
-├── assembly/      # Distribution packaging
-├── bom/           # Bill of Materials for dependency management
-├── parent/        # Parent POM with shared configuration
-└── jakarta/       # Jakarta EE compatibility modules
+├── core/           # struts2-core - main framework
+├── plugins/        # Plugin modules (json, rest, spring, tiles, velocity, etc.)
+├── apps/           # Sample applications (showcase, rest-showcase)
+├── assembly/       # Distribution packaging
+├── bom/            # Bill of Materials for dependency management
+├── parent/         # Parent POM with shared configuration
+└── jakarta/        # Jakarta EE compatibility modules
 ```
 
-### Core Architecture Components
-
-#### MVC Framework Components
+### Core Architecture
 
-- **ActionSupport**: Base class for actions with validation and internationalization
-- **ActionContext**: Thread-local context holding request/response data
-- **ActionProxy/ActionInvocation**: Handles action execution lifecycle
-- **Dispatcher**: Core request dispatcher and framework initialization
-- **Interceptors**: Cross-cutting concerns (validation, file upload, security)
+**Request Lifecycle**: `Dispatcher` → `ActionProxy` → `ActionInvocation` → Interceptor stack → `Action` → Result
 
-#### Key Packages
+Key components:
 
-- `org.apache.struts2.dispatcher`: Request handling and context management
-- `org.apache.struts2.interceptor`: Interceptor implementations
-- `org.apache.struts2.components`: UI component system
-- `org.apache.struts2.views`: View technologies (JSP, FreeMarker, Velocity)
-- `org.apache.struts2.security`: Security-related utilities
+- **ActionSupport**: Base class for actions (validation, i18n, messages)
+- **ActionContext**: Thread-local context with request/response/session data
+- **Interceptors**: Cross-cutting concerns (validation, file upload, security, params)
+- **Results**: Response handlers (dispatcher, redirect, json, stream)
 
-### Technology Stack
+Key packages in `org.apache.struts2`:
 
-- **Jakarta EE**: Servlet API, JSP, JSTL
-- **Core Libraries**: OGNL (expression language), Commons FileUpload2, Log4j2
-- **Template Engines**: FreeMarker, Velocity (via plugins)
-- **Build Dependencies**: Maven, various plugins for assembly and site generation
+- `dispatcher` - Request handling, `Dispatcher`, servlet integration
+- `interceptor` - Built-in interceptors (params, validation, fileUpload)
+- `components` - UI tag components (form, textfield, submit)
+- `action` - Action interfaces (`UploadedFilesAware`, `SessionAware`, etc.)
+- `security` - Security utilities and OGNL member access policies
 
-## Security-First Development
+### Technology Stack
 
-### Critical Security Principles
+- **Java 17+** with Jakarta EE 10 (Servlet 6.0, JSP 3.1)
+- **OGNL** - Expression language for value stack access
+- **FreeMarker** - Default template engine for UI tags
+- **Commons FileUpload2** - File upload handling
+- **Log4j2/SLF4J** - Logging
 
-1. **Never create files in system temp directories** - always use controlled application directories
-2. **Use UUID-based naming** for temporary files to prevent collisions and path traversal
-3. **Implement proper resource cleanup** with try-with-resources and finally blocks
-4. **Track all temporary resources** for explicit cleanup (security critical)
-5. **Validate all user inputs** and sanitize filenames before processing
+## Security-Critical Patterns
 
-**For comprehensive security analysis, use:** `/security_scan`
+Apache Struts has a history of security vulnerabilities. Follow these strictly:
 
-### Security Implementation Patterns
+1. **Temporary files**: Never use system temp directory; use UUID-based names in controlled locations
+2. **OGNL expressions**: Never evaluate user-controlled OGNL; use allowlist member access
+3. **File uploads**: Validate content types, sanitize filenames, enforce size limits
+4. **Parameter injection**: Use `ParameterNameAware` to filter dangerous parameter names
 
 ```java
-// GOOD: Secure temporary file creation
+// Secure temporary file pattern
 protected File createTemporaryFile(String fileName, Path location) {
     String uid = UUID.randomUUID().toString().replace("-", "_");
-    File file = location.resolve("upload_" + uid + ".tmp").toFile();
-    LOG.debug("Creating temporary file: {} (originally: {})", file.getName(), fileName);
-    return file;
+    return location.resolve("upload_" + uid + ".tmp").toFile();
 }
 ```
 
-## Testing Implementation
-
-### Intelligent Test Execution Approach
-
-When running tests, use this priority order:
+Run `/security_scan` for comprehensive security analysis.
 
-1. **JetBrains MCP** (when available in IntelliJ IDEA):
-   - Use `mcp__jetbrains__execute_run_configuration` for specific test configurations
-   - First check if configuration exists with `get_run_configurations`
+## Testing
 
-2. **test-runner agent** (primary method):
-   - Use Task tool with `subagent_type="test-runner"` for comprehensive test execution
-   - Provides intelligent test analysis and coverage reports
+**Priority order for running tests:**
 
-3. **Direct Maven** (fallback):
-   - Use only when explicitly requested or for simple verification
-   - Command: `mvn test -DskipAssembly`
+1. **JetBrains MCP** (in IntelliJ): `mcp__jetbrains__execute_run_configuration`
+2. **test-runner agent**: `Task` tool with `subagent_type="test-runner"`
+3. **Direct Maven**: `mvn test -DskipAssembly -Dtest=TestClassName`
 
-### Test Structure & Coverage
+Tests use JUnit 5 with AssertJ assertions and Mockito for mocking.
 
-- **Unit Tests**: Test individual methods with mocked dependencies
-- **Integration Tests**: Test complete workflows with real file I/O
-- **Security Tests**: Verify directory traversal prevention, secure naming
-- **Error Handling Tests**: Test exception scenarios and error reporting
-- **Cleanup Tests**: Verify resource cleanup and tracking
+## Available Tools
 
-## Documentation Standards
-
-**For comprehensive documentation quality analysis, use:** `/quality_check`
-
-### Documentation Requirements
-
-- **Always document security implications** in methods handling files/user input
-- **Include usage examples** for complex methods and classes
-- **Document exception conditions** and error handling behavior
-- **Reference related methods** using `@see` tags
-- **Explain resource management** responsibilities
-
-## Error Handling & Logging
-
-### Logging Best Practices
-
-- Use parameterized logging for performance: `LOG.debug("Processing: {}", value)`
-- Log security-relevant operations appropriately
-- Use appropriate log levels (debug/info/warn/error)
-- Avoid logging sensitive information
-
-## Code Quality Standards
-
-**For comprehensive code quality analysis, use:** `/quality_check`
+### Commands
 
-### Key Principles
+- `/security_scan` - OGNL injection, CVE detection, security analysis
+- `/quality_check` - JavaDoc compliance, coding standards
+- `/config_analyze` - struts.xml validation, interceptor analysis
+- `/create_plan` / `/validate_plan` - Implementation planning
+- `/research_codebase` - Codebase exploration
 
-- Use `protected` for methods that subclasses might override
-- Catch specific exceptions rather than generic `Exception`
-- Use clear, descriptive method and variable names
-- Follow existing project conventions and patterns
+### Specialized Agents
 
-## Available Automated Tools
+- `test-runner` - Maven test execution (use this to RUN tests)
+- `security-analyzer` - Security vulnerability scanning
+- `codebase-locator` - Find files, classes, implementations
+- `codebase-pattern-finder` - Find similar code patterns
+- `config-validator` - Validate Struts configuration files
 
-### Commands
+## Pull Requests
 
-- `/security_scan` - Comprehensive security analysis
-- `/quality_check` - Code quality and documentation analysis
-- `/config_analyze` - Configuration validation and optimization
-- `/create_plan` - Implementation planning assistance
-- `/validate_plan` - Plan validation and verification
-- `/commit` - Guided git commit creation
-- `/research_codebase` - Comprehensive codebase research
+- **Title format**: `WW-XXXX Description` (Jira ticket ID required)
+- **Link ticket in description**: `Fixes [WW-XXXX](https://issues.apache.org/jira/browse/WW-XXXX)`
+- **Issue tracker**: https://issues.apache.org/jira/projects/WW
 
-### Specialized Agents
+## Common Pitfalls
 
-- `security-analyzer` - OGNL injection scanning, CVE detection
-- `test-runner` - Maven test execution and coverage analysis, use this agent to RUN the tests
-- `code-quality-checker` - JavaDoc compliance, pattern consistency
-- `config-validator` - struts.xml validation, interceptor analysis
-- `codebase-analyzer` - Project structure and architecture analysis
-- `codebase-locator` - Code and file location assistance
-- `codebase-pattern-finder` - Pattern examples and usage
-
-## Pull Request Guidelines
-
-- **PR title must start with Jira ticket ID** (e.g., `WW-5588 Allow Preparable interface...`)
-- **PR description must link to the ticket** using GitHub keywords:
-    - `Closes [WW-XXXX](https://issues.apache.org/jira/browse/WW-XXXX)`
-    - `Fixes [WW-XXXX](https://issues.apache.org/jira/browse/WW-XXXX)`
-
-## Common Pitfalls to Avoid
-
-1. **File Security**: Never use `File.createTempFile()` without directory control
-2. **Resource Leaks**: Always track and clean up temporary files
-3. **Test Coverage**: Don't forget to test error conditions and cleanup
-4. **Documentation**: Always document security implications
-5. **Exception Handling**: Don't let cleanup failures affect main operations
-6. **Path Validation**: Always validate and sanitize file paths
+1. Never use `File.createTempFile()` without controlling the directory
+2. Always clean up temporary files (track and delete in finally blocks)
+3. Test error paths and cleanup behavior, not just happy paths
+4. Don't catch generic `Exception` - catch specific types
+5. Use `protected` visibility for methods subclasses may override