correx/core/kernel/AGENTS.md

core/kernel — AGENTS.md

Purpose

Top-level orchestration: drives session lifecycle through workflow stages, coordinates retries, manages approval gating, runs static analysis, and provides deterministic replay of past sessions.

Ownership

CORREX kernel team. This is the integration point for all other core/ modules. Changes here affect end-to-end session behavior.

Local Contracts

• SessionOrchestrator / DefaultSessionOrchestrator — primary entry point for launching and advancing sessions through workflow stages.
• OrchestrationState / OrchestrationReducer (DefaultOrchestrationReducer) / OrchestrationProjector / OrchestrationRepository — standard event-sourcing stack for orchestration state.
• RetryCoordinator / DefaultRetryCoordinator — manages retry logic per RetryPolicy.
• On a recoverable tool failure dispatchToolCalls feeds the failing tool's argument schema back into context alongside the error (toolArgsHint), so the model self-corrects a malformed call instead of repeating it — the contract stays strict; the feedback is what loosens.
• Stages that grant tools (allowedTools non-empty) request ModelCapability.ToolCalling on top of their declared capabilities when routing, so the capability-aware strategy steers them to the best tool-calling model.
• ApprovalGateway — kernel-side approval bridge; calls core:approvals engine before executing gated operations. Per-tool gating in dispatchToolCalls builds the ApprovalContext mode from the session's bound operator profile (boundProfile.approvalMode, mapped by approvalModeFor): unset/prompt keeps a human in the loop (default), auto auto-approves up to T2, yolo all tiers, deny blocks above T0. The engine is always consulted (Invariant #4 holds); policy/plane-2 BLOCK stays terminal regardless of mode.
• ReplayOrchestrator / ReplayInferenceProvider / ReplayStrategy — deterministic replay of a session from its event log. ReplayInferenceProvider returns recorded responses — no live LLM (Hard Invariant #8).
• SubagentRunner / InSessionSubagentRunner — runs sub-agent invocations within an active session.
• StaticAnalysisRunner / ProcessStaticAnalysisRunner — runs static analysis tools and records results as events.
• LspDiagnosticsRunner — injected pull-diagnostics seam; diagnostics are filtered to stage-written files, recorded, and enforced before build/review.
• Review→rework loops use the configured three-cycle default, then route accumulated notes to recovery once and fail if the fixed DoD still cannot be approved.
• StageCheckpointReconciler — reconciles checkpoint state across stage transitions.
• Capability-gated failures first retry in place when the stage holds the required tool; an unchanged-fingerprint gate-budget exhaustion routes to the recovery/intent-holder stage when one is available, so capability possession alone cannot cause a frozen owner loop to fail the workflow.
• Three repeated REFERENCE_EXISTS blocks for the same build prerequisite within one stage become a workspace_precondition gate failure, which is eligible for file-write recovery rather than remaining disconnected tool-call noise.
• Every stage receives a small curated operating-guidance system entry: verify observed state, create required project setup, and resolve necessary scope edges without re-deliberating.
• JournalCompactionService — triggers journal compaction and emits JournalCompactedEvent.
• OrchestratorEngines / OrchestratorRepositories — dependency bundles for wiring.
• WorkspaceContext / WorkspaceToolRegistryProvider — workspace-scoped tool registry provisioning.
• RepoKnowledgeRetriever — retrieves repo knowledge facts recorded as events (Hard Invariant #9: observations recorded at query time, not re-queried during replay).
• BriefEchoDiff / BriefReferenceExtractor — brief grounding utilities.
• CritiqueOutcomeCorrelator — correlates critique findings with orchestration outcomes for calibration.
• ContextFeedback — feeds context signals back into the orchestration loop.
• PreemptRedirect — handles steering/preempt events mid-session.
• ReplayArtifactMissingException — thrown when replay requires an artifact that was not recorded.

Work Guidance

• Follow the standard Events→State→Reducer→Projector→Repository pattern (see core/AGENTS.md).
• DefaultOrchestrationReducer only does state.copy(...). All routing decisions live in DefaultSessionOrchestrator.
• Hard Invariant #3: DefaultSessionOrchestrator decides; LLM proposals from core:inference are inputs, not decisions.
• Hard Invariant #4: ApprovalGateway must be called before any gated operation. Policy denial is terminal.
• Hard Invariant #8: ReplayOrchestrator must never call a live provider. Use ReplayInferenceProvider.
• OrchestratorEngines and OrchestratorRepositories are the canonical wiring containers. Add new dependencies there, not as ad-hoc constructor params scattered across callers.

Verification

./gradlew :core:kernel:test --rerun-tasks

Tests in testing/kernel/ (RetryCoordinator, ReplayInferenceProvider, LaunchRegistrationRace, ContextFeedback) and testing/replay/ (session replay, execution plan, refinement, repo knowledge replay).

Child DOX Index

No child AGENTS.md (leaf module).