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,50 @@
+# 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`.
+- `ApprovalGateway` — kernel-side approval bridge; calls `core:approvals` engine before executing gated operations.
+- `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.
+- `StageCheckpointReconciler` — reconciles checkpoint state across stage transitions.
+- `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
+
+```bash
+./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).