# 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).