docs(dox): build out the DOX AGENTS.md hierarchy

Root Child DOX Index assembled, plus a per-module AGENTS.md across the tree (core/*, infrastructure/*, apps/*, testing/*, and docs/examples/frontend/etc), each following the DOX section shape: Purpose, Ownership, Local Contracts, Work Guidance, Verification, Child DOX Index.
2026-06-28 20:43:27 +04:00
parent 1cb7fec677
commit d26f20c316
48 changed files with 1783 additions and 0 deletions
@@ -0,0 +1,42 @@
+# core/transitions — AGENTS.md
+
+## Purpose
+
+FSM/workflow graph execution: defines the `WorkflowGraph` (stages and transition edges), resolves which transition to take at each step, executes stages, and detects cycles.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `WorkflowGraph` — the workflow DAG: stages (`StageConfig`) connected by `TransitionEdge`s.
+- `TransitionResolver` / `DefaultTransitionResolver` — evaluates `TransitionCondition`s against `EvaluationContext` to pick the next stage.
+- `TransitionCondition` — sealed interface for conditions. Built-in: `AlwaysTrue`, `VariableEquals`, `ArtifactFieldEquals`, `ArtifactConditions`, and composites (`Composites`).
+- `StageExecutor` — executes a single stage given a `StageExecutionRequest`; returns `StageExecutionResult`.
+- `StageExecutionEventMapper` / `DefaultStageExecutionEventMapper` — maps stage execution results to domain events.
+- `TransitionDecision` / `TransitionOrdering` — decision and ordering types.
+- `EvaluationContext` — runtime context for condition evaluation.
+- `PromptResolver` — resolves prompt templates for a stage from config.
+- `CycleExtractor` / `CycleDfs` / `DetectedCycle` / `CycleCanonicalizer` — detect and canonicalize cycles in the workflow graph (used by `core:validation`).
+- `DeterministicAdjacencyBuilder` / `GraphOrdering` — deterministic graph traversal for consistent ordering.
+- `VisitState` — DFS traversal state.
+
+## Work Guidance
+
+- `DefaultTransitionResolver` is stateless per call — it reads `EvaluationContext`, not persisted state.
+- Stage events are recorded by `DefaultStageExecutionEventMapper`; the mapper must emit events for every outcome (success, failure, skip).
+- `WorkflowGraph` is built from config/TOML at session start; it is immutable during a session.
+- Cycle detection (`CycleExtractor`) runs during graph validation (`core:validation`), not at runtime.
+
+## Verification
+
+```bash
+./gradlew :core:transitions:test --rerun-tasks
+```
+
+Tests in `testing/transitions/` (DefaultTransitionResolverTest, TransitionFuzzTest, TransitionEventSerializationTest) and `testing/replay/` (TransitionReplayIntegrationTest).
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).