docs(02-04): complete diagram hash linking gap closure plan

- SUMMARY.md documenting diagram hash linking and test stability fixes
- STATE.md updated with position, decisions, metrics
- ROADMAP.md updated with phase 02 plan progress
- REQUIREMENTS.md DIAG-02 marked complete

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.planning/REQUIREMENTS.md

@@ -113,7 +113,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 | AGNT-06 (#18) | Phase 3 | Pending |
 | AGNT-07 (#19) | Phase 3 | Pending |
 | DIAG-01 (#20) | Phase 2 | Pending |
-| DIAG-02 (#21) | Phase 2 | Pending |
+| DIAG-02 (#21) | Phase 2 | Complete |
 | DIAG-03 (#22) | Phase 2 | Pending |
 | SECU-01 (#23) | Phase 4 | Pending |
 | SECU-02 (#24) | Phase 4 | Pending |

.planning/STATE.md

@@ -3,15 +3,15 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: in-progress
-stopped_at: Completed 02-03-PLAN.md (Phase 02 complete)
+stopped_at: Completed 02-04-PLAN.md (Phase 02 gap closure complete)
-last_updated: "2026-03-11T15:32:00Z"
+last_updated: "2026-03-11T16:36:49Z"
-last_activity: 2026-03-11 -- Completed 02-03 (Search endpoints, detail controller, 24 tests)
+last_activity: 2026-03-11 -- Completed 02-04 (Diagram hash linking, Surefire fix, test stability)
 progress:
   total_phases: 4
   completed_phases: 2
-  total_plans: 3
+  total_plans: 7
-  completed_plans: 3
+  completed_plans: 7
-  percent: 75
+  percent: 100
 ---
 
 # Project State
@@ -26,11 +26,11 @@ See: .planning/PROJECT.md (updated 2026-03-11)
 ## Current Position
 
 Phase: 2 of 4 (Transaction Search + Diagrams) -- COMPLETE
-Plan: 3 of 3 in current phase
+Plan: 4 of 4 in current phase (gap closure)
-Status: Phase 02 Complete
+Status: Phase 02 Complete (including gap closure)
-Last activity: 2026-03-11 -- Completed 02-03 (Search endpoints, detail controller, tree reconstruction, 24 tests)
+Last activity: 2026-03-11 -- Completed 02-04 (Diagram hash linking, Surefire fix, test stability)
 
-Progress: [████████--] 75%
+Progress: [██████████] 100%
 
 ## Performance Metrics
 
@@ -56,6 +56,7 @@ Progress: [████████--] 75%
 | Phase 02 P01 | 13min | 2 tasks | 15 files |
 | Phase 02 P02 | 14min | 2 tasks | 10 files |
 | Phase 02 P03 | 12min | 2 tasks | 9 files |
+| Phase 02 P04 | 22min | 1 tasks | 5 files |
 
 ## Accumulated Context
 
@@ -88,6 +89,9 @@ Recent decisions affecting current work:
 - [Phase 02]: Search tests use correlationId scoping for shared ClickHouse isolation
 - [Phase 02]: findProcessorSnapshot uses ClickHouse 1-indexed array access
 - [Phase 02]: DetailController injects ClickHouseExecutionRepository directly for snapshot (not via interface)
+- [Phase 02]: DiagramRepository injected via constructor into ClickHouseExecutionRepository for diagram hash lookup during batch insert
+- [Phase 02]: Awaitility ignoreExceptions pattern adopted for all ClickHouse polling assertions
+- [Phase 02]: Surefire and Failsafe both need reuseForks=false for ELK classloader isolation
 
 ### Pending Todos
 
@@ -102,6 +106,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-03-11T15:32:00Z
+Last session: 2026-03-11T16:36:49Z
-Stopped at: Completed 02-03-PLAN.md (Phase 02 complete)
+Stopped at: Completed 02-04-PLAN.md (Phase 02 gap closure complete)
-Resume file: .planning/phases/02-transaction-search-diagrams/02-03-SUMMARY.md
+Resume file: .planning/phases/02-transaction-search-diagrams/02-04-SUMMARY.md

.planning/config.json

@@ -8,6 +8,7 @@
     "research": true,
     "plan_check": true,
     "verifier": true,
-    "nyquist_validation": true
+    "nyquist_validation": true,
+    "_auto_chain_active": false
   }
 }

.planning/phases/02-transaction-search-diagrams/02-04-SUMMARY.md

@@ -0,0 +1,121 @@
+---
+phase: 02-transaction-search-diagrams
+plan: 04
+subsystem: database
+tags: [clickhouse, diagram-linking, surefire, testcontainers, awaitility]
+
+# Dependency graph
+requires:
+  - phase: 02-transaction-search-diagrams (plans 01-03)
+    provides: ClickHouse schema, execution repository, diagram repository, ingestion pipeline
+provides:
+  - diagram_content_hash populated during execution ingestion (DIAG-02 complete)
+  - stable mvn clean verify with classloader isolation
+affects: [03-agent-registry-sse, 04-security-api-docs]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [awaitility ignoreExceptions for ClickHouse eventual consistency, surefire reuseForks=false for ELK classloader isolation]
+
+key-files:
+  created:
+    - cameleer3-server-app/src/test/java/com/cameleer3/server/app/storage/DiagramLinkingIT.java
+  modified:
+    - cameleer3-server-app/src/main/java/com/cameleer3/server/app/storage/ClickHouseExecutionRepository.java
+    - cameleer3-server-app/pom.xml
+    - cameleer3-server-app/src/test/java/com/cameleer3/server/app/storage/IngestionSchemaIT.java
+    - cameleer3-server-app/src/test/java/com/cameleer3/server/app/controller/SearchControllerIT.java
+
+key-decisions:
+  - "DiagramRepository injected via constructor into ClickHouseExecutionRepository for diagram hash lookup during batch insert"
+  - "Awaitility ignoreExceptions pattern adopted for all ClickHouse polling assertions to handle EmptyResultDataAccessException during flush delay"
+  - "Surefire and Failsafe both configured with reuseForks=false to isolate ELK static initializer from Spring Boot classloader"
+
+patterns-established:
+  - "Awaitility ignoreExceptions: all awaitility assertions polling ClickHouse must use .ignoreExceptions() to tolerate EmptyResultDataAccessException before data is flushed"
+
+requirements-completed: [DIAG-02]
+
+# Metrics
+duration: 22min
+completed: 2026-03-11
+---
+
+# Phase 2 Plan 4: Gap Closure Summary
+
+**Diagram hash linking during execution ingestion via DiagramRepository lookup, plus Surefire/Failsafe classloader isolation and test stability fixes**
+
+## Performance
+
+- **Duration:** 22 min
+- **Started:** 2026-03-11T16:13:57Z
+- **Completed:** 2026-03-11T16:36:49Z
+- **Tasks:** 1
+- **Files modified:** 5
+
+## Accomplishments
+- diagram_content_hash populated with active RouteGraph SHA-256 hash during batch insert (DIAG-02 fully satisfied)
+- DiagramLinkingIT integration test proves both positive (hash populated) and negative (empty fallback) cases
+- `mvn clean verify` passes reliably -- 51 tests, 0 failures, 0 errors
+- Fixed flaky test failures caused by EmptyResultDataAccessException in awaitility polling
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Populate diagram_content_hash during ingestion and fix Surefire forks** - `34c8310` (feat)
+
+**Plan metadata:** (pending)
+
+## Files Created/Modified
+- `cameleer3-server-app/src/main/java/com/cameleer3/server/app/storage/ClickHouseExecutionRepository.java` - Added DiagramRepository injection, diagram hash lookup in insertBatch
+- `cameleer3-server-app/pom.xml` - Added maven-surefire-plugin and maven-failsafe-plugin with reuseForks=false
+- `cameleer3-server-app/src/test/java/com/cameleer3/server/app/storage/DiagramLinkingIT.java` - Integration test for diagram hash linking
+- `cameleer3-server-app/src/test/java/com/cameleer3/server/app/storage/IngestionSchemaIT.java` - Added ignoreExceptions + increased timeouts
+- `cameleer3-server-app/src/test/java/com/cameleer3/server/app/controller/SearchControllerIT.java` - Adjusted pagination assertion count
+
+## Decisions Made
+- DiagramRepository injected via constructor into ClickHouseExecutionRepository -- both are @Repository Spring beans, so constructor injection autowires cleanly
+- Used `ignoreExceptions()` in awaitility chains rather than switching from `queryForObject` to `queryForList`, since ignoreExceptions is the canonical awaitility pattern for eventual consistency
+- Surefire AND Failsafe both need reuseForks=false -- ELK's LayeredMetaDataProvider static initializer poisons the JVM classloader for subsequent Spring Boot test contexts
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed flaky integration tests due to awaitility not retrying EmptyResultDataAccessException**
+- **Found during:** Task 1 (verification step)
+- **Issue:** Awaitility's `untilAsserted` was not retrying `EmptyResultDataAccessException` thrown by `queryForObject` when data hadn't been flushed yet, causing intermittent test failures
+- **Fix:** Added `.ignoreExceptions()` to all awaitility assertions that poll ClickHouse with `queryForObject`, and increased IngestionSchemaIT timeouts from 10s to 30s
+- **Files modified:** DiagramLinkingIT.java, IngestionSchemaIT.java
+- **Verification:** `mvn clean verify` passes with 51/51 tests green
+- **Committed in:** 34c8310 (part of Task 1 commit)
+
+**2. [Rule 1 - Bug] Fixed SearchControllerIT pagination assertion count**
+- **Found during:** Task 1 (verification step)
+- **Issue:** Pagination test asserted >= 8 COMPLETED executions but seed data only contains 7 COMPLETED (execs 2,4 are FAILED, exec 3 is RUNNING)
+- **Fix:** Changed assertion to `isGreaterThanOrEqualTo(7)`
+- **Files modified:** SearchControllerIT.java
+- **Verification:** Test passes consistently
+- **Committed in:** 34c8310 (part of Task 1 commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (2 bugs)
+**Impact on plan:** Both fixes required for test reliability. No scope creep.
+
+## Issues Encountered
+- Initial `mvn clean verify` had 3 test failures (DiagramLinkingIT x2, IngestionSchemaIT x1) all caused by `EmptyResultDataAccessException` in awaitility assertions. Root cause: awaitility was propagating the exception immediately instead of retrying. Fixed by adding `ignoreExceptions()`.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Phase 2 fully complete: ingestion, search, detail, diagrams, and now diagram-execution linking
+- DIAG-02 requirement satisfied: transactions link to the RouteGraph version active at execution time
+- Test suite stable at 51 tests with classloader isolation
+
+---
+*Phase: 02-transaction-search-diagrams*
+*Completed: 2026-03-11*