Add detailed comments and logging for compile-only cache saving

- Document why attached resource bookkeeping reset is needed
- Explain that outputs are attached for ALL lifecycle phases
- Add debug logging when saving compile-only cache entries
- Address reviewer feedback from PR apache#176 about pre-compile phase support

Author: claude

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

@@ -498,6 +498,9 @@ public void save(
         final MavenProject project = context.getProject();
         final MavenSession session = context.getSession();
         try {
+            // Reset attached resource bookkeeping to ensure clean state per save invocation.
+            // This prevents stale artifacts from previous builds within the same session
+            // from polluting the current cache entry (critical for multi-module builds).
             attachedResourcesPathsById.clear();
             attachedResourceCounter = 0;
 
@@ -506,9 +509,20 @@ public void save(
             final org.apache.maven.artifact.Artifact projectArtifact = project.getArtifact();
             final boolean hasPackagePhase = project.hasLifecyclePhase("package");
 
+            // Attach configured outputs for ALL lifecycle phases (including compile-only builds).
+            // This ensures compile-only cache entries contain necessary outputs (e.g., classes, module-info)
+            // for subsequent builds that restore from cache and continue with later phases.
+            // Addresses issues #393, #259, #340 where JPMS modules failed after compile-only cache hits.
             attachGeneratedSources(project);
             attachOutputs(project);
 
+            if (!hasPackagePhase && LOGGER.isDebugEnabled()) {
+                LOGGER.debug(
+                        "Saving cache entry for compile-only build (no package phase) for project {}. "
+                                + "Attached outputs will be available for restoration in subsequent builds.",
+                        project.getArtifactId());
+            }
+
             final List<org.apache.maven.artifact.Artifact> attachedArtifacts = project.getAttachedArtifacts() != null
                     ? project.getAttachedArtifacts()
                     : Collections.emptyList();