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.

core/AGENTS.md

@@ -0,0 +1,74 @@
+# core/ — AGENTS.md
+
+## Purpose
+
+Pure domain logic for CORREX: event sourcing primitives, session orchestration, inference routing, tool management, workflow graph execution, and all supporting domain services. No I/O, no external adapters.
+
+## Ownership
+
+All modules under `core/` are owned by the CORREX kernel team. Changes to shared event types (in `core:events`) require review for downstream impact across all modules.
+
+## Local Contracts
+
+- Dependency direction: `apps → core → infrastructure`. No cross-core imports. No sibling module dependencies within `core/`.
+- Shared vocabulary types belong in `core:events` only.
+- Constructor parameters use interfaces wherever an interface exists. Concrete classes are never instantiated inside another class.
+- All state is rebuilt from events. State is never persisted independently.
+- Every new `EventPayload` subclass must be registered in `core/events/.../serialization/Serialization.kt` inside the `eventModule` polymorphic block. Missing registration causes silent runtime deserialization failure.
+
+## Work Guidance
+
+Follow the standard domain module pattern for every module in this subtree:
+
+1. **Events** — `@Serializable data class` implementing `EventPayload`, defined in `core:events`.
+2. **State** — module-local `@Serializable data class` with sensible empty defaults. Always rebuilt from events.
+3. **Reducer** — `interface ThingReducer` + `DefaultThingReducer`. Only `state.copy(...)` logic, no domain decisions.
+4. **Projector** — `class ThingProjector(reducer)` implementing `Projection<ThingState>`.
+5. **Repository** — `DefaultThingRepository(replayer: EventReplayer<ThingState>)`. Wired as `DefaultEventReplayer(store, ThingProjector(DefaultThingReducer()))`.
+
+**Hard Invariants (all apply here):**
+1. Event log is the only source of truth.
+2. Projections are bounded-context owned — no shared global state, no cross-projection mutation.
+3. LLMs propose; core decides. LLM outputs are untrusted until validated.
+4. Policy layer is absolute — approvals cannot override policy denial.
+5. All tools declare execution tier. All tool side effects captured in events.
+6. Compression is non-authoritative — derived representations must not replace original events.
+7. Replay is environment-independent — no external service calls, no live LLM required.
+8. Environment observations are recorded as events at the moment they occur, never re-queried during replay.
+
+**Kotlin rules:**
+- `runCatching { }` over bare try/catch.
+- Scope functions (`?.let`, `?:`) over null-branching `if/else`.
+- `suspend` + `delay()`, never `Thread.sleep()`. Blocking I/O in `withContext(Dispatchers.IO)`.
+- Never swallow `CancellationException`.
+- Verify all imports are used before finalizing any file.
+
+## Verification
+
+```bash
+./gradlew check                                  # full suite: tests + detekt + koverVerify
+./gradlew :core:<module>:test --rerun-tasks      # single module, bypass cache
+```
+
+Many tests live in `testing/` submodules (approvals, contracts, deterministic, kernel, projections, replay, transitions) — check there before concluding a module has no tests.
+
+## Child DOX Index
+
+- [approvals/](approvals/AGENTS.md) — approval gate engine: grants, modes, policy enforcement
+- [artifacts/](artifacts/AGENTS.md) — structured output model: artifact kinds, lineage, relationships
+- [artifacts-store/](artifacts-store/AGENTS.md) — artifact persistence interface
+- [config/](config/AGENTS.md) — TOML config loading, operator/project profile, agent instructions
+- [context/](context/AGENTS.md) — context synthesis, compression, token budgeting
+- [critique/](critique/AGENTS.md) — critic calibration state and projector
+- [events/](events/AGENTS.md) — event primitives, serialization registry, replay infrastructure
+- [inference/](inference/AGENTS.md) — provider abstraction, routing, prompt rendering, embedder
+- [journal/](journal/AGENTS.md) — decision journal projection and memory distillation
+- [kernel/](kernel/AGENTS.md) — top-level orchestration: SessionOrchestrator, retry, replay
+- [risk/](risk/AGENTS.md) — risk assessment and tier mapping
+- [router/](router/AGENTS.md) — router facade, context building, L3 memory, idea capture
+- [sessions/](sessions/AGENTS.md) — session lifecycle, state, approval mode binding
+- [tasks/](tasks/AGENTS.md) — task graph, board, markdown, git sync, context assembly
+- [toolintent/](toolintent/AGENTS.md) — plane-2 tool-call intent validation and workspace policy
+- [tools/](tools/AGENTS.md) — tool contract, registry, executor, output compression
+- [transitions/](transitions/AGENTS.md) — FSM/workflow graph, stage execution, cycle detection
+- [validation/](validation/AGENTS.md) — layered validation pipeline: graph, semantic, session, JSON schema

core/approvals/AGENTS.md

@@ -0,0 +1,36 @@
+# core/approvals — AGENTS.md
+
+## Purpose
+
+Approval gate logic: evaluates tool-execution requests against active grants and session approval mode, records decisions as events, and exposes an engine interface for the kernel to query.
+
+## Ownership
+
+CORREX kernel team. Changes to approval semantics must be validated against `testing/approvals/`.
+
+## Local Contracts
+
+- `ApprovalEngine` — primary interface; `DefaultApprovalEngine` evaluates `DomainApprovalRequest` against `ApprovalState`.
+- `NoOpApprovalEngine` — always grants; used in test/replay contexts.
+- `ApprovalState` rebuilt from events via `ApprovalReducer` + `ApprovalProjector`.
+- `ApprovalGrant` holds scope identity (`ApprovalScopeIdentity`), mode, and expiry. Grants are recorded as events in `core:events` (`ApprovalEvents.kt`).
+- Hard Invariant #4 applies: approvals cannot override policy denial. Policy failure is terminal.
+
+## Work Guidance
+
+- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
+- `DefaultApprovalReducer` only does `state.copy(...)`. No grant-evaluation logic in the reducer.
+- Grant evaluation lives in `DefaultApprovalEngine`, not in the reducer or projector.
+- `ApprovalContext` carries per-request context; `ApprovalDecision` is a sealed result type.
+
+## Verification
+
+```bash
+./gradlew :core:approvals:test --rerun-tasks
+```
+
+Extended tests in `testing/approvals/`: edge cases, fuzz, grant security, tier immutability.
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/artifacts-store/AGENTS.md

@@ -0,0 +1,29 @@
+# core/artifacts-store — AGENTS.md
+
+## Purpose
+
+Thin persistence interface (`ArtifactStore`) for artifact blobs. Decouples the artifact domain model from the storage adapter so `infrastructure/` can supply the real implementation.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `ArtifactStore` — single interface; implementations live in `infrastructure/`.
+- No domain logic here. No event sourcing stack — this is a raw store abstraction, not a projection.
+
+## Work Guidance
+
+- Keep this module minimal. Any new method on `ArtifactStore` must have a corresponding implementation in every adapter under `infrastructure/`.
+- Do not add domain types here; those belong in `core:artifacts`.
+
+## Verification
+
+```bash
+./gradlew :core:artifacts-store:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/artifacts/AGENTS.md

@@ -0,0 +1,37 @@
+# core/artifacts — AGENTS.md
+
+## Purpose
+
+Structured output model for workflow artifacts: defines artifact kinds, tracks lineage and relationships between artifacts, and provides the projector/reducer/repository stack for artifact state.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `Artifact` — core domain type, carries `ArtifactKind`, payload, and metadata.
+- `ArtifactKind` / `ArtifactKindRegistry` — extensible registry; built-in kinds: `ConfigArtifactKind`, `FileWrittenKind`, `ProcessResultKind`.
+- `ArtifactLineage` / `ArtifactRelationship` / `ArtifactRelationshipType` — DAG of artifact provenance.
+- `ArtifactState` rebuilt from events via `DefaultArtifactReducer` (in `core:events` `ArtifactEvents.kt`) + `ArtifactProjector`.
+- `TypedArtifactSlot<T>` — typed accessor for well-known artifact slots.
+- `ArtifactSerializationModule` — registers artifact polymorphic types; must be included in serialization setup.
+- Hard Invariant #1: artifact state is always rebuilt from events. `ArtifactRepository` wraps `EventReplayer<ArtifactState>`.
+
+## Work Guidance
+
+- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
+- New artifact kinds must be registered in `ArtifactKindRegistry` and their payloads in `ArtifactSerializationModule`.
+- `JsonSchema` is a local utility for schema representation; do not reach into external schema libraries.
+
+## Verification
+
+```bash
+./gradlew :core:artifacts:test --rerun-tasks
+```
+
+Reducer tests in `testing/projections/ArtifactReducerTest.kt`.
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/config/AGENTS.md

@@ -0,0 +1,35 @@
+# core/config — AGENTS.md
+
+## Purpose
+
+TOML configuration loading and live-reload: defines `CorrexConfig` (the top-level config shape), operator/project profiles, agent instructions, and read/write helpers.
+
+## Ownership
+
+CORREX kernel team. Config schema changes affect all consumers — coordinate with `apps/server` and `apps/cli`.
+
+## Local Contracts
+
+- `CorrexConfig` — top-level `@Serializable` config data class.
+- `ConfigHolder` — mutable live config reference, updated on reload.
+- `ConfigLoader` — reads TOML from disk; `CorrexConfigWriter` writes it back.
+- `EditableConfig` — partial config for live patch operations (used by the TUI config editor).
+- `OperatorProfile` — operator-level persona and behavior settings.
+- `ProjectProfile` / `ProjectProfileLoader` / `ProjectProfileWriter` — project-scoped profile; loaded at session bind time.
+- `AgentInstructions` / `AgentInstructionsLoader` — per-role prompt fragments loaded from config.
+
+## Work Guidance
+
+- Config is read from disk; it is not event-sourced. Do not add event/state/reducer structures here.
+- `ConfigHolder` is the shared mutable reference injected into consumers. Never read the file directly in domain code — always go through `ConfigHolder`.
+- `CorrexConfigWriter` regenerates TOML from the in-memory model; round-tripping loses comments by design.
+
+## Verification
+
+```bash
+./gradlew :core:config:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/context/AGENTS.md

@@ -0,0 +1,39 @@
+# core/context — AGENTS.md
+
+## Purpose
+
+Context synthesis, compression, and token budgeting: assembles a `ContextPack` from layered `ContextEntry` records, applies compression strategies to fit token budgets, and tracks context state via the standard event-sourcing stack.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `ContextPack` / `ContextPackBuilder` (`DefaultContextPackBuilder`) — assembles ordered context entries for an inference call.
+- `ContextEntry` — single context item with a `ContextLayer` ordinal for ordering.
+- `ContextLayer` — enum defining layer priority (system, L0–L3, etc.). All SYSTEM-role entries fold into the leading system message; non-system entries order by `ContextEntry.ordinal`.
+- `ContextCompressor` (`DefaultContextCompressor`) — applies `CompressionStrategy` to reduce context size within `TokenBudget`.
+- `CompressionMetadata` — records what was compressed and why (non-authoritative; does not replace original events — Hard Invariant #6).
+- `ContextState` rebuilt from events via `DefaultContextReducer` + `ContextProjector`.
+- `DefaultContextRepository` wraps `EventReplayer<ContextState>`.
+- `DecisionPointBuilder` — constructs context snapshots at decision boundaries.
+- `ContextSerializationModule` — registers context types for serialization.
+
+## Work Guidance
+
+- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
+- Compression output is informational only (Hard Invariant #6). Never replace event-sourced context with a compressed snapshot.
+- `DefaultContextReducer` only does `state.copy(...)`.
+
+## Verification
+
+```bash
+./gradlew :core:context:test --rerun-tasks
+```
+
+Tests in `testing/projections/` (ContextProjectorTest, DefaultContextReducerTest, DefaultContextPackBuilderTest) and `testing/deterministic/` (ContextCompressionDeterminismTest, PromptRendererOrderingTest).
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/critique/AGENTS.md

@@ -0,0 +1,31 @@
+# core/critique — AGENTS.md
+
+## Purpose
+
+Critic calibration tracking: projects critic outcome history into `CriticCalibrationState` so the kernel can adapt critic weighting over time.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `CriticCalibrationState` — accumulated calibration data rebuilt from `CritiqueCalibrationEvents` (defined in `core:events`).
+- `CriticCalibrationReducer` / `DefaultCriticCalibrationReducer` — standard reducer, only `state.copy(...)`.
+- `CriticCalibrationProjector` — wraps the reducer as `Projection<CriticCalibrationState>`.
+- No repository class here; callers use `EventReplayer<CriticCalibrationState>` directly or wire their own.
+
+## Work Guidance
+
+- Follow the standard Events→State→Reducer→Projector pattern (see `core/AGENTS.md`).
+- No promotion logic in this module — calibration data is read by `core:kernel`; decisions are made there.
+
+## Verification
+
+```bash
+./gradlew :core:critique:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/events/AGENTS.md

@@ -0,0 +1,43 @@
+# core/events — AGENTS.md
+
+## Purpose
+
+Foundational event-sourcing infrastructure: all `EventPayload` definitions for every domain, the serialization registry, the `EventStore` interface, the `EventReplayer` contract, and shared identity/vocabulary types used across the entire `core/` layer.
+
+## Ownership
+
+CORREX kernel team. This is the most cross-cutting module in the codebase — changes here can break every other module. Coordinate before adding or renaming event types.
+
+## Local Contracts
+
+- `EventPayload` — sealed interface that every domain event implements.
+- `StoredEvent` / `EventEnvelope` / `EventMetadata` — envelope types wrapping payloads for storage and replay.
+- `EventStore` — interface for appending and querying events. Implementations in `infrastructure/`.
+- `EventReplayer<S>` / `DefaultEventReplayer<S>` — replays a filtered event stream through a `Projection<S>` to rebuild state.
+- `Projection<S>` — interface: `initial(): S` + `apply(state, event): S`.
+- `StateBuilder` / `DefaultStateBuilder` — convenience builder over `EventReplayer`.
+- `Serialization.kt` — the `eventModule` polymorphic block. **Every new `EventPayload` subclass must be registered here.** Missing registration = silent deserialization failure.
+- `JsonEventSerializer` / `EventSerializer` — serialize/deserialize `StoredEvent` to JSON.
+- `EventDispatcher` — broadcasts events to in-process listeners.
+- Domain event files: `ApprovalEvents`, `ArtifactEvents`, `ContextEvents`, `InferenceEvents`, `OrchestrationEvents`, `RouterEvents`, `SessionEvents`, `TaskEvents`, `ToolEvents`, `IntentEvents`, `RiskAssessedEvent`, `JournalCompactedEvent`, and many more — all payload definitions live here.
+- Shared vocabulary: `IdentityTypes` (SessionId, TaskId, etc.), `Tier`, `TokenUsage`, `ToolReceipt`, `ToolRequest`, `RiskLevel`, `RetryPolicy`, `GrantScope`, `GrantLedger`.
+
+## Work Guidance
+
+- **SILENT FAILURE TRAP**: After adding any `EventPayload` subclass, immediately add it to `Serialization.kt` `eventModule` block. Run `./gradlew check` to verify. Tests may pass without it but runtime replay will fail silently.
+- `AnyMapSerializer` — custom serializer for `Map<String, Any?>`; use it for dynamic payloads, don't roll another.
+- Event classes are `@Serializable data class` with no mutable state. No methods beyond data accessors.
+- Do not add domain logic to events. They are records, not actors.
+- `EgressAllowlistProjection` — special projection kept in this module because it is used by both `core:toolintent` and `core:events` consumers; it is a shared cross-cutting projection.
+
+## Verification
+
+```bash
+./gradlew :core:events:test --rerun-tasks
+```
+
+Tests in `testing/contracts/` (EventsTest, EventStoreContractTest) and `testing/replay/` (serialization round-trips, replay integration).
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/inference/AGENTS.md

@@ -0,0 +1,46 @@
+# core/inference — AGENTS.md
+
+## Purpose
+
+Provider abstraction and routing for LLM inference: defines `InferenceProvider`, `InferenceRouter`, prompt rendering, embedder/tokenizer contracts, and the projection stack for tracking inference history.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `InferenceProvider` — interface for making inference calls. Implementations in `infrastructure/` (llama.cpp, remote providers).
+- `InferenceRouter` / `DefaultInferenceRouter` — selects a provider, applies routing policy, caches provider selection.
+- `InferenceRequest` / `InferenceResponse` — request/response types. `ResponseFormat` controls output structure.
+- `GenerationConfig` — sampling parameters.
+- `ModelCapability` — capability flags per model (e.g. tool-use, function-calling).
+- `PromptRenderer` — renders a `ContextPack` into the provider's prompt format. All SYSTEM-role entries fold into the leading system message; ordering by `ContextEntry.ordinal` for non-system entries.
+- `Embedder` / `NoopEmbedder` — vector embedding interface; `NoopEmbedder` for contexts without embedding support.
+- `Tokenizer` — token counting interface; implementations in `infrastructure/`.
+- `InferenceState` rebuilt from `InferenceEvents` via `DefaultInferenceReducer` + `InferenceProjector`.
+- `InferenceRepository` wraps `EventReplayer<InferenceState>`.
+- `InferenceCancellationToken` / `CancellationReason` — cooperative cancellation model.
+- `ProviderHealth` — health status reported by a provider.
+- `ToolDefinition` / `ToolCallRequest` — types for tool-use in inference requests.
+- Hard Invariant #7: LLM outputs are untrusted until validated by `core:validation`.
+- Hard Invariant #8: Replay uses `ReplayInferenceProvider` in `core:kernel` — no live LLM calls during replay.
+
+## Work Guidance
+
+- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
+- `DefaultInferenceReducer` only does `state.copy(...)`.
+- Never call a live provider from within this module's domain logic. Provider instantiation is in `infrastructure/`.
+- `ModelLoadException` — thrown when a required model is unavailable. Callers must handle this as a terminal condition for the operation.
+
+## Verification
+
+```bash
+./gradlew :core:inference:test --rerun-tasks
+```
+
+Tests in `testing/contracts/` (InferenceProviderContractTest, DefaultInferenceRouterTest) and `testing/projections/` (InferenceProjectorTest, InferenceReducerTest) and `testing/deterministic/` (PromptRendererOrderingTest).
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/journal/AGENTS.md

@@ -0,0 +1,35 @@
+# core/journal — AGENTS.md
+
+## Purpose
+
+Decision journal: projects orchestration events into a structured `DecisionJournalState` (a chronological log of `DecisionRecord`s), renders it for human review, and provides a `ProjectMemoryDistiller` that condenses journal entries into cross-session memory.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `DecisionRecord` — single journal entry: decision point, rationale, outcome.
+- `DecisionJournalState` rebuilt from `JournalCompactedEvent` and orchestration events via `DefaultDecisionJournalReducer` + `DecisionJournalProjector`.
+- `DefaultDecisionJournalRepository` wraps `EventReplayer<DecisionJournalState>`.
+- `DecisionJournalRenderer` — formats `DecisionJournalState` as human-readable text for context injection or export.
+- `ProjectMemoryDistiller` — produces a condensed memory summary from journal state; output is non-authoritative (Hard Invariant #6 applies — compressed output must not replace original events).
+
+## Work Guidance
+
+- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
+- `DefaultDecisionJournalReducer` only does `state.copy(...)`.
+- Distilled memory is a derived view; the event log remains the source of truth.
+
+## Verification
+
+```bash
+./gradlew :core:journal:test --rerun-tasks
+```
+
+Tests in `testing/projections/` (DecisionJournalProjectorTest) and `testing/replay/` (DecisionJournalReplayTest).
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/kernel/AGENTS.md

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

core/risk/AGENTS.md

@@ -0,0 +1,32 @@
+# core/risk — AGENTS.md
+
+## Purpose
+
+Risk assessment for tool calls and workflow operations: maps tool execution tiers to risk levels and evaluates `RiskContext` to produce a `RiskSummary`.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `RiskAssessor` — interface; `DefaultRiskAssessor` applies `TierMapping` to produce `RiskSummary`. `NoOpRiskAssessor` always returns clean (used in test contexts).
+- `RiskContext` — input to assessment: tool identity, parameters, session context.
+- `TierMapping` — maps `Tier` values (from `core:events`) to `RiskLevel`. Tier levels are the canonical risk signal — do not invent secondary risk signals here.
+- `RiskSummary` / `RiskAction` / `RiskLevel` / `RiskSignal` — vocabulary types (defined in `core:events`; referenced here).
+- Hard Invariant #5: all tools declare execution tier; tier drives risk level. Risk assessment is not optional.
+
+## Work Guidance
+
+- `DefaultRiskAssessor` is stateless — no event sourcing needed here.
+- Do not add approval logic here; that belongs in `core:approvals`. Risk assessment produces a summary; approval evaluation consumes it.
+
+## Verification
+
+```bash
+./gradlew :core:risk:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/router/AGENTS.md

@@ -0,0 +1,43 @@
+# core/router — AGENTS.md
+
+## Purpose
+
+Router facade and context assembly: builds the context pack delivered to each inference call, manages L3 cross-session memory retrieval, captures ideas from rubber-ducking sessions, and exposes `RouterFacade` as the primary entry point for the routing pipeline.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `RouterFacade` — primary entry point; orchestrates `RouterContextBuilder`, L3 retrieval, and narration trigger evaluation.
+- `RouterContextBuilder` — assembles `ContextPack` from active session state, L3 memory hits, repo knowledge, ideas, and steering entries.
+- `RouterState` rebuilt from `RouterEvents` via `RouterReducer` + `RouterProjector`.
+- `RouterRepository` wraps `EventReplayer<RouterState>`.
+- `RouterResponse` — output from `RouterFacade`: rendered context + routing metadata.
+- `RouterConfig` — per-session router configuration (narration mode, L3 enabled, etc.).
+- `L3MemoryStore` / `RehydratableL3MemoryStore` / `InMemoryL3MemoryStore` — L3 cross-session memory interfaces. `RehydratableL3MemoryStore` uses `L3MetadataRehydrator` to restore from recorded events (Hard Invariant #9: L3 queries are recorded as events; replay reads the recorded hits, not the live index).
+- `L3Hit` / `L3MemoryEntry` / `L3Query` — L3 retrieval types.
+- `IdeaReader` / `Idea` / `Ideas` — reads `IdeaCaptured`/`IdeaDiscarded` events to surface idea state as a context feed.
+- `WorkflowProposals` / `WorkflowSummary` — proposal types for the workflow-propose panel.
+- `NarrationTrigger` — evaluates whether narration should be emitted on this turn.
+- Hard Invariant #9: L3 retrieval queries are recorded as events at query time. During replay, `L3MetadataRehydrator` restores the recorded hits — the live ANN index is never queried.
+
+## Work Guidance
+
+- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
+- `RouterReducer` only does `state.copy(...)`.
+- L3 memory is non-deterministic at query time (ANN search). Always record the hits as events immediately and read those recorded events in all downstream/replay paths.
+- `InMemoryL3MemoryStore` is for tests only; production wiring uses `RehydratableL3MemoryStore`.
+
+## Verification
+
+```bash
+./gradlew :core:router:test --rerun-tasks
+```
+
+Tests in `testing/deterministic/` (RouterContextBuilderTest, RouterFacadeTest, RouterNarrationTest, RouterProjectorTest, L3MetadataRehydratorTest).
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/sessions/AGENTS.md

@@ -0,0 +1,39 @@
+# core/sessions — AGENTS.md
+
+## Purpose
+
+Session lifecycle management: defines session state, status transitions, approval mode, bound profile/workspace, and the projector/reducer/repository stack for tracking active and historical sessions.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `Session` — core session domain type with id, status, bound profile and workspace.
+- `SessionState` rebuilt from `SessionEvents` via `DefaultSessionReducer` + `SessionProjector`.
+- `DefaultSessionRepository` wraps `EventReplayer<SessionState>`.
+- `SessionStatus` — enum of lifecycle states (e.g. PENDING, RUNNING, COMPLETE, FAILED).
+- `ApprovalMode` — per-session approval policy binding (AUTO, MANUAL, etc.).
+- `BoundAgentInstructions` / `BoundProfile` / `BoundProjectProfile` / `BoundWorkspace` — types capturing what was bound to the session at launch time; these are immutable once set.
+- `SessionSummary` / `SessionSummaryProjector` — lightweight projection for listing sessions without full state replay.
+- `SessionCounterProjection` / `SessionCounterState` — cross-session counter projection.
+- `TransitionResult` — outcome type for session state transitions.
+
+## Work Guidance
+
+- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
+- `DefaultSessionReducer` only does `state.copy(...)`. No lifecycle decision logic in the reducer.
+- Bound types (`BoundProfile`, `BoundWorkspace`, etc.) are immutable once written to the event log. Do not mutate them post-bind.
+
+## Verification
+
+```bash
+./gradlew :core:sessions:test --rerun-tasks
+```
+
+Tests in `testing/projections/` (DefaultSessionReducerTest) and `testing/replay/` (SessionReplayTest, SessionEmptyReplayTest).
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/tasks/AGENTS.md

@@ -0,0 +1,45 @@
+# core/tasks — AGENTS.md
+
+## Purpose
+
+Task graph management: defines tasks, their status, links, notes, and history; projects task state from events; assembles task context bundles for inference; syncs with git commit history; and provides search and retrieval over the task board.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `Task` / `TaskState` / `TaskStatus` / `TaskLink` / `TaskNote` — core task domain types.
+- `TaskReducer` / `DefaultTaskReducer` — standard reducer over `TaskEvents` (from `core:events`).
+- `TaskBoardProjector` — projects all tasks into `TaskBoard` (the full board view).
+- `DefaultTaskRepository` wraps `EventReplayer<TaskState>`.
+- `TaskGraph` — dependency/link graph over tasks; surfaces ready/blocked status.
+- `TaskBoard` — aggregated view: all tasks + graph relationships.
+- `TaskHistory` — event history for a single task.
+- `TaskMarkdown` — renders task state as Markdown for context injection.
+- `TaskContextAssembler` / `TaskContextBundle` — assembles task-related context for an inference call.
+- `TaskSearch` — keyword/status search over `TaskBoard`.
+- `TaskService` — application-layer facade for task operations (create, update, transition).
+- `TaskStreams` — streaming task updates for WS consumers.
+- `TaskKnowledgeRetriever` — retrieves task-related knowledge for L3 context.
+- `GitTaskSync` / `CommitTaskParser` — syncs tasks from git commit history.
+- `TaskArtifactResolver` / `TaskDocumentResolver` / `TaskSessionResolver` — resolvers for task-linked artifacts, documents, and sessions.
+- `TaskTargetKinds` / `TaskCounterProjection` / `TaskCounterState` — supporting types.
+
+## Work Guidance
+
+- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
+- `DefaultTaskReducer` only does `state.copy(...)`.
+- `TaskGraph` is a derived structure — always rebuild from `TaskBoard`, never persist it independently (Hard Invariant #1).
+- `GitTaskSync` reads git history; its observations must be recorded as events (Hard Invariant #9). Do not re-read git history during replay.
+
+## Verification
+
+```bash
+./gradlew :core:tasks:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/toolintent/AGENTS.md

@@ -0,0 +1,45 @@
+# core/toolintent — AGENTS.md
+
+## Purpose
+
+Plane-2 tool-call intent validation: evaluates proposed tool calls against workspace policy rules before execution, records the assessment as an event, and provides `WorldProbe` for recording environment observations needed by rules.
+
+## Ownership
+
+CORREX kernel team. This module enforces Hard Invariant #9 for the tool-call path.
+
+## Local Contracts
+
+- `ToolCallAssessor` — evaluates a proposed tool call against all active `ToolCallRule`s; returns a `ToolCallAssessmentRecord`.
+- `ToolCallRule` — interface for a single validation rule. Built-in rules:
+  - `PathContainmentRule` — tool must write within the workspace root.
+  - `ReadBeforeWriteRule` — file must be read before being overwritten.
+  - `StaleWriteRule` — detects write to a file that has changed on disk since last read.
+  - `NetworkHostRule` — egress must be on the allowlist.
+  - `ManifestContainmentRule` — write target must appear in the write manifest.
+  - `WriteScopeRule` — enforces declared write scope.
+  - `ReferenceExistsRule` — referenced entities must exist.
+  - `ExecInterpreterRule` — interpreter must be in the allowed list.
+  - `CycleExitRule` (in `core:validation`) — imported separately; not defined here.
+- `WorkspacePolicy` — aggregates rules and configuration for a workspace.
+- `WorldProbe` — performs environment checks (filesystem, network) and records the observations as events immediately (Hard Invariant #9). Never call `WorldProbe` during replay.
+- `EgressAllowlist` — current egress allowlist; rebuilt from `EgressAllowlistProjection` (in `core:events`).
+- `ParamValueExtractor` — extracts typed parameter values from tool call arguments.
+- `RiskMapping` — maps rule violations to risk levels for `core:risk`.
+- `SessionContext` — session-scoped context passed to rules during evaluation.
+
+## Work Guidance
+
+- Hard Invariant #9: all `WorldProbe` calls record observations as events. Replay reads those recorded events — it must not call `WorldProbe` again.
+- Hard Invariant #5: every tool call must be assessed before execution. Assessment result is recorded as `ToolCallAssessmentEvents` in `core:events`.
+- New rules implement `ToolCallRule` and are registered in `WorkspacePolicy`. Do not add rule logic directly to `ToolCallAssessor`.
+
+## Verification
+
+```bash
+./gradlew :core:toolintent:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/tools/AGENTS.md

@@ -0,0 +1,43 @@
+# core/tools — AGENTS.md
+
+## Purpose
+
+Tool contract, registry, executor, and receipt tracking: defines the `Tool` interface, manages tool registration, executes tools within their declared tier, compresses tool output, and projects tool invocation history via the standard event-sourcing stack.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `Tool` — primary interface all tools implement. Must declare `Tier` (from `core:events`).
+- `ToolRegistry` — holds all registered tools for a session; looked up by name.
+- `ToolExecutor` — executes a `Tool` given a `ToolRequest`, records `ToolEvents` in `core:events`.
+- `ToolResult` — sealed result type: success with output, or failure with error.
+- `ToolState` rebuilt from `ToolEvents` via `DefaultToolReducer` + `ToolProjector`.
+- `DefaultToolRepository` wraps `EventReplayer<ToolState>`.
+- `ToolInvocationRecord` / `ToolInvocationStatus` / `ToolCallAssessmentRecord` — history types.
+- `FileMutationRecord` — records file-affecting side effects.
+- `FileAffectingTool` — extended `Tool` interface for tools that write files; must declare `affectedPaths`.
+- `OutputCompressionSpec` / `ToolOutputCompressor` / `DeclarativeCompressor` — compress large tool outputs to fit token budgets (Hard Invariant #6: compressed output is informational; original events are preserved).
+- `ParamRole` — annotates tool parameter semantic roles (input path, output path, etc.).
+- `ValidationResult` — result from tool-level parameter validation (pre-execution check).
+- Hard Invariant #5: all tool side effects are captured in events. Silent execution is not allowed.
+
+## Work Guidance
+
+- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
+- `DefaultToolReducer` only does `state.copy(...)`.
+- `ToolExecutor` must record a `ToolExecutedEvent` (or equivalent) before returning, even on failure.
+- Output compression must not discard the original event — only produce a derived summary alongside it.
+- New tools implement `Tool` (or `FileAffectingTool`) and register in `ToolRegistry`. Do not instantiate tools inside `ToolExecutor`.
+
+## Verification
+
+```bash
+./gradlew :core:tools:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

core/transitions/AGENTS.md

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

core/validation/AGENTS.md

@@ -0,0 +1,48 @@
+# core/validation — AGENTS.md
+
+## Purpose
+
+Layered validation pipeline: validates workflow graphs (structure, cycles, reachability), session state, semantic rules, JSON schema conformance, and artifact payloads before any state-mutating operation proceeds.
+
+## Ownership
+
+CORREX kernel team. Hard Invariant #7 applies here: LLM outputs are untrusted until this pipeline approves them.
+
+## Local Contracts
+
+- `ValidationPipeline` — top-level entry point; runs all registered validators in sequence and collects `ValidationReport`.
+- `Validator` — interface for a single validator. Returns `ValidationOutcome` (pass/warn/fail) with `ValidationIssue` list.
+- Built-in validators:
+  - `GraphValidator` — validates `WorkflowGraph`: reachability, cycle detection (via `core:transitions` `CycleExtractor`), missing tool references.
+  - `SemanticValidator` — applies `SemanticRule`s to workflow/stage definitions.
+  - `SessionValidator` — validates session preconditions before launch.
+  - `TransitionValidator` — validates transition edge definitions.
+  - `ArtifactPayloadValidator` — validates artifact payloads against `JsonSchema`.
+  - `JsonSchemaValidator` — JSON schema conformance check.
+  - `SceneValidator` — validates scene definitions.
+- `ValidationReport` / `ValidationIssue` / `ValidationOutcome` / `ValidationSeverity` / `ValidationSection` / `ValidationLocation` — report structure types.
+- `ValidationContext` — context passed to all validators (session, graph, config).
+- `ValidationRiskStats` — risk statistics derived from validation results, consumed by `core:risk`.
+- `ApprovalRequest` / `ApprovalTrigger` — approval-related types used during validation-triggered approval flows.
+- `CyclePolicy` / `CyclePolicyBinding` / `CycleSignature` / `CycleSignatureFactory` / `CycleExitRule` — cycle policy enforcement: detects recurring cycle patterns and applies policy (warn/fail/allow).
+- `RiskSummary` — local re-export of risk summary type used in validation output.
+- `MissingToolRule` / `SemanticRule` — built-in semantic rule implementations.
+
+## Work Guidance
+
+- Add new validators by implementing `Validator` and registering in `ValidationPipeline`. Do not add validation logic directly to `SessionOrchestrator` or other callers.
+- `ValidationPipeline` must be run before any inference call processes its output (Hard Invariant #7).
+- `CyclePolicy` is the mechanism for allowing controlled cycles in workflows; do not bypass it.
+- `GraphValidator` calls `CycleExtractor` from `core:transitions` — this is the one legitimate cross-core reference; it is structural, not domain logic.
+
+## Verification
+
+```bash
+./gradlew :core:validation:test --rerun-tasks
+```
+
+Tests in `testing/deterministic/` (GraphValidatorTest) and `testing/contracts/` (ContextSnapshotTest).
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).