Transmission #062: PDD scaffold for character JSON Patch

Planning bundle for Characters JSON Patch

Started a Prompt-Driven Development workspace under .agents/planning/2026-05-12-characters-api-json-patch/ for adding RFC 6902-style JSON Patch to CharactersApiImpl, including evaluation of java-json-tools/json-patch versus bespoke merge logic. Artifacts: rough-idea.md, idea-honing.md, and empty research/, design/, and implementation/ folders for the next PDD steps.

Requirements clarification started

Chose path (1): hone requirements first. Q1 is in idea-honing.md: whether JSON Patch should replace the current update, be a separate endpoint/content type, or coexist during a transition—awaiting the answer before the next question.

Q1 answer recorded: API contract already set via OpenAPI + codegen; focus is implementing CharactersApiImpl to that spec. Q2 (read-only / server-owned paths) posed next.

Q2 answer: Only id is immutable via patch; any change to /id should fail validation / reject the request. Q3 covers concurrent updates (last-write-wins vs optimistic locking).

Q3 answer: Last-write-wins (no optimistic locking). Q4 asks required JSON Patch operations (full RFC 6902 vs subset).

Q4 answer: Must support add, remove, replace, test; move/copy not required (library may still implement them—see Q5).

Q5 answer: Allow move/copy when the engine can apply them; any failure applies atomically to the whole patch—no partial persist. Clarification checkpoint recorded in idea-honing.md.

Iteration checkpoint

Requirements honing marked complete (idea-honing.md, iteration-checkpoint.md). Awaiting choice: design vs research vs return to Q&A.

Research phase

Added research/existing-codebase.md, research/json-patch-library.md, research/synthesis.md — OpenAPI gap for move/copy+from, java-json-tools usage, risks (LGPL, stale release vs Jackson 2.18).

Requirements revisit

User selected revisit requirements; Q6 added to idea-honing.md (OpenAPI vs move/copy / from).

Q6 answer: Option 2 — keep public API to add/remove/replace/test only; move/copy not on wire until spec extended. idea-honing.md, research/synthesis.md, and research/existing-codebase.md updated.

Requirements clarification marked complete; design/detailed-design.md added. implementation/plan.md + summary.md added (4 implementation steps with checklist, tests per step). PDD bundle ready for coding.

Implementation (server)

Shipped JSON Patch for PATCH /characters/{id}: com.github.java-json-tools:json-patch in the version catalog, CharacterJsonPatchSupport + CharacterPatchIdViolationException, JsonContextResolver.jerseyObjectMapper() for a single ObjectMapper config, CharactersApiImpl returning 200 / 404 / 400 as designed. Unit tests in CharacterJsonPatchSupportTest; integration tests in CharactersApiIntegrationTest (require live Jersey per existing stack). ./gradlew test passes.

PDD scaffold: CI workflows + Compose test stack

Started another Prompt-Driven Development workspace under .agents/planning/2026-05-12-gha-compose-test-migration/ to align GitHub Actions with new Makefile targets (compose-up / compose-down, integration-compose-up / integration-compose-down) and to remove Testcontainers in favor of the Compose-based setup. Artifacts so far: rough-idea.md, empty idea-honing.md, and empty research/, design/, implementation/ for the next PDD steps.

GHA compose PDD: Requirements path (1) chosen; Q1 in idea-honing.md asks which workflows/jobs must adopt the Makefile compose targets.

GHA compose PDD: Q5 answered (one job; integration only after unit passes; teardown still always). Checkpoint in idea-honing.md: confirm requirements complete vs more detail before research/design.

GHA compose PDD — research: Added research/ci-and-workflows.md, makefile-and-compose.md, testcontainers-removal.md, synthesis.md (Makefile names vs integration-compose-up; CI docker compose path issue; clean vs JaCoCo ordering).

GHA compose PDD — design: User confirmed research sufficient. Added iteration-checkpoint.md and design/detailed-design.md (workflows, Make targets, Testcontainers removal, mermaid flows, Makefile clean options). Awaiting confirmation before implementation/plan.md.

GHA compose PDD — implementation plan: User approved design; added implementation/plan.md (6 steps + checklist) and summary.md. Ready to execute in repo.

CI + Compose + dropping Testcontainers (implemented)

server-ci.yml now uses make -C server compose-up / compose-down (always) around ./gradlew test jacocoTestReport, then integration-environment-setup / integration-environment-teardown (always) around integrationTest—no bare docker compose from the wrong directory. server/Makefile: integration-environment-setup depends on shadowJar only via shadowJar-for-compose (no clean between unit coverage and integration); integration-compose-up/down aliases; fast-unit runs ./gradlew test; integration-reload-db phony fixed. Testcontainers removed from libs.versions.toml / build.gradle; PostgresTestHelper uses Compose Postgres with Flyway clean + migrate per class. ApiUtils: HttpClient.Version.HTTP_1_1 so Grizzly accepts POST bodies. CharactersApiImpl.patchCharacter: drop @Valid on the list parameter to satisfy Hibernate override rules. CharactersApiIntegrationTest: RandomStringUtils replaced; patch inventory uses a valid [] replace for /items. server/README.md updated; AGENTS.md + .agents/summary/dependencies.md aligned with Makefile/Compose (no stale @Tag("live") / Testcontainers lines). PDD checklist in implementation/plan.md marked done.