tech-log-backend/docs/superpowers/plans/2026-08-02-warning-zero-build-refactoring.md

# Warning-Zero Build Refactoring Implementation Plan

> **For Codex:** REQUIRED SUB-SKILLS: use `superpowers:subagent-driven-development` for the
> independent owner-leaf batches, `superpowers:test-driven-development` for behavior changes,
> `superpowers:systematic-debugging` for any failure, and
> `superpowers:verification-before-completion` before reporting success.

**Goal:** Remove the audited compiler/static-analysis/test-output warning debt, preserve the approved
legacy compatibility boundaries, and make the blocking build fail on any future warning.

**Architecture:** Fix behavior in the owning leaf, preserve identity/framework/compatibility seams
with the narrowest justified suppressions, migrate deprecated provider APIs in their outbound leaf,
then enable root Gradle/CI gates only after all focused tasks are clean. No dependency edge or runtime
membership changes are permitted. The 19-leaf registry remains the dependency SSOT.

**Tech Stack:** Java 21, Spring Boot 4.0.0, Gradle multi-project build, JUnit 5, AssertJ, Mockito,
Error Prone, Checkstyle, SpotBugs, Jackson 3.0.2, Lettuce 6.8.1, AWS SDK v2, Testcontainers 2.

**Approved design:**
`docs/superpowers/specs/2026-08-02-warning-zero-build-design.md`

**Repository constraints:** The worktree already contains user/P0/P1/P2 changes. Preserve them,
never reset or rewrite unrelated files, and do not stage, commit, amend, or push. Agent tasks must
edit only their assigned files and report overlaps before proceeding.

## Task 1: Freeze warning evidence and add behavior regressions

**Owner leaves:** `adapter-inbound-web`, `adapter-outbound-notification`, `sample-portfolio`,
`app-bootstrap`

**Files:**

- Add: `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/JwtToAuthenticatedPrincipalConverterTest.java`
- Modify: `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/conditional/ETagsTest.java`
- Modify: `src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/core/RoutingNotifierTest.java`
- Modify: `src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/adapter/outbound/repostats/RepoStatsAclMapperTest.java`
- Modify: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/async/AsyncGracefulShutdownBehaviorTest.java`

**Steps:**

1. Add Turkish-default-locale regressions for JWT role uppercasing, notification route-key
   lowercasing, and repository ACL lowercasing. Snapshot `Locale.getDefault()`, set
   `Locale.forLanguageTag("tr-TR")`, and restore it in `finally`.
2. Add RED ETag cases for `"opaque,tag"`, weak `W/"opaque,tag"` inside a mixed list, malformed
   unclosed quotes, wildcard, blank, stale, and ordinary multiple values.
3. Add a RED async case proving an exception raised in the submitted action reaches the test through
   `Future.get()`.
4. Run the exact focused tests. Confirm the new locale/ETag cases fail for the intended reason; the
   async change uses the existing `FutureReturnValueIgnored` compile diagnostic as its RED contract:

   ```bash
   ./gradlew :adapter:inbound:web:test --tests '*JwtToAuthenticatedPrincipalConverterTest' --tests '*ETag*' --console=plain
   ./gradlew :adapter:outbound:notification:test --tests '*RoutingNotifier*' --console=plain
   ./gradlew :sample-portfolio:test --tests '*RepoStatsAclMapper*' --console=plain
   ./gradlew :app-bootstrap:test --tests '*AsyncGracefulShutdownBehaviorTest' --console=plain
   ```

5. Do not change production code in this task; retain the behavior-test failures and compile warning
   as the TDD/static-analysis baseline.

## Task 2: Correct locale, ETag, async, cleanup, and host-default behavior

**Owner leaves:** `adapter-inbound-web`, `adapter-outbound-notification`, `sample-portfolio`,
`app-bootstrap`, `application-core`, `shared-contract`, `adapter-outbound-fileserver`,
`adapter-outbound-httpclient`, `adapter-outbound-identifier`

**Production files:**

- Modify: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/JwtToAuthenticatedPrincipalConverter.java`
- Modify: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/conditional/ETags.java`
- Modify: `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/core/RoutingNotifier.java`
- Modify: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/outbound/repostats/RepoStatsAclMapper.java`

**Test/mechanical files:**

- Modify the nine audited implicit-charset sites in `CursorCodecTest`,
  `RedisTrustMaterialProviderTest`, `OutboundHttpClientTest`,
  `HmacUserPrincipalPseudonymizerTest`, `StreamingResponseBodyAllowedFixture`, and
  `IdempotencyExecutorTest`.
- Modify the remaining audited test-only locale sites in `JwtDecoderConfigTest`,
  `OutboundHttpClientTest`, `WorkLogReservedIntegrationEventMapperJsonTest`, `WorkLogIdTest`, and
  `TraceParentTest`.
- Modify: `src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/domain/worklog/WorkLogTest.java`
- Modify the four outbox cleanup classes under
  `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/integration/outbox/`.
- Modify: `src/adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/FilesystemCsvExportAdapterTest.java`

**Steps:**

1. Use `Locale.ROOT` at the three production identifier sites and at audited test comparisons.
2. Replace `ETags` delimiter splitting with a quote-aware scanner. Split only on commas outside
   quoted opaque tags; malformed quoting yields no match. Keep wildcard and weak-tag semantics.
3. Retain and observe the async `Future<?>`; unwrap `ExecutionException` only as required by the
   test's existing assertion contract.
4. Replace empty cleanup catches with propagation or `IllegalStateException`/`UncheckedIOException`
   preserving the original cause.
5. Replace implicit charset calls with `StandardCharsets.UTF_8`; replace `LocalDate.now()` test data
   with the fixed intended date or an explicit UTC clock.
6. Convert byte-identical readability literals to text blocks and verify the exact expected strings.
7. Run the focused tests from Task 1 and the affected owner test suites:

   ```bash
   ./gradlew :application-core:test :shared-contract:test :adapter:inbound:web:test \
     :adapter:outbound:notification:test :adapter:outbound:fileserver:test \
     :adapter:outbound:httpclient:test :adapter:outbound:identifier:test \
     :sample-portfolio:test :app-bootstrap:test --console=plain
   ```

## Task 3: Preserve Redis invariants and migrate Lettuce calls

**Owner leaf:** `adapter-outbound-cache-redis`

**Files:**

- Modify: `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisPrimitiveInvocation.java`
- Modify: `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisTopologyCommandRuntime.java`
- Modify: `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisVersionedSession.java`
- Modify: `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/VersionedRedisSessionStore.java`
- Add: `src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/RedisPrimitiveInvocationTest.java`
- Add: `src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/VersionedRedisSessionStoreTest.java`
- Modify: `src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/LettuceRedisRuntimeServiceTest.java`
- Modify: `src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/RedisVersionedSessionRepositoryTest.java`
- Modify: `src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/RedisPrimitiveRuntimeServiceTest.java`

**Steps:**

1. Add characterization regressions proving a value-equal descriptor from a different catalog is
   rejected and the four session array records copy constructor inputs and accessor outputs. These
   should pass before implementation because they justify preserving the invariants; the compiler
   warnings are the RED executable contract for the suppression/migration work.
2. Keep descriptor reference equality and add constructor-only
   `@SuppressWarnings("ReferenceEquality")` with an invariant rationale.
3. Qualify every ambiguous nested `ExpectedKind` reference with its enclosing record.
4. Keep Spring Session's `<T> T getAttribute(String)` signature and add method-only
   `TypeParameterUnusedInFormals` suppression.
5. Preserve defensive copying for the four `VersionedRedisSessionStore` array records; apply exact
   `ArrayRecordComponent` suppressions to those records and the private test fake only.
6. Convert canonical finite score strings to `BigDecimal`, build inclusive Lettuce `Range` values,
   and use typed `zcount` and `zrangebyscoreWithScores(..., Limit.create(...))` overloads. Extend the
   runtime proxy test to prove both overloads and their offset/count arguments.
7. Replace one-shot `new SecureRandom()` with one static final instance.
8. Run:

   ```bash
   ./gradlew :adapter:outbound:cache-redis:test --console=plain
   ./gradlew :adapter:outbound:cache-redis:compileJava \
     :adapter:outbound:cache-redis:compileTestJava --rerun-tasks --console=plain
   ./gradlew :adapter:outbound:cache-redis:spotbugsTest --rerun-tasks --console=plain
   ```

## Task 4: Preserve HTTP retry and notification ciphertext invariants

**Owner leaves:** `adapter-outbound-httpclient`, `adapter-outbound-persistence-jpa`

**Files:**

- Modify: `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/OutboundRetryPolicy.java`
- Modify: `src/adapter/outbound/httpclient/src/test/groovy/dev/caskeleton/adapter/outbound/httpclient/OutboundRetryPolicySpec.groovy`
- Modify: `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/crypto/NotificationCiphertext.java`
- Modify: `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/notification/crypto/NotificationPayloadCryptoTest.java`

**Steps:**

1. Add a characterization test using two `OutboundRetryPolicy` instances on one thread: policy A
   context must not be visible to policy B, and `endCall()` must clear the owning context. It should
   pass before implementation and justifies preserving the instance field; the compile warning is
   the RED contract.
2. Keep the instance `ThreadLocal`; add field-only `ThreadLocalUsage` suppression with the isolation
   reason.
3. Add/strengthen tests proving `NotificationCiphertext` clones nonce/ciphertext inputs and
   accessors, compares arrays by content, hashes consistently, and never exposes bytes in
   `toString()`.
4. Keep the record API and add exact record-level `ArrayRecordComponent` suppression.
5. Run:

   ```bash
   ./gradlew :adapter:outbound:httpclient:test --console=plain
   ./gradlew :adapter:outbound:persistence-jpa:test --console=plain
   ```

## Task 5: Migrate Jackson 3 messaging APIs

**Owner leaf:** `adapter-outbound-messaging`

**Files:**

- Modify: `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/schema/LocalJsonSchemaRegistry.java`
- Modify: `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/envelope/DeterministicEnvelopeWriter.java`
- Modify: `src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/envelope/LocalJsonSchemaRegistryTest.java`
- Modify: `src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/envelope/JsonSchemaIntegrationEventEncoderTest.java`

**Steps:**

1. Extend existing tests to freeze text-node validation and canonical envelope bytes.
2. Replace `isTextual()`/`textValue()` with `isString()`/`stringValue()`.
3. Replace `createGenerator(output)` with
   `createGenerator(ObjectWriteContext.empty(), output, JsonEncoding.UTF8)`.
4. Run:

   ```bash
   ./gradlew :adapter:outbound:messaging:test --console=plain
   ./gradlew :adapter:outbound:messaging:compileJava --rerun-tasks --console=plain
   ```

## Task 6: Preserve legacy object storage and migrate provider APIs

**Owner leaves:** `application-core`, `adapter-outbound-objectstorage`, `sample-portfolio`,
`app-bootstrap` architecture tests

**Files:**

- Modify: `src/application-core/src/main/java/dev/caskeleton/application/storage/ObjectStoragePort.java`
- Modify the six Java files under
  `src/application-core/src/main/java/dev/caskeleton/application/storage/migration/`.
- Modify: `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/FilesystemObjectStorageAdapter.java`
- Modify: `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/S3ObjectStorageAdapter.java`
- Modify: `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/maintenance/LegacyObjectInspector.java`
- Modify: `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/maintenance/LegacyObjectAdoptionService.java`
- Modify: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/poster/UploadPosterImageUseCase.java`
- Modify: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/poster/migration/AdoptLegacyPosterImageUseCase.java`
- Modify: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/objectstorage/PosterImageApiConfig.java`
- Modify: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/LegacyPosterImageController.java`
- Modify: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/mapper/PosterWebMapper.java`
- Modify: `src/application-core/src/test/java/dev/caskeleton/application/objectstorage/ObjectStorageArchitectureContractTest.java`
- Modify: `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/s3/S3AsyncClientFactory.java`
- Modify: `src/adapter/outbound/objectstorage/src/objectStorageMinioFaultTest/java/dev/caskeleton/adapter/outbound/objectstorage/qualification/MinioManagedObjectFaultTest.java`
- Modify: `src/adapter/outbound/objectstorage/build.gradle`
- Modify: `src/adapter/outbound/objectstorage/gradle.lockfile` only if the toxiproxy dependency graph changes.
- Modify audited URL, Mockito varargs, range parser, text-block, and legacy characterization tests.

**Steps:**

1. Add/retain lifecycle tests: `ObjectStoragePort`, `StoredObject`, and adapter-owned
   `ObjectStorageSettings` remain `forRemoval=true`; migration types remain deprecated but are no
   longer `forRemoval`.
2. Change the six migration mechanism types plus `AdoptLegacyPosterImageUseCase` to plain
   `@Deprecated`. Add only exact `deprecation` suppressions at adoption implementation/configuration
   consumers.
3. Add only the exact `removal` suppressions named by the design to legacy implementations,
   controller/mapper/wiring, characterization classes, and single receipt methods.
4. Replace AWS `RetryPolicy`/old equal-jitter API with `StandardRetryStrategy`, half-jitter
   exponential backoff, exact max attempts, and `retryStrategy(...)`. Assert normal/throttling
   configuration in `S3AsyncClientFactoryTest`.
5. Keep the existing `org.testcontainers:testcontainers-toxiproxy` dependency, switch to its
   Testcontainers 2 package, and use `ToxiproxyClient`/`Proxy` against an explicitly exposed proxy
   port. Preserve cut/restore MinIO semantics; update the leaf lock only if resolution actually
   changes.
6. Replace `new URL(String)` with `URI.create(...).toURL()`.
7. Replace Mockito's two-value varargs `thenReturn` with two chained single-value stubs.
8. Replace test-only range splitting with an asserted single-hyphen boundary; keep fingerprint
   literal bytes identical when converting to a text block.
9. Run:

   ```bash
   ./gradlew :application-core:test :adapter:outbound:objectstorage:test \
     :sample-portfolio:test --console=plain
   ./gradlew :adapter:outbound:objectstorage:check --console=plain
   ./gradlew :app-bootstrap:test --tests '*CleanArchitectureTest' --console=plain
   ./gradlew verifyDependencyLocks --console=plain
   ```

10. If Docker is available, run the MinIO fault source-set task. If unavailable, record the exact
    environmental blocker; never suppress its deprecation to claim success.

## Task 7: Remove remaining mechanical Error Prone warnings

**Owner leaves:** `application-core`, `app-bootstrap`, `sample-portfolio`, and the exact test leaves
from the audit inventory

**Files:**

- Modify: `IdempotencyExecutor.java`, `IdempotencySettings.java`,
  `SampleIdempotencySettings.java`, and matching tests.
- Modify: `TracingSampleRateResolver.java` and `TestTaxonomyArchitectureTest.java`.
- Modify: `CleanArchitectureTest.java`, `ManagementActuatorSecurityContractTest.java`,
  `ProblemDetailDisabledConfigTest.java`, and the serialization violation fixture.
- Modify: `CreateWorkLogOutboxTest.java`, `WorkLogUseCasesTest.java`, and the remaining exact sample
  test warning locations.

**Steps:**

1. Replace five `Duration.ofHours(72)` sites with `Duration.ofDays(3)`.
2. Add the missing Javadoc summary and render annotation names as `{@code @WebMvcTest}`.
3. Add all 16 missing `@Override` annotations.
4. Replace Boolean wrapper comparison with the direct literal/assertion form.
5. Preserve the forbidden `new BigDecimal(double/float)` bytecode and add method-only
   `BigDecimalLiteralDouble` suppressions with fixture rationale.
6. Replace the three test-only one-argument splits without changing each grammar:
   limit-bearing CSV handling, equivalent mapping-path scanning, and exact byte-range parsing.
7. Run affected owner tests and rerun all compile tasks with Error Prone:

   ```bash
   ./gradlew :application-core:test :app-bootstrap:test :sample-portfolio:test --console=plain
   ./gradlew compileJava compileTestJava --rerun-tasks --console=plain
   ```

## Task 8: Capture Redis lab expected failures and configure clean test JVMs

**Files:**

- Modify: `infra/redis-lab/test/redis-lab-contract.sh`
- Add: `src/gradle/test-jvm-agents.gradle`
- Modify: `src/build.gradle`

**Steps:**

1. Change `assert_fails` to capture stdout/stderr per invocation, require non-zero status, assert the
   exact expected diagnostic with no extra lines, and print capture only on mismatch.
2. Run `bash -n infra/redis-lab/test/redis-lab-contract.sh`, then run the real Redis lab Gradle/shell
   contract and verify successful output contains no leaked `redis-lab:` child diagnostics.
3. Add a dedicated `mockitoAgent` configuration per Java test project and a relocatable
   `CommandLineArgumentProvider` in `src/gradle/test-jvm-agents.gradle`. Require exactly one
   `mockito-core` jar and emit `-javaagent:<absolute jar>` plus test-only `-Xshare:off`.
4. Apply the script once from the root build and wire every ordinary/custom `Test` task without
   changing production JVM arguments.
5. Run representative Mockito-heavy app-bootstrap, Redis, object-storage, and messaging tests and
   verify no self-attachment/CDS warning is printed.

## Task 9: Enable warning-zero blocking gates

**Files:**

- Modify: `src/build.gradle`
- Modify: `src/app-bootstrap/build.gradle`
- Modify: `.github/workflows/ci-quality-gates.yml`

**Steps:**

1. First run every `JavaCompile` task with `-Xlint:deprecation` and `-Xlint:unchecked`; resolve every
   remaining diagnostic at the exact source owner.
2. Add `-Werror`, `-Xlint:deprecation`, and `-Xlint:unchecked` to every leaf `JavaCompile` task while
   retaining Error Prone.
3. Remove root `checkstyleTest` and `spotbugsTest` `ignoreFailures=true`.
4. Remove app-bootstrap `sampleOffTest`, `functionalTest`, and `conditionalTransportTest`
   Checkstyle/SpotBugs ignore overrides. Keep only `quarantineTest` non-blocking.
5. Add `--warning-mode=fail` to the blocking `quality-gates` Gradle invocation.
6. Run:

   ```bash
   ./gradlew checkstyleTest spotbugsTest --rerun-tasks --console=plain
   ./gradlew check --warning-mode=fail --no-daemon --console=plain
   ```

## Task 10: Fresh repository verification, review, and Wiki capture

**Files:**

- Modify: `docs/superpowers/plans/2026-08-02-warning-zero-build-refactoring.md` only if execution
  evidence exposes a plan correction.
- Modify external Wiki capture:
  `/home/donghyeon/workspace/ai-tool/llm-wiki-private/raw/branch-notes/main.md`
  and `raw/errors/build-success-warning-debt-2026-08-02.md`.

**Steps:**

1. Run owner-focused tests for every changed leaf.
2. Run repository verification from `src/`:

   ```bash
   ./gradlew test --no-daemon --console=plain
   ./gradlew check --no-daemon --console=plain
   ./gradlew build --warning-mode=fail --no-daemon --console=plain
   ./gradlew clean build --warning-mode=all --no-daemon --console=plain
   ./gradlew verifyCleanArchitectureDependencies verifyRuntimeModuleMembership \
     verifyDependencyLocks verifyPublicPathSnapshot verifyEnvKeys \
     --no-daemon --console=plain
   ```

3. Verify the gate matrix, wrapper, shell syntax, XML findings/skips, and diff:

   ```bash
   bash .github/scripts/verify-gate-matrix.sh
   bash .github/scripts/verify-gradle-wrapper.sh .
   bash -n infra/redis-lab/test/redis-lab-contract.sh
   git diff --check
   ```

4. Scan the fresh build log for `warning:`, deprecated/unchecked `Note:`, SpotBugs non-zero output,
   OpenJDK/CDS warnings, Mockito self-attachment, and leaked expected-negative Redis diagnostics.
5. Confirm the skipped-test XML inventory is exactly the five approved optional-adapter contract
   cases and no qualification source set skipped.
6. Dispatch independent code review over behavior fixes, legacy/provider migrations, and
   Gradle/test-noise gates. Apply only evidence-backed findings and rerun affected/full gates.
7. Update the mandatory Wiki branch/error notes with changed files, commands, results, suppression
   inventory, blocked environment-only qualifications, and evidence grade. Run per-file Wiki lint;
   retain the known `main.md` naming-policy conflict without weakening either policy.
8. Report success only if the clean build is exit zero and the final log is warning/noise clean.