# v0.3.0 Gradle / Spring Build Guidance

## Goal

Tighten the Java/Spring backend build guidance after the template-fill/history smoke exposed a local build-line workaround.

This is guidance only. It is not a build enforcement gate, AST/linter rule, or generated app product-quality certification.

## Evidence

The clean template-fill/history smoke generated a buildable Equipment Rental API, but it needed build-file repair:

- local JDK was Java 21 while the generated Gradle toolchain initially targeted Java 17;
- Gradle test initially missed the JUnit Platform launcher;
- `bootJar` failed under the generated Gradle 9.4.0 / Spring Boot 3.3.2 combination;
- OpenCode disabled `bootJar` so `gradle build` could pass.

The run still passed `gradle test`, `gradle build`, and HTTP smoke after repair, but disabling `bootJar` is not the desired default for a Spring Boot application.

The later plan-acceptance implementation smoke repeated the same pattern:

- OpenCode read the plan, revised it, accepted it, and implemented a buildable Pet Clinic Appointment API;
- `gradle test`, `gradle build`, and HTTP smoke passed;
- `bootJar` failed with `CopyProcessingSpec.getDirMode()` under Gradle 9.4.0 / Spring Boot 3.3.2;
- OpenCode again added `tasks.named('bootJar') { enabled = false }`.

That repeat means a generic caution was too weak. The guidance now treats `bootJar` disabling as the wrong default for executable Spring Boot apps and names the compatibility failure signature directly.

## Decision

For Java/Spring backend generation, the build guidance should say:

- choose a mutually compatible Spring Boot plugin, Gradle wrapper/launcher, and Java toolchain line;
- pin the Java toolchain instead of relying on the ambient JDK;
- do not mix a very new Gradle launcher with an older Spring Boot plugin and then disable `bootJar` as the default fix;
- do not add `tasks.named("bootJar") { enabled = false }` unless the project is explicitly a plain Java library;
- if `bootJar` fails with `CopyProcessingSpec.getDirMode()` or a similar plugin API mismatch, fix the Spring Boot plugin / Gradle launcher line instead of disabling the task;
- with a Gradle 9.x launcher, do not default to older Spring Boot 3.3.x plugin lines unless a wrapper pins a supported Gradle line;
- include the JUnit Platform launcher when the selected Gradle/JUnit setup needs it;
- for executable Spring Boot applications, keep `gradle test`, `gradle build`, and a basic `gradle bootRun` smoke viable.

## Applied Surface

Updated:

- `.persona/rules/backend/gradle-bootstrap.md`
- `packages/shared-skills/skills/programming/references/java/README.md`
- `packages/shared-skills/skills/programming/references/java/backend.md`
- `packages/shared-skills/skills/programming/references/java/technology-seams.md`

## Non-Goals

- no generated build-file fixer;
- no Gradle plugin compatibility checker;
- no public npm publish;
- no frontend/infra expansion;
- no AST/linter/enforcement gate;
- no generated app product-quality guarantee.

## Verification

Repo checks:

```bash
npm test
npm run typecheck
npm run build
npm run report:rules
npm run check:scope:strict
npm run check:injection-value
npm pack --dry-run
```

The targeted test asserts that Gradle bootstrap injection now includes:

- compatible Spring Boot/Gradle/JDK guidance;
- `bootJar` caution;
- explicit `enabled = false` caution;
- `CopyProcessingSpec.getDirMode()` compatibility-failure guidance;
- `junit-platform-launcher` guidance.

Clean smoke evidence:

- `docs/evidence-reviews/v0.3.0-gradle-spring-buildline-smoke.md`
- `docs/evidence-reviews/v0.3.0-bootjar-guidance-fresh-on-review.md`

Observed in the clean Clinic Notice API run:

- OpenCode read the workflow plan and Gradle/Spring guidance before implementation;
- plan status became `accepted`;
- generated build used Spring Boot `3.5.0`, Java 21 toolchain, and local Gradle `9.4.0`;
- `tasks.named("bootJar") { enabled = false }` was not generated;
- `gradle test` passed;
- `gradle build` passed with `:bootJar`;
- `gradle bootRun` plus basic HTTP smoke passed.

Observed in the later fresh Book Loans ON run after package-flow guidance:

- OpenCode generated Spring Boot `3.3.6`, Java 21 toolchain, and local Gradle `9.4.0`;
- `tasks.named("bootJar") { enabled = false }` was not generated;
- `gradle build` passed with `:bootJar UP-TO-DATE`;
- `.persona/workflow/implementation-report.md` recorded that `:bootJar` executed and was not skipped;
- independent `gradle bootRun` plus HTTP happy/failure smoke passed.

## Next

Keep this guidance and monitor future clean runs for regression.

Do not repeat broad A/B loops for package shape here. If confidence is needed before packaging, run one additional fresh ON smoke on a different backend domain rather than reopening the old package-shape A/B loop.
