80 lines
5.1 KiB
Markdown
80 lines
5.1 KiB
Markdown
# Verification Purity Refactoring 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:** Make stale-JAR and public-path verification strictly read-only while preserving explicit cleanup/update workflows.
|
|
|
|
**Architecture:** Extract only these two root Gradle concerns into applied scripts so the production tasks can be exercised by isolated Gradle TestKit fixtures. Verification tasks only observe and fail; `clean*` and `update*` tasks are the sole writers.
|
|
|
|
**Tech Stack:** Java 21, Gradle 9.0.0 Groovy DSL, Gradle TestKit, JUnit 5, AssertJ.
|
|
|
|
## Global Constraints
|
|
|
|
- Preserve all existing P0 changes in the dirty worktree.
|
|
- Preserve the 19-leaf registry and every production project dependency edge.
|
|
- Normal archive tasks and every `verify*` task must be read-only.
|
|
- `updatePublicPathSnapshot` requires `-PapprovePublicPathChange`.
|
|
- Agents do not stage, commit, amend, or push.
|
|
|
|
---
|
|
|
|
### Task 1: Add Functional RED Contracts
|
|
|
|
**Files:**
|
|
- Create: `src/app-bootstrap/src/functionalTest/java/dev/caskeleton/bootstrap/contract/BuildVerificationPurityContractTest.java`
|
|
- Modify: `src/app-bootstrap/build.gradle`
|
|
- Modify: `src/app-bootstrap/gradle.lockfile`
|
|
|
|
**Interfaces:**
|
|
- Consumes: production scripts at `src/gradle/archive-hygiene.gradle` and `src/gradle/public-path-snapshot.gradle`.
|
|
- Produces: functional tests that execute real Gradle tasks and assert filesystem side effects.
|
|
|
|
- [x] Add an isolated `functionalTest` source set/task and its `functionalTestImplementation gradleTestKit()` dependency so Gradle's SLF4J provider cannot pollute ordinary tests.
|
|
- [x] Add a nested temporary archive fixture with root + `family:module` projects. Apply the production archive script, pre-create a stale traceable JAR and a nonmatching JAR, run `:family:module:jar`, `verifyNoStaleTraceableJars`, and `cleanStaleTraceableJars`, and assert exact preservation/deletion plus the full task-path diagnostic.
|
|
- [x] Add a temporary public-path fixture. Apply the production public-path script and assert missing/drifted snapshots are not written, the verifier rejects `-PapprovePublicPathChange`, and only the approved updater writes canonical content.
|
|
- [x] Confirm the contracts RED before the two production scripts exist. The first RED run used the ordinary test source set; after it exposed Gradle TestKit's SLF4J provider collision, move the contract and TestKit dependency to isolated `functionalTest` configurations and add their strict lock state.
|
|
|
|
### Task 2: Separate Archive Verification from Cleanup
|
|
|
|
**Files:**
|
|
- Create: `src/gradle/archive-hygiene.gradle`
|
|
- Modify: `src/build.gradle`
|
|
|
|
**Interfaces:**
|
|
- Produces: root tasks `verifyNoStaleTraceableJars` and `cleanStaleTraceableJars` with no dependency between them.
|
|
|
|
- [x] Move traceable archive matching/discovery and both root tasks into the applied script.
|
|
- [x] Remove the stale-deleting `doFirst` from every `Jar` task while retaining manifest metadata.
|
|
- [x] Apply the script before leaf `check` dependencies are configured; task actions discover leaf JAR tasks at execution time.
|
|
- [x] Explicitly declare both archive tasks configuration-cache incompatible because their actions inspect subproject task models.
|
|
- [x] Run the focused functional test and confirm archive cases are GREEN.
|
|
|
|
### Task 3: Separate Public-Path Verification from Update
|
|
|
|
**Files:**
|
|
- Create: `src/gradle/public-path-snapshot.gradle`
|
|
- Modify: `src/build.gradle`
|
|
- Modify: `src/README.md`
|
|
- Modify: `docs/security/public-paths-snapshot.txt`
|
|
|
|
**Interfaces:**
|
|
- Produces: read-only `verifyPublicPathSnapshot` and explicitly mutating `updatePublicPathSnapshot`.
|
|
|
|
- [x] Centralize canonical snapshot rendering in the script.
|
|
- [x] Make verification fail on missing env, missing snapshot, drift, and use of the approval property without any writes.
|
|
- [x] Make update require `-PapprovePublicPathChange`, create the parent directory, and write canonical content.
|
|
- [x] Replace documentation and snapshot instructions with `updatePublicPathSnapshot -PapprovePublicPathChange`.
|
|
- [x] Run the focused functional test and confirm all public-path cases are GREEN.
|
|
|
|
### Task 4: Focused and Architecture Verification
|
|
|
|
**Files:** none beyond Tasks 1-3.
|
|
|
|
- [x] Run `./gradlew :app-bootstrap:functionalTest --tests '*BuildVerificationPurityContractTest' --console=plain`.
|
|
- [x] Run `./gradlew :app-bootstrap:test --console=plain`; 640 ordinary tests pass after TestKit isolation (6 skipped), alongside the 9 functional contracts.
|
|
- [x] Run `./gradlew :app-bootstrap:verifyDependencyLocks --console=plain`.
|
|
- [x] Run `./gradlew :app-bootstrap:spotlessJavaCheck :app-bootstrap:checkstyleFunctionalTest :app-bootstrap:spotbugsFunctionalTest --console=plain`.
|
|
- [x] Run `./gradlew verifyNoStaleTraceableJars verifyPublicPathSnapshot --console=plain` and confirm both are read-only and pass on the current baseline.
|
|
- [x] Run `./gradlew verifyCleanArchitectureDependencies --console=plain`.
|
|
- [x] Run `git diff --check` and record `git status --short` without staging or committing.
|