docs: add module documentation in AsciiDoc with PlantUML diagrams

Generated by per-group subagents covering all 52 modules across:
core (18), infrastructure (10), apps (5), interfaces (3),
plugins (7), testing (9)

Documentation format:
- AsciiDoc (.adoc) files in docs/modules/<group>/
- PlantUML (.puml) files in docs/diagrams/
- .adoc files reference diagrams via include:: directives

Each doc covers: purpose, responsibilities, non-responsibilities,
key types, event flow, integration points, invariants, PlantUML
diagram, known issues, and open questions.

docs/modules/testing/test-contracts.adoc

@@ -0,0 +1,87 @@
+= test-contracts
+
+== purpose
+
+Contract tests that validate the behavioral guarantees of core domain types. Ensures that value objects, model classes, and domain interfaces conform to their documented contracts across serialization, equality, and behavior.
+
+== responsibilities
+
+* Validate `WorkflowGraph`, `StageId`, `TransitionId` construction and invariants
+* Test `InferenceProvider` contract (routing, health check, caching)
+* Test `ValidationReport` contract and serialization
+* Test `ContextSnapshot` construction and serialization
+* Test orchestration model types (`OrchestrationConfig`, `WorkflowResult`, `StageOutcome`, `RetryPolicy`)
+* Provide concurrent testing utilities (`ConcurrencyRunner`, `DeterministicBarrier`)
+
+== non-responsibilities
+
+* Does not test full integration between modules
+* Does not test infrastructure adapters
+* Does not test UI or application layers
+
+== key types (test utilities)
+
+=== ConcurrencyRunner
+* **kind**: object
+* **purpose**: Runs a block concurrently across N threads for M iterations using a `CountDownLatch` for synchronized start. Used for concurrency safety contract tests.
+
+=== DeterministicBarrier
+* **kind**: class
+* **purpose**: Thin wrapper over `java.util.concurrent.CyclicBarrier` for synchronizing test threads at known points.
+
+=== WorkflowGraphTest
+* **kind**: JUnit 5 test class
+* **purpose**: Tests `WorkflowGraph` construction, stage lookup, transition validation, and serialization round-trips.
+
+=== InferenceProviderContractTest
+* **kind**: JUnit 5 test class
+* **purpose**: Defines the contract that all `InferenceProvider` implementations must satisfy (request handling, health check, capability reporting).
+
+=== DefaultInferenceRouterTest / DefaultInferenceRouterCacheTest
+* **kind**: JUnit 5 test classes
+* **purpose**: Tests routing strategy, provider selection, and cache invalidation behavior.
+
+=== EventsTest
+* **kind**: JUnit 5 test class
+* **purpose**: Tests event payload construction, metadata, and serialization contracts.
+
+== event flow
+
+*inbound:* Constructed domain objects and serialized JSON strings.
+
+*outbound:* Assertions on equality, serialization round-trips, exception types, and behavioral contracts.
+
+== integration points
+
+* `:core:transitions` — `WorkflowGraph`, `StageConfig`, `TransitionEdge`
+* `:core:inference` — `InferenceProvider`, `DefaultInferenceRouter`, `ProviderHealth`
+* `:core:validation` — `ValidationReport`, validation model types
+* `:core:events` — event payload types, `EventMetadata`
+* `:core:context` — `ContextSnapshot`
+* `:core:kernel` — orchestration config and result types
+
+== invariants
+
+* All serializable types survive a JSON encode/decode round-trip without data loss
+* `StageId` and `TransitionId` are valid when non-blank
+* `InferenceProvider.healthCheck()` never throws for healthy providers
+
+== PlantUML diagram
+
+[plantuml, test-contracts, "png"]
+----
+include::../../diagrams/test-contracts.puml[]
+----
+
+
+
+
+== known issues
+
+* `ConcurrencyRunner` does not assert on thread safety — it only provides concurrent execution scaffolding; the test must supply assertions
+* `DeterministicBarrier` does not have a timeout — a stalled test thread will hang indefinitely
+
+== open questions
+
+* Should contract tests be parameterized to run against all implementations of each interface?
+* Should JSON schema validation be added to serialization contract tests?