clean-architecture-backend-template/docs/superpowers/plans/2026-09-17-jpa-evidence-gradle-model-decoupling.md

JPA Evidence Gradle Model Decoupling Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Remove execution-time Gradle Project/Task/TaskState access from JPA evidence generation without changing evidence semantics.

Architecture: A shared JpaEvidenceExecutionService consumes Gradle task-completion events for non-Test task claims. The JPA evidence plugin snapshots/configures JUnit result directories, provenance, environment/profile values, and dependency versions as typed task inputs. GenerateJpaEvidenceManifestsTask becomes a pure evidence assembler over those inputs plus filesystem/exec services.

Tech Stack: Java 21, Gradle 9 BuildService + Tooling Events, JUnit 6/TestKit, Jackson 3.

Spec: docs/superpowers/specs/2026-09-17-jpa-evidence-gradle-model-decoupling-design.md

Global Constraints

• Preserve readiness-card schema and task names.
• Preserve JUnit XML as test evidence.
• Preserve task-claim meaning: only a successful producer task covers a task claim.
• Preserve evidence grade, blocker, hashing, prerequisite, output, candidate/R2 semantics.
• No execution-time Project, Task, or TaskState access in GenerateJpaEvidenceManifestsTask.
• Do not stage, commit, amend, reset, or push existing worktree changes.

---

Task 1: Task completion evidence service

Files:

• Create: src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/JpaEvidenceExecutionService.java
• Create: src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/JpaEvidenceTaskOutcome.java
• Test: src/build-tools/src/test/java/dev/caskeleton/buildtools/jpa/JpaEvidenceExecutionServiceTest.java

Interfaces:

• Produces: JpaEvidenceExecutionService.outcome(String taskPath) and completedSuccessfully(String taskPath).

• Consumes: Gradle TaskFinishEvent via OperationCompletionListener.

• Write tests for success, failure, skipped, and unknown task paths.

• Verify tests fail because the service/model do not exist.

• Implement the typed outcome model and thread-safe service.

• Verify focused tests pass.

Task 2: Typed JUnit evidence inputs

Files:

• Create: src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/JpaEvidenceTestResultLocator.java
• Modify: src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/JpaEvidenceTaskSupport.java
• Test: src/build-tools/src/test/java/dev/caskeleton/buildtools/jpa/JpaEvidenceTestResultLocatorTest.java

Interfaces:

• Consumes: Map<String, String> task-path to repository-relative/absolute JUnit XML directory.

• Produces: JpaGeneratedTestResult read(String taskPath) without Project or Test.

• Write a failing test that creates JUnit XML under a temporary directory and resolves it by task path.

• Implement file-based result lookup using JUnitEvidenceReader.

• Remove the readJUnitResult(Project, Test) helper once no caller remains.

• Verify focused tests pass.

Task 3: Generator typed input surface

Files:

• Modify: src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/GenerateJpaEvidenceManifestsTask.java
• Test: extend src/build-tools/src/test/java/dev/caskeleton/buildtools/jpa/JpaEvidencePluginTypeTest.java

Interfaces:

• Add typed properties for profile/CI/artifact/topology/provenance/dependency versions/JUnit result directories.

• Add an internal/service reference to JpaEvidenceExecutionService.

• Add reflection/type tests asserting the new task properties exist and no generator source contains getProject() or Task.getState() usage.

• Verify the test fails against the current generator.

• Add the typed properties and service reference.

• Replace Project/Task/TaskState/configuration/extra-property reads with typed inputs/service lookups.

• Verify focused tests pass.

Task 4: Plugin wiring

Files:

• Modify: src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/JpaEvidencePlugin.java
• Modify: src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/JpaEvidenceTaskSupport.java
• Test: add src/build-tools/src/test/java/dev/caskeleton/buildtools/jpa/JpaEvidencePluginFunctionalTest.java

Interfaces:

• Register shared execution service and task-completion listener.

• Configure generator typed inputs.

• Configure JUnit result-directory mapping for active readiness/support Test tasks.

• Preserve existing dependsOn producer graph.

• Write TestKit fixture asserting typed generator inputs and task wiring.

• Verify RED.

• Register/wire the service and all generator properties.

• Resolve dependency versions and release provenance during configuration/plugin wiring rather than task action.

• Verify TestKit GREEN.

Task 5: Regression and Gradle 10-preparation verification

Files:

• Modify only if verification exposes a regression.

• Run src/build-tools full check --warning-mode=fail.

• Run root verifyJpaReadinessRegistry verifyJpaReleaseGateTasks --warning-mode=fail.

• Run :adapter:outbound:persistence-jpa:check --warning-mode=fail.

• Run candidate evidence generation with --warning-mode=all; verify there is no Task.project/execution-time project deprecation from JPA evidence tooling.

• Run adapter procedural-Groovy scan and confirm no regression.

• Run git diff --check.

• Record any environment-only Docker/Testcontainers limitation separately from code correctness.