Fix integration test failures and implement staleness detection

This commit fixes test failures and implements staleness detection via
staging directory to prevent caching artifacts with future timestamps
due to clock skew or orphaned files from git branch switches.

Root Causes Fixed:
1. Issue74Test/DuplicateGoalsTest: hasUsefulArtifacts logic too aggressive
2. Compile-only builds: NullPointerException during artifact restoration
3. Clock skew vulnerability: Future timestamps cause wrong cache entries

Staleness Detection Solution - Staging Directory:
Instead of timestamp checking (which fails with clock skew), physically
separate stale artifacts by moving them to a staging directory.

Before mojos run: Move pre-existing artifacts to staging directory
- Maven sees clean target/ with no pre-existing artifacts
- Maven compiler MUST compile (can't skip based on timestamps)
- Fresh correct files created in target/
- save() only sees fresh files (stale ones in staging)
After save(): Restore artifacts from staging atomically (prevents TOCTOU race)

Scenarios Protected:
1. Future Timestamps from Clock Skew - Moved to staging, forcing recompilation
2. Orphaned Class Files (deleted sources) - Moved to staging, not cached
3. Stale JARs/WARs from previous builds - Moved to staging, fresh ones cached

Multimodule Support:
- Staging directory structure preserves paths relative to multimodule root
- Directory: target/maven-build-cache-extension/{module-path}/target/classes
- Fixed state lifecycle bug where save() was removing ProjectCacheState
  before restoreRenamedArtifacts() could restore files
- Updated method signatures to accept MavenSession for multimodule root resolution

Changes:
- CacheControllerImpl: Staging directory infrastructure with atomic restore
- BuildCacheMojosExecutionStrategy: Integrated move before mojos, restore after save
- hasUsefulArtifacts: Allow POM projects with plugin executions
- artifactDto: Always set filePath for directories
- restoreRenamedArtifacts: Use atomic Files.move() to prevent race conditions
- Added: GitCheckoutStaleArtifactTest for single-module validation
- Added: GitCheckoutStaleMultimoduleTest for multimodule validation

All 74 unit tests pass.

Author: cowwoc

.gitignore

@@ -15,3 +15,4 @@ out/
 .java-version
 .checkstyle
 .factorypath
+null/

src/main/java/org/apache/maven/buildcache/BuildCacheMojosExecutionStrategy.java

@@ -23,6 +23,7 @@
 import javax.inject.Named;
 
 import java.io.File;
+import java.io.IOException;
 import java.nio.file.Path;
 import java.util.HashSet;
 import java.util.List;
@@ -138,33 +139,54 @@ public void execute(
 
             boolean restorable = result.isSuccess() || result.isPartialSuccess();
             boolean restored = false; // if partially restored need to save increment
+
             if (restorable) {
                 CacheRestorationStatus cacheRestorationStatus =
                         restoreProject(result, mojoExecutions, mojoExecutionRunner, cacheConfig);
                 restored = CacheRestorationStatus.SUCCESS == cacheRestorationStatus;
                 executeExtraCleanPhaseIfNeeded(cacheRestorationStatus, cleanPhase, mojoExecutionRunner);
             }
-            if (!restored) {
-                for (MojoExecution mojoExecution : mojoExecutions) {
-                    if (source == Source.CLI
-                            || mojoExecution.getLifecyclePhase() == null
-                            || lifecyclePhasesHelper.isLaterPhaseThanClean(mojoExecution.getLifecyclePhase())) {
-                        mojoExecutionRunner.run(mojoExecution);
+
+            try {
+                if (!restored) {
+                    // Move pre-existing artifacts to staging directory to prevent caching stale files
+                    // from previous builds (e.g., after git branch switch, or from cache restored
+                    // with clock skew). This ensures save() only sees fresh files built during this session.
+                    try {
+                        cacheController.stagePreExistingArtifacts(session, project);
+                    } catch (IOException e) {
+                        LOGGER.warn("Failed to stage pre-existing artifacts: {}", e.getMessage());
+                        // Continue build - if staging fails, we'll just cache what exists
+                    }
+
+                    for (MojoExecution mojoExecution : mojoExecutions) {
+                        if (source == Source.CLI
+                                || mojoExecution.getLifecyclePhase() == null
+                                || lifecyclePhasesHelper.isLaterPhaseThanClean(mojoExecution.getLifecyclePhase())) {
+                            mojoExecutionRunner.run(mojoExecution);
+                        }
                     }
                 }
-            }
 
-            if (cacheState == INITIALIZED && (!result.isSuccess() || !restored)) {
-                if (cacheConfig.isSkipSave()) {
-                    LOGGER.info("Cache saving is disabled.");
-                } else if (cacheConfig.isMandatoryClean()
-                        && lifecyclePhasesHelper
-                                .getCleanSegment(project, mojoExecutions)
-                                .isEmpty()) {
-                    LOGGER.info("Cache storing is skipped since there was no \"clean\" phase.");
-                } else {
-                    final Map<String, MojoExecutionEvent> executionEvents = mojoListener.getProjectExecutions(project);
-                    cacheController.save(result, mojoExecutions, executionEvents);
+                if (cacheState == INITIALIZED && (!result.isSuccess() || !restored)) {
+                    if (cacheConfig.isSkipSave()) {
+                        LOGGER.info("Cache saving is disabled.");
+                    } else if (cacheConfig.isMandatoryClean()
+                            && lifecyclePhasesHelper
+                                    .getCleanSegment(project, mojoExecutions)
+                                    .isEmpty()) {
+                        LOGGER.info("Cache storing is skipped since there was no \"clean\" phase.");
+                    } else {
+                        final Map<String, MojoExecutionEvent> executionEvents =
+                                mojoListener.getProjectExecutions(project);
+                        cacheController.save(result, mojoExecutions, executionEvents);
+                    }
+                }
+            } finally {
+                // Always restore staged files after build completes (whether save ran or not).
+                // Files that were rebuilt are discarded; files that weren't rebuilt are restored.
+                if (!restored) {
+                    cacheController.restoreStagedArtifacts(session, project);
                 }
             }
 
@@ -244,6 +266,7 @@ private CacheRestorationStatus restoreProject(
 
         // Restore project artifacts
         ArtifactRestorationReport restorationReport = cacheController.restoreProjectArtifacts(cacheResult);
+
         if (!restorationReport.isSuccess()) {
             LOGGER.info("Cannot restore project artifacts, continuing with non cached build");
             return restorationReport.isRestoredFilesInProjectDirectory()

src/main/java/org/apache/maven/buildcache/CacheController.java

@@ -18,6 +18,7 @@
  */
 package org.apache.maven.buildcache;
 
+import java.io.IOException;
 import java.util.List;
 import java.util.Map;
 
@@ -45,4 +46,23 @@ void save(
     boolean isForcedExecution(MavenProject project, MojoExecution execution);
 
     void saveCacheReport(MavenSession session);
+
+    /**
+     * Move pre-existing artifacts to staging directory to prevent caching stale files.
+     * Called before mojos run to ensure save() only sees fresh files.
+     *
+     * @param session the Maven session
+     * @param project the Maven project
+     * @throws IOException if file operations fail
+     */
+    void stagePreExistingArtifacts(MavenSession session, MavenProject project) throws IOException;
+
+    /**
+     * Restore staged artifacts after save() completes.
+     * Files that were rebuilt are discarded; files that weren't rebuilt are restored.
+     *
+     * @param session the Maven session
+     * @param project the Maven project
+     */
+    void restoreStagedArtifacts(MavenSession session, MavenProject project);
 }