[roadmap] 001 — Gradle Build Migration & Automation Foundation

[oluies]

Draft planning artifact generated via spec-kit — see specs/001-gradle-build-automation/ (spec, plan, research, data-model, contracts, quickstart, tasks).

⚠️ Unverified draft: authored without a build environment (no Gradle/JDK 17/network/TIBCO/DuckDB). On branch t/yolo-d76fe7 (not yet pushed).

Tasks (mirrors specs/001-gradle-build-automation/tasks.md)

Phase 1: Setup (Shared Infrastructure)

• T001 Add the Gradle wrapper pinned to a current stable Gradle (gradlew, gradlew.bat, gradle/wrapper/gradle-wrapper.jar, gradle/wrapper/gradle-wrapper.properties) — PARTIAL: gradle-wrapper.properties authored; gradlew/gradlew.bat/gradle-wrapper.jar must be generated by gradle wrapper (no Gradle available here)
• T002 Create settings.gradle.kts (rootProject.name = "rvsnoop") and a skeleton build.gradle.kts applying the java + application plugins with a Java 17 toolchain and version "1.6.2", carrying the Apache 2.0 license header
• T003 [P] Create gradle.properties with build/toolchain settings (e.g. org.gradle.* options) replacing the per-dev build.properties defaults
• T004 [P] Verify the skeleton resolves: ./gradlew tasks runs via the wrapper on JDK 17 — BLOCKED: no Gradle/JDK 17/network

Phase 2: Foundational (Blocking Prerequisites)

• T005 Verify exact Maven coordinates and public availability for all OSS deps per research.md R2 (confirm log4j, beansbinding, bsaf, db4o, eventbus, glazedlists, jgoodies-forms, xom, junit; resolve nearest releases for the commons-cli/Guava/Guice snapshots); record confirmed coordinates and any local-file fallback (e.g. db4o) back into research.md — BLOCKED: no network. Draft coordinates are in gradle/libs.versions.toml, flagged unverified
• T006 Run the Java 17 compatibility spike per research.md R3 — attempt test + a smoke launch of org.rvsnoop.ui.RvSnoopApplication on JDK 17; identify Guice/db4o (cglib/ASM, reflective-access) failures; record any required minimal-upgrade exceptions in research.md and escalate them to the maintainer before proceeding — BLOCKED: no Gradle/JDK 17/TIBCO jars. HIGHEST-RISK task; do this first in a real env
• T007 Define the external TIBCO library provisioning mechanism (a build property/env for the local path mirroring the Ant lib.tibrv/lib.tibsdk + TIBRV_HOME conventions) so both the local build and CI can supply tibrvj.jar and TIBCOrt.jar without committing them

Phase 3: User Story 1 - Reproducible build from a managed manifest (Priority: P1) 🎯 MVP

• T008 [US1] Create the version catalog gradle/libs.versions.toml with one pinned version per OSS dependency (from T005), explicitly marking the commons-cli/Guava/Guice snapshot→release substitutions — DRAFT: coordinates unverified pending T005
• T009 [US1] Wire dependencies in build.gradle.kts from the catalog (implementation / testImplementation), ensuring exactly one version per library
• T010 [US1] Configure the TIBCO jars as compileOnly + testRuntimeOnly resolved from the external location defined in T007, failing with a clear message naming the missing jar(s) when absent (FR-005)
• T011 [US1] Configure the test task: JUnit 4.4, exclude the abstract org/rvsnoop/RecordLedgerTest, and include the src/test data resources (**/.properties, **/.rbz, **/*.txt)
• T012 [US1] Configure the jar task with the Implementation-Title/Version/Vendor/URL manifest attributes and package resources/**/.png plus **/.properties (excluding commons-logging.properties) in build.gradle.kts
• T013 [P] [US1] Configure the javadoc task (protected access, external links) in build.gradle.kts
• T014 [P] [US1] Configure the pmd and spotbugs tasks (PMD using etc/rvsnoop.pmd — pin toolVersion or migrate the ruleset per research.md R4; SpotBugs replacing FindBugs) in build.gradle.kts — NOTE: SpotBugs plugin left commented pending a verified version
• T015 [US1] Configure the application plugin (mainClass = org.rvsnoop.ui.RvSnoopApplication) and the distZip/distTar packaging (bin/ scripts, docs, runtime libs, -src zip) preserving the rvsnoop-1.6.2 layout — PARTIAL: application plugin + mainClass set; bin/docs/-src.zip distribution wiring is a TODO in build.gradle.kts
• T016 [US1] Verify build parity: run ./gradlew build then ./gradlew build --offline; confirm the produced rvsnoop-1.6.2.jar is equivalent to the Ant jar and the app launches (quickstart S1, S2, S4, S5; CONTRACT-BUILD-1..5) — BLOCKED: no Gradle/JDK 17/network/TIBCO
• T017 [US1] Cut over: remove build.xml and lib/.jar, update README.md build instructions and the Java 17 requirement, and document the snapshot→release substitutions (FR-013, FR-014, SC-007, CONTRACT-DOC-1/2) — DEFERRED: destructive (lib/.jar are git-tracked); must not run until the Gradle build is verified (T016)

Phase 4: User Story 2 - Every change is automatically validated (Priority: P2)

• T018 [US2] Create .github/workflows/ci.yml triggered on push and pull_request: checkout → set up JDK 17 → provision TIBCO jars (T019) → ./gradlew build → publish test results, with a stably named status check (FR-007/FR-009, CONTRACT-CI-1..4)
• T019 [US2] Implement secured TIBCO jar provisioning in the workflow (encrypted secret or credentialed fetch materialised to a runner dir, pointed at by the T007 property), ensuring the jars are never echoed to logs or uploaded as artifacts and the run fails clearly if they are unavailable (FR-015, CONTRACT-CI-5/6)
• T020 [US2] Document the branch-protection / required-status-check rule a maintainer must enable to enforce the green-only merge policy (FR-008, CONTRACT-DOC-3) in README.md or CONTRIBUTING — PARTIAL: documented in the ci.yml header comment; a README/CONTRIBUTING note is still pending
• T021 [US2] Verify CI behaviour on a pull request: a clean PR passes, a deliberately failing test turns the check red (and is blocked once branch protection is on), and no TIBCO/secret content appears in logs (quickstart S6) — BLOCKED: needs a GitHub round-trip

Phase 5: User Story 3 - Automated dependency & pipeline updates (Priority: P3)

• T022 [US3] Create .github/dependabot.yml declaring the gradle ecosystem (root, watching the version catalog) and the github-actions ecosystem (watching workflow action versions) on a weekly schedule (FR-010, CONTRACT-DEP-1/2)
• T023 [US3] Verify a Dependabot-opened update PR triggers the ci.yml workflow and is validated like any other PR (FR-011, CONTRACT-DEP-3; quickstart S7) — BLOCKED: needs a GitHub round-trip

Phase 6: Polish & Cross-Cutting Concerns

• T024 [P] Update CLAUDE.md / developer docs with the Gradle workflow (wrapper commands, JDK 17, TIBCO setup) — NOT DONE: deferred until the build is verified, to avoid documenting an unproven workflow
• T025 Run the full quickstart.md validation (Scenarios 1–8) and confirm all pass — BLOCKED: needs a runnable build + GitHub
• T026 Amend .specify/memory/constitution.md to make Gradle the build system of record (per the governance amendment rule, since the constitution currently names Ant), bumping the version and Last Amended date with a Sync Impact Report entry — DEFERRED: amend only once Gradle is actually authoritative (after cut-over T017)