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.

AGENTS.md

@@ -0,0 +1,94 @@
+# DOX framework
+
+- DOX is highly performant AGENTS.md hierarchy installed here
+- Agent must follow DOX instructions across any edits
+
+## Core Contract
+
+- AGENTS.md files are binding work contracts for their subtrees
+- Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable AGENTS.md plus every parent AGENTS.md above it
+
+## Read Before Editing
+
+1. Read the root AGENTS.md
+2. Identify every file or folder you expect to touch
+3. Walk from the repository root to each target path
+4. Read every AGENTS.md found along each route
+5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there
+6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules
+7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX
+
+Do not rely on memory. Re-read the applicable DOX chain in the current session before editing.
+
+## Update After Editing
+
+Every meaningful change requires a DOX pass before the task is done.
+
+Update the closest owning AGENTS.md when a change affects:
+
+- purpose, scope, ownership, or responsibilities
+- durable structure, contracts, workflows, or operating rules
+- required inputs, outputs, permissions, constraints, side effects, or artifacts
+- user preferences about behavior, communication, process, organization, or quality
+- AGENTS.md creation, deletion, move, rename, or index contents
+
+Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the DOX pass still must happen.
+
+## Hierarchy
+
+- Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index
+- Child AGENTS.md files own domain-specific instructions and their own Child DOX Index
+- Each parent explains what its direct children cover and what stays owned by the parent
+- The closer a doc is to the work, the more specific and practical it must be
+
+## Child Doc Shape
+
+- Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards
+- Work Guidance must reflect the current standards of the project or user instructions; if there are no specific standards or instructions yet, leave it empty
+- Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists
+
+Default section order:
+- Purpose
+- Ownership
+- Local Contracts
+- Work Guidance
+- Verification
+- Child DOX Index
+
+## Style
+
+- Keep docs concise, current, and operational
+- Document stable contracts, not diary entries
+- Put broad rules in parent docs and concrete details in child docs
+- Prefer direct bullets with explicit names
+- Do not duplicate rules across many files unless each scope needs a local version
+- Delete stale notes instead of explaining history
+- Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist
+
+## Closeout
+
+1. Re-check changed paths against the DOX chain
+2. Update nearest owning docs and any affected parents or children
+3. Refresh every affected Child DOX Index
+4. Remove stale or contradictory text
+5. Run existing verification when relevant
+6. Report any docs intentionally left unchanged and why
+
+## User Preferences
+
+When the user requests a durable behavior change, record it here or in the relevant child AGENTS.md
+
+## Child DOX Index
+
+Each entry below has its own `AGENTS.md` (the DOX rail for that subtree) with a further Child DOX Index for its modules. Read the relevant chain before editing under it.
+
+- core/ — pure domain logic: event sourcing, session orchestration, inference routing, tool management, workflow graph execution, and all supporting domain services
+- infrastructure/ — real-world adapters (SQLite event store, llama.cpp inference, TurboVec L3 memory, shell/web/filesystem tools, TOML workflow loader) wired via InfrastructureModule
+- apps/ — entry-point applications (CLI, server, terminal UI, and two stub modules) that wire core and infrastructure into runnable processes
+- testing/ — dedicated test submodules (approvals, contracts, determinism, integration, kernel, projections, replay, transitions) that verify production core/* modules; not co-located with production code
+- docs/ — architecture docs, ADRs, QA run plans, specs, and schemas; docs/plans + docs/future are gitignored and stale
+- examples/ — runnable TOML workflow definitions and prompt files demonstrating kernel features
+- frontend/ — early-stage React/TS web UI connecting to the Ktor server; secondary surface to the TUI
+- interfaces/ — reserved, currently empty; future home for cross-module interface contracts
+- plugins/ — reserved, currently empty; future home for plugin descriptors outside the Gradle tree
+- scripts/ — developer helper scripts: context lookup, epic status, healthcheck, task scaffolding

apps/AGENTS.md

@@ -0,0 +1,31 @@
+# apps/
+
+## Purpose
+
+Entry-point applications that compose core modules into runnable processes. Each app wires infrastructure and core together; no business logic lives here.
+
+## Ownership
+
+All apps in this subtree. Dependency rule: `apps → core → infrastructure`. Apps may not import sibling app modules.
+
+## Local Contracts
+
+- Apps depend on `core:*` and `infrastructure:*` only — never on each other.
+- Configuration loading, process lifecycle, and entrypoint wiring live here.
+- No domain logic in apps; delegate to core services.
+
+## Work Guidance
+
+Follow the Kotlin rules and anti-patterns in the root CLAUDE.md for all JVM apps. `apps/tui-go` is a separate Go module — see its own AGENTS.md.
+
+## Verification
+
+Each app has its own verification command. See child AGENTS.md.
+
+## Child DOX Index
+
+- `apps/cli` — Clikt CLI; sends commands to `apps/server` over HTTP + WebSocket
+- `apps/desktop` — stub module, not yet implemented
+- `apps/server` — Ktor HTTP API + WebSocket server; orchestrates core kernel
+- `apps/tui-go` — Go/Bubble Tea terminal UI; WebSocket client of `apps/server`
+- `apps/worker` — stub module, not yet implemented

apps/cli/AGENTS.md

@@ -0,0 +1,30 @@
+# apps/cli
+
+## Purpose
+
+Clikt-based command-line interface. Translates user commands into HTTP requests and WebSocket connections against `apps/server`.
+
+## Ownership
+
+All sources under `apps/cli/src/`.
+
+## Local Contracts
+
+- Commands: `session`, `run`, `task`, `provider`, `approve`, `undo`, `events`, `status`, `replay`, `stats`, `health`
+- Communicates with server via HTTP REST and WebSocket (`CliWsClient`)
+- No business logic; all orchestration is delegated to the server
+
+## Work Guidance
+
+- Follow Kotlin rules in root CLAUDE.md (runCatching, suspend, no blocking I/O on main thread)
+- New commands go under `commands/`, follow the existing Clikt subcommand pattern
+
+## Verification
+
+```
+./gradlew :apps:cli:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

apps/desktop/AGENTS.md

@@ -0,0 +1,27 @@
+# apps/desktop
+
+## Purpose
+
+Stub module reserved for a future desktop GUI application. Not yet implemented.
+
+## Ownership
+
+`apps/desktop/` — currently only a placeholder `Main.kt`.
+
+## Local Contracts
+
+None defined yet.
+
+## Work Guidance
+
+Do not add functionality here until the desktop epic is planned. Follow Kotlin rules in root CLAUDE.md when work begins.
+
+## Verification
+
+```
+./gradlew :apps:desktop:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

apps/server/AGENTS.md

@@ -0,0 +1,45 @@
+# apps/server
+
+## Purpose
+
+Ktor HTTP + WebSocket server. Exposes the orchestration kernel to CLI and TUI clients, manages session lifecycle, and streams events over WebSocket.
+
+## Ownership
+
+All sources under `apps/server/src/`.
+
+## Local Contracts
+
+### HTTP REST routes
+- `GET/POST /sessions` — session browse and start
+- `POST /sessions/{id}/resume` — resume a session after restart
+- `GET/POST /tasks` — task listing and management
+- `GET/POST /providers` — provider configuration
+- `GET/POST /workflows` — workflow management
+- `GET /health` — health report (probes: event-store, llama-server, disk watermark)
+- `GET /stats` — metrics report (MetricsProjection)
+
+### WebSocket protocol (`/ws`)
+- **ServerMessage** (server → client): sealed hierarchy — `SessionMessage` (event-derived, carries `sequence` + `sessionSequence`) and `NonEventMessage` (control/infra). Variants include session lifecycle, approval requests, clarification requests, narration, proposed workflows, health/metrics pushes.
+- **ClientMessage** (client → server): `StartSession`, `ApproveToolCall`, `RejectToolCall`, `GrantApproval`, `AnswerClarification`, `SetChatMode`, and others.
+- All protocol types are in `protocol/` (Dtos.kt, ServerMessage.kt, ClientMessage.kt, ProtocolSerializer.kt).
+
+### Health monitoring
+- `HealthMonitor` runs probes on a schedule; results folded via `HealthProjection` into `HealthState`.
+- Adding a probe: implement `HealthProbe`, register in `ServerModule`.
+
+## Work Guidance
+
+- Follow Kotlin rules in root CLAUDE.md.
+- Route handlers must not contain domain logic — delegate to core services injected via `ServerModule`.
+- New WS message variants require updating both `ServerMessage`/`ClientMessage` sealed classes and `ProtocolSerializer`.
+
+## Verification
+
+```
+./gradlew :apps:server:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

apps/tui-go/AGENTS.md

@@ -0,0 +1,37 @@
+# apps/tui-go
+
+## Purpose
+
+Terminal UI for correx. A Go/Bubble Tea application that connects to `apps/server` over WebSocket and renders session state in a "Soft + blue" visual style.
+
+## Ownership
+
+All sources under `apps/tui-go/`. Separate Go module (`github.com/correx/tui-go`) — independent build and test toolchain from the Gradle/Kotlin apps.
+
+## Local Contracts
+
+- Connects to `apps/server` at the configured WebSocket endpoint; does not import any Kotlin/JVM code.
+- **Receives** `ServerMessage` JSON over WebSocket (session lifecycle, approval requests, clarification requests, narration, proposed workflows, health/metrics).
+- **Sends** `ClientMessage` JSON (StartSession, ApproveToolCall, RejectToolCall, AnswerClarification, SetChatMode, etc.).
+- Protocol types are mirrored in `internal/protocol/` — must stay in sync with `apps/server/src/.../protocol/`.
+- Visual theme: "Soft + blue" (see `internal/app/theme.go`). Reference design lives in `docs/visual/ref/`.
+- Key layout defined in `internal/app/key.go`.
+- Main model in `internal/app/model.go`; update loop in `internal/app/update.go`; rendering in `internal/app/view.go`.
+- Overlays (sessions, tasks, config, ideas) in `internal/app/overlays.go` and sibling files.
+
+## Work Guidance
+
+- Standard Go conventions: `gofmt`-formatted, exported names for cross-package types, unexported for internal.
+- Add new WS message handling in `internal/ws/client.go` → dispatch via Bubble Tea `Msg` types → handled in `update.go`.
+- New UI panels follow the existing card/overlay pattern (see `clarcard.go`, `proposecard.go`).
+- Keep theme constants in `theme.go`; do not hardcode colors elsewhere.
+
+## Verification
+
+```bash
+cd apps/tui-go && go build ./... && go test ./...
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

apps/worker/AGENTS.md

@@ -0,0 +1,27 @@
+# apps/worker
+
+## Purpose
+
+Stub module reserved for a future background worker process. Not yet implemented.
+
+## Ownership
+
+`apps/worker/` — currently only a placeholder `Main.kt`.
+
+## Local Contracts
+
+None defined yet.
+
+## Work Guidance
+
+Do not add functionality here until the worker epic is planned. Follow Kotlin rules in root CLAUDE.md when work begins.
+
+## Verification
+
+```
+./gradlew :apps:worker:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

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

docs/AGENTS.md

@@ -0,0 +1,37 @@
+# docs/ — AGENTS.md
+
+## Purpose
+
+Human-readable documentation for the CORREX project: architecture decisions, module specs, QA run plans, schemas, epics, and design references. Not source of truth for build status — source of truth is git log + live code.
+
+## Ownership
+
+Maintained alongside the features they describe. Any agent shipping a significant feature must update or create the relevant doc.
+
+## Local Contracts
+
+- `architecture/` — stable, high-level architectural docs (context layers, event model, replay model, security boundaries).
+- `decisions/` — ADRs (adr-NNNN-*.md). Append-only. Never delete or retroactively alter a decided ADR; write a superseding one instead.
+- `qa/` — QA run plans (QA-*.md). Each maps to a shipped feature. `TEMPLATE.md` is the canonical shape. `ENV.md` describes the required live environment. `README.md` explains the QA process.
+- `specs/` — feature specs by date-slug. Inputs for planned or in-flight work.
+- `schemas/` — canonical JSON schemas for structured outputs (analysis, brief_echo, design, execution_plan, impl_plan). Shared across the router and validator.
+- `epics/`, `modules/`, `diagrams/`, `design/`, `reviews/`, `visual/` — supporting reference material.
+
+**⚠️ STALE / DO NOT TRUST FOR STATUS:**
+- `docs/plans/` — gitignored. Contains old implementation plans. Never reflects current build state.
+- `docs/future/` — gitignored. Speculative, may be outdated. Verify any claim against git log + live code.
+
+## Work Guidance
+
+- QA plans live in `qa/`. Use `qa/TEMPLATE.md` as the starting shape when creating a new one.
+- ADRs go in `decisions/`. Follow the existing numbering sequence.
+- Specs go in `specs/` under a `YYYY-MM-DD-<slug>/` directory.
+- Never trust `docs/plans/` or `docs/future/` for feature status. Always verify against `git log` and live source.
+
+## Verification
+
+_None yet._
+
+## Child DOX Index
+
+No child AGENTS.md (leaf directory).

examples/AGENTS.md

@@ -0,0 +1,32 @@
+# examples/ — AGENTS.md
+
+## Purpose
+
+Reference configurations and workflow definitions that demonstrate how to use CORREX. These are runnable examples, not documentation prose.
+
+## Ownership
+
+Kept in sync with the features they exercise. When a kernel contract changes (tool names, config keys, stage shape), update affected examples.
+
+## Local Contracts
+
+- `workflows/` — TOML workflow definitions (decompose→gather→report, role_pipeline, review_loop, etc.) plus a `prompts/` subdirectory for prompt text files referenced by those workflows. These are the canonical examples for the `[tools.research]` config and freestyle/plan workflows.
+- `configs/` — currently empty; reserved for example `correx.toml` server configs.
+- `plugins/` — currently empty; reserved for example plugin descriptors.
+- `stages/` — currently empty; reserved for example stage definitions.
+
+Each TOML file in `workflows/` is a valid workflow loadable by the server. Keep them working against the current kernel API.
+
+## Work Guidance
+
+- Add a new workflow example when a major new workflow type ships.
+- Prompts referenced by TOML files go in `workflows/prompts/`.
+- Do not add configs/plugins/stages stubs speculatively — populate when there is real content.
+
+## Verification
+
+_None yet._
+
+## Child DOX Index
+
+No child AGENTS.md (leaf directory).

frontend/AGENTS.md

@@ -0,0 +1,34 @@
+# frontend/ — AGENTS.md
+
+## Purpose
+
+Early-stage React/TypeScript web UI for the CORREX server. Connects to the server's REST endpoints and WebSocket feed. Placeholder / exploratory state — not production-hardened.
+
+## Ownership
+
+Loosely maintained. Not on the critical path. The canonical operator UI is `apps/tui-go/` (Go/Bubble Tea TUI). This web UI is a secondary surface.
+
+## Local Contracts
+
+- Stack: React 18, TypeScript, `react-scripts` (Create React App).
+- Entry: `src/App.tsx`.
+- Structure: `src/components/`, `src/routes/`, `src/stores/`, `src/lib/`, `src/websocket/`, `src/visualizations/`.
+- Static assets: `static/`.
+- No backend lives here — all data comes from the Ktor server (`apps/server/`).
+- `docs/visual/ref/` is the canonical JS/TS mockup for look-and-feel reference.
+
+## Work Guidance
+
+- Mirror the WS protocol used by `apps/tui-go/` — both clients consume the same server feed.
+- Do not duplicate business logic here; keep components thin and data-driven.
+- Check `docs/visual/ref/` before designing new UI elements.
+
+## Verification
+
+```bash
+cd frontend && npm run build
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf directory).

infrastructure/AGENTS.md

@@ -0,0 +1,39 @@
+# infrastructure/
+
+## Purpose
+
+Real-world adapters for the correx kernel. Each submodule wires a concrete external system (SQLite, llama.cpp server, TurboVec sidecar, OS shell, SearXNG/web) to the interfaces declared in `core:*`. The root module (`infrastructure/`) contains `InfrastructureModule` — a single factory object that assembles and wires all adapters for use by `apps/*`.
+
+## Ownership
+
+Adapter layer. Depends on `core:*`. No upward dependency on `apps/*` is permitted.
+
+## Local Contracts
+
+- All adapters implement interfaces declared in `core:*` — never invent adapter-specific abstractions visible outside this layer.
+- `InfrastructureModule` is the sole DI assembly point: `apps/*` call its factory functions; they do not instantiate adapters directly.
+- Tool side effects must be captured in events (invariant #5). Adapters must not execute tool side effects silently.
+- Environment observations (filesystem state, network responses, embedder results) must be recorded as events at call time; replay must not re-query the environment (invariants #8, #9).
+- No cross-core imports. Adapters may depend on multiple `core:*` modules but never on sibling `infrastructure:*` modules except through `InfrastructureModule` wiring.
+
+## Work Guidance
+
+- Kotlin error handling: use `runCatching` / sealed domain types; no bare `try-catch`.
+- Blocking I/O goes in `withContext(Dispatchers.IO)`.
+- Imports: verify each is used before finalising a file; remove unused imports.
+
+## Verification
+
+```
+./gradlew :infrastructure:test --rerun-tasks
+./gradlew check
+```
+
+## Child DOX Index
+
+- [artifacts-cas/](artifacts-cas/AGENTS.md) — content-addressable artifact store backed by SQLite index + append-only segment files
+- [inference/](inference/AGENTS.md) — inference provider registry and llama.cpp adapter (model lifecycle, embedder, tokenizer)
+- [persistence/](persistence/AGENTS.md) — SQLite event store and in-memory event store; artifact repository projection
+- [router/](router/AGENTS.md) — L3 memory adapter (TurboVec Python sidecar) for cross-session router memory
+- [tools/](tools/AGENTS.md) — tool registry, sandboxed executor, shell/web/task/filesystem tool implementations
+- [workflow/](workflow/AGENTS.md) — TOML workflow loader, prompt loader, execution plan compiler

infrastructure/artifacts-cas/AGENTS.md

@@ -0,0 +1,33 @@
+# infrastructure/artifacts-cas/
+
+## Purpose
+
+Content-addressable artifact store backed by append-only segment files on disk and a SQLite index. Implements `core:artifacts-store` (`ArtifactStore`). Handles content hashing, segment layout, compaction, eviction, and crash-recovery tail scanning.
+
+## Ownership
+
+Adapter for local filesystem artifact storage. No dependency on other `infrastructure:*` modules at runtime; `infrastructure:persistence` is a test dependency only.
+
+## Local Contracts
+
+- Implements `ArtifactStore` from `core:artifacts-store`.
+- Segment files are append-only; `SegmentWriter`/`SegmentReader` own the on-disk format (`SegmentLayout`).
+- `SqliteArtifactIndex` maintains the content-hash → segment offset index; the SQLite file lives alongside the segments in the configured root dir.
+- `TailScanner` recovers the index after a crash by scanning the tail of the most recent segment.
+- `LivenessScanner` and `Evictor` handle compaction and space reclamation.
+- `CasConfig` is the only configuration surface; pass via `InfrastructureModule.createArtifactStore()`.
+- Environment observations (file existence, segment bytes) happen at call time and must not be re-read during replay — callers must record artifact content as events if replay correctness requires it (invariant #9).
+
+## Work Guidance
+
+Standard adapter rules apply (see parent `AGENTS.md`). No domain logic beyond storage mechanics belongs here.
+
+## Verification
+
+```
+./gradlew :infrastructure:artifacts-cas:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

infrastructure/inference/AGENTS.md

@@ -0,0 +1,34 @@
+# infrastructure/inference/
+
+## Purpose
+
+Inference adapter layer. The root module provides `DefaultProviderRegistry` (registers `InferenceProvider` instances) and `FirstAvailableRoutingStrategy`. Submodules cover shared HTTP client infrastructure (`commons/`) and the llama.cpp server adapter (`llama_cpp/`).
+
+## Ownership
+
+Adapter for LLM inference backends. Implements `core:inference` interfaces. No dependency on other `infrastructure:*` modules.
+
+## Local Contracts
+
+- `DefaultProviderRegistry` implements `ProviderRegistry` from `core:inference`.
+- `FirstAvailableRoutingStrategy` is the default routing policy; extend only in `core:inference`, not here.
+- All LLM responses are proposals — they must be validated by the core before affecting state (invariant #7). Adapters return raw responses; they do not validate.
+- Network calls to the llama.cpp server are environment observations; results must be recorded as events by callers if replay must reproduce them (invariant #9).
+- Model lifecycle (spawn/own the llama-server process) lives in `llama_cpp/`; the autonomous scheduler is intentionally unbuilt (see root CLAUDE.md).
+
+## Work Guidance
+
+Standard adapter rules apply (see parent `AGENTS.md`). HTTP client code uses Ktor CIO; blocking I/O in `withContext(Dispatchers.IO)`.
+
+## Verification
+
+```
+./gradlew :infrastructure:inference:test --rerun-tasks
+./gradlew :infrastructure:inference:commons:test --rerun-tasks
+./gradlew :infrastructure:inference:llama_cpp:test --rerun-tasks
+```
+
+## Child DOX Index
+
+- `commons/` — shared `ManagedInferenceProvider`, `ModelManager`, `ResourceProbe` (Nvidia/AMD), `ResidencyMode`; no separate AGENTS.md (sub-leaf, covered by this doc)
+- `llama_cpp/` — `LlamaCppInferenceProvider`, `LlamaProcess` (spawns/owns llama-server), `LlamaCppEmbedder`, `LlamaCppTokenizer`, `GbnfGrammarConverter`; no separate AGENTS.md (sub-leaf, covered by this doc)

infrastructure/persistence/AGENTS.md

@@ -0,0 +1,31 @@
+# infrastructure/persistence/
+
+## Purpose
+
+Event store adapters for the correx event log. Provides `SqliteEventStore` (durable, production) and `InMemoryEventStore` (tests/dev). Also contains `LiveArtifactRepository`, which projects artifact state from the event log via `core:artifacts`.
+
+## Ownership
+
+Sole persistence adapter for `core:events` (`EventStore`). No other infrastructure module may write to the event log.
+
+## Local Contracts
+
+- `SqliteEventStore` implements `EventStore` from `core:events`; the SQLite file is the authoritative event log.
+- `InMemoryEventStore` is for tests only — not suitable for production use.
+- `LiveArtifactRepository` implements `ArtifactRepository` from `core:artifacts` by replaying events; it never persists state independently (invariant #1).
+- Schema migrations are the responsibility of this module; `JDBCHelper` owns connection utilities.
+- The event log is append-only: no updates or deletes to existing rows.
+
+## Work Guidance
+
+Standard adapter rules apply (see parent `AGENTS.md`). All JDBC calls go in `withContext(Dispatchers.IO)`.
+
+## Verification
+
+```
+./gradlew :infrastructure:persistence:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

infrastructure/router/AGENTS.md

@@ -0,0 +1,31 @@
+# infrastructure/router/
+
+## Purpose
+
+Router infrastructure adapters. Currently contains one submodule: `turbovec/`, which provides `TurboVecL3MemoryStore` — a durable L3 (cross-session) memory store backed by a Python TurboVec sidecar process communicating over stdio.
+
+## Ownership
+
+Adapter for `core:router` L3 memory interfaces. No source in the root `router/` module itself; all code lives in `turbovec/`.
+
+## Local Contracts
+
+- `TurboVecL3MemoryStore` implements `L3MemoryStore` from `core:router`.
+- The TurboVec sidecar is a Python process; `SidecarProtocol` defines the stdio JSON message protocol.
+- The bundled `turbovec_sidecar.py` script is extracted from the classpath to `~/.cache/correx/` at startup by `InfrastructureModule`.
+- Similarity search results are environment observations (ANN index query); callers must record retrieved memories as events if replay correctness requires them (invariant #9).
+- `TurboVecSidecarConfig` is the only configuration surface.
+
+## Work Guidance
+
+Standard adapter rules apply (see parent `AGENTS.md`). Sidecar communication is async; never block the calling coroutine waiting for the process without `withContext(Dispatchers.IO)`.
+
+## Verification
+
+```
+./gradlew :infrastructure:router:turbovec:test --rerun-tasks
+```
+
+## Child DOX Index
+
+- `turbovec/` — `TurboVecL3MemoryStore`, `SidecarProtocol`, `TurboVecSidecarConfig`; no separate AGENTS.md (sub-leaf, covered by this doc)

infrastructure/tools/AGENTS.md

@@ -0,0 +1,33 @@
+# infrastructure/tools/
+
+## Purpose
+
+Tool implementations and execution infrastructure. Provides `DefaultToolRegistry`, `DispatchingToolExecutor`, and `SandboxedToolExecutor`. Implements concrete tools: shell execution (`ShellTool`), web search (`WebSearchTool`, requires SearXNG), web fetch + HTML→Markdown extraction (`WebFetchTool`, jsoup), task management tools, and filesystem tools (in `filesystem/`).
+
+## Ownership
+
+Adapter for `core:tools`. Depends on `core:tools`, `core:events`, `core:approvals`, `core:sessions`, `core:tasks`, `core:artifacts`, `core:artifacts-store`. The `filesystem/` submodule is a dependency of this module.
+
+## Local Contracts
+
+- `DefaultToolRegistry` implements `ToolRegistry` from `core:tools`.
+- `SandboxedToolExecutor` wraps `DispatchingToolExecutor`; it enforces approval gates and records all tool side effects as events before returning (invariant #5).
+- No tool may execute a side effect without emitting an event — silent execution is not allowed.
+- Web search and web fetch results are environment observations; they must be recorded as events by callers to preserve replay determinism (invariant #9).
+- `ToolConfig` is the only configuration surface; pass via `InfrastructureModule.createToolExecutor()`.
+- `buildTools()` extension on `ToolConfig` assembles the full tool list; add new tools there, not in the registry directly.
+
+## Work Guidance
+
+Standard adapter rules apply (see parent `AGENTS.md`). Network calls (web tools) use Ktor CIO client with `withContext(Dispatchers.IO)`. Shell tool executes OS processes — never suppress `CancellationException` in process wait loops.
+
+## Verification
+
+```
+./gradlew :infrastructure:tools:test --rerun-tasks
+./gradlew :infrastructure:tools:filesystem:test --rerun-tasks
+```
+
+## Child DOX Index
+
+- `filesystem/` — filesystem read/write/list tools implementing `core:tools` contracts; no separate AGENTS.md (sub-leaf, covered by this doc)

infrastructure/workflow/AGENTS.md

@@ -0,0 +1,31 @@
+# infrastructure/workflow/
+
+## Purpose
+
+Workflow and prompt loading adapters. Parses TOML workflow definitions into `core:transitions` execution plans (`TomlWorkflowLoader`, `ExecutionPlanCompiler`), loads prompt files from the filesystem (`FileSystemPromptLoader`), and validates plan structure (`PlanLinter`).
+
+## Ownership
+
+Adapter for `core:transitions` and `core:inference` workflow interfaces. Depends on `core:transitions`, `core:inference`, `core:events`, `core:artifacts`. Uses Jackson for TOML parsing.
+
+## Local Contracts
+
+- `WorkflowLoader` (implemented by `TomlWorkflowLoader`) is the interface for reading workflow definitions; implementations must not embed domain logic beyond parsing and structural validation.
+- `PromptLoader` (implemented by `FileSystemPromptLoader`) reads prompt text from disk; filesystem reads are environment observations — callers must record the loaded content as events if replay must reproduce the exact prompt (invariant #9).
+- `ExecutionPlanCompiler` converts the parsed `ExecutionPlanModel` into a runnable plan for `core:transitions`; compilation is deterministic given the same input model.
+- `PlanLinter` enforces structural rules (e.g. unreachable stages are rejected); linting failures throw `WorkflowValidationException`.
+- `PlanDerivedManifest` exposes the write manifest derived from a plan.
+
+## Work Guidance
+
+Standard adapter rules apply (see parent `AGENTS.md`). Filesystem I/O in `withContext(Dispatchers.IO)`. TOML parsing errors must be surfaced as `WorkflowValidationException`, not raw Jackson exceptions.
+
+## Verification
+
+```
+./gradlew :infrastructure:workflow:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

interfaces/AGENTS.md

@@ -0,0 +1,27 @@
+# interfaces/ — AGENTS.md
+
+## Purpose
+
+Reserved directory. Currently empty. Intended for shared interface or schema definitions that span multiple modules or external consumers.
+
+## Ownership
+
+Unassigned until content is added.
+
+## Local Contracts
+
+_None — directory is empty._
+
+Do not add content here speculatively. Add when a durable cross-module interface contract needs a home outside the Gradle module tree.
+
+## Work Guidance
+
+_None yet._
+
+## Verification
+
+_None yet._
+
+## Child DOX Index
+
+No child AGENTS.md (leaf directory).

plugins/AGENTS.md

@@ -0,0 +1,27 @@
+# plugins/ — AGENTS.md
+
+## Purpose
+
+Reserved directory. Currently empty. Intended for plugin descriptors or plugin implementations that extend the CORREX kernel outside the core Gradle module tree.
+
+## Ownership
+
+Unassigned until content is added.
+
+## Local Contracts
+
+_None — directory is empty._
+
+Do not add content here speculatively. Add when a real plugin with a stable descriptor format ships.
+
+## Work Guidance
+
+_None yet._
+
+## Verification
+
+_None yet._
+
+## Child DOX Index
+
+No child AGENTS.md (leaf directory).

testing/AGENTS.md

@@ -0,0 +1,40 @@
+# testing/
+
+## Purpose
+
+Dedicated test submodules for the correx kernel. Tests here are NOT co-located with production code — each submodule targets a specific verification concern (approval gates, projection correctness, replay determinism, cross-module contracts, integration flows, etc.).
+
+## Ownership
+
+All test submodules in this subtree. Production source is in `core/` and `infrastructure/`; nothing here is deployed.
+
+## Local Contracts
+
+- Tests must not assert on persisted State — only on event-derived state rebuilt by projectors/reducers.
+- No test submodule may import a sibling `testing/*` module except `testing:fixtures`, `testing:kernel`, and `testing:contracts` (shared helpers only).
+- `./gradlew check` applies detekt with `ignoreFailures = false` across all submodules.
+
+## Work Guidance
+
+- Always run tests with `--rerun-tasks` to bypass Gradle cache: `./gradlew :testing:<module>:test --rerun-tasks`
+- Suspend functions in tests use `runBlocking { ... }` — no test coroutine framework needed.
+- Detekt `maxIssues: 120` — do not introduce new rule violations.
+- New `EventPayload` subclass used in tests? Register it in `core/events/.../serialization/Serialization.kt` or deserialization silently fails.
+
+## Verification
+
+```
+./gradlew check   # all submodules: test + detekt + koverVerify
+```
+
+## Child DOX Index
+
+- `testing/approvals` — approval gate logic: grant semantics, security, trigger rules, tier immutability, fuzz
+- `testing/contracts` — cross-module interface contracts and reusable contract test fixtures (projection, replay, inference)
+- `testing/deterministic` — determinism checks: router, session replay, context compression, prompt rendering, validation pipeline
+- `testing/fixtures` — shared test data library: mock implementations, fixture builders, deterministic harness (not a test runner)
+- `testing/integration` — end-to-end flows: orchestrator, tool-call gate, freestyle approval, clarification loop, steering, rehydration
+- `testing/kernel` — core:kernel internals: retry coordinator, approval-before-emit ordering, replay inference provider, context feedback
+- `testing/projections` — reducer and projector correctness for sessions, context, inference, artifacts, router, and journal
+- `testing/replay` — replay determinism: session, approval, validation, transition, decision journal, and repo-knowledge replays
+- `testing/transitions` — FSM/workflow graph: transition resolver, event serialization, fuzz coverage

testing/approvals/AGENTS.md

@@ -0,0 +1,31 @@
+# testing/approvals
+
+## Purpose
+
+Verifies the approval gate subsystem: grant semantics, security properties, trigger rules, tier immutability, mode-based approval, and fuzz coverage. Exercises `core:approvals` in isolation and against real event/session plumbing.
+
+## Ownership
+
+Tests in this submodule. Production code lives in `core:approvals`, `core:events`, `core:sessions`, `core:transitions`, `core:validation`, `infrastructure:persistence`.
+
+## Local Contracts
+
+- Approval grants must never couple to tool execution — `NoExecutionCouplingTest` pins this boundary.
+- Tier values are immutable after assignment — `TierImmutabilityTest` pins this.
+- Grant security properties (escalation, scope leakage) pinned by `GrantSecurityTest`.
+- Approval triggers fire on the correct event sequence — `ApprovalTriggerTest` pins this.
+
+## Work Guidance
+
+- `ApprovalFuzzTest` generates random event sequences; seed is fixed for reproducibility — do not change the seed without a clear reason.
+- Suspend tests use `runBlocking { ... }`.
+
+## Verification
+
+```
+./gradlew :testing:approvals:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

testing/contracts/AGENTS.md

@@ -0,0 +1,31 @@
+# testing/contracts
+
+## Purpose
+
+Cross-module interface contracts and shared contract test fixtures. Two responsibilities:
+1. **Contract tests** — verify that model types (`StageId`, `TransitionId`, `WorkflowGraph`, `ContextSnapshot`, `ValidationReport`) and provider implementations (`InferenceProvider`, inference router, resource probes) satisfy their declared interfaces.
+2. **Reusable fixtures** — `testFixtures` source set exports `ProjectionContractTest`, `ReplayContractTest`, `SessionReplayContractTest`, `CountingProjectionContractTest`, and `NoopArtifactStore` for use by other test submodules.
+
+## Ownership
+
+Tests and test fixtures here. Production modules exercised: `core:events`, `core:transitions`, `core:sessions`, `core:validation`, `core:approvals`, `core:artifacts`, `core:kernel`, `core:inference`, `core:context`, `infrastructure:inference:commons`.
+
+## Local Contracts
+
+- Contract test fixtures in `testFixtures/` are the canonical base for projection and replay contract verification — other submodules inherit from them.
+- `koverVerify` is disabled for this submodule (fixture code is not independently measurable).
+
+## Work Guidance
+
+- Suspend tests use `runBlocking { ... }`.
+- `ConcurrencyRunner` and `DeterministicBarrier` in `main/` are utilities for concurrency contracts — do not add state to them.
+
+## Verification
+
+```
+./gradlew :testing:contracts:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

testing/deterministic/AGENTS.md

@@ -0,0 +1,30 @@
+# testing/deterministic
+
+## Purpose
+
+Pins determinism invariants across the core. Every test here asserts that a given computation produces identical output for identical event input — no randomness, no external I/O. Covers: router reducer and projector, session replay, context compression, prompt renderer ordering, token budget enforcement, approval engine, validation pipeline short-circuit, context pack builder, and L3 metadata rehydration.
+
+## Ownership
+
+Tests in this submodule. Production modules exercised: `core:events`, `core:router`, `core:sessions`, `core:transitions`, `core:validation`, `core:approvals`, `core:context`, `core:inference`, `infrastructure:persistence`.
+
+## Local Contracts
+
+- No test in this submodule may call an external service or live LLM — hard invariant #8 (replay is environment-independent).
+- Every tested path must produce byte-identical state for the same event log on repeated runs.
+- `PromptRendererOrderingTest` pins the rule that all SYSTEM-role entries fold into the leading system message; non-system messages order by `ContextEntry.ordinal`.
+
+## Work Guidance
+
+- Suspend tests use `runBlocking { ... }`.
+- If a new deterministic component is added to `core:router` or `core:context`, add a matching test here.
+
+## Verification
+
+```
+./gradlew :testing:deterministic:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

testing/fixtures/AGENTS.md

@@ -0,0 +1,30 @@
+# testing/fixtures
+
+## Purpose
+
+Shared test data library. Not a test runner — contains no test classes of its own (except `MockToolsTest` which validates the mocks themselves). Provides: mock implementations (`MockInferenceProvider`, `MockTokenizer`, `MockEventReplayer`, `MockSessionRepository`), stub tools (`EchoTool`, `FailingTool`, `RejectedTool`), fixture builders (`EventFixtures`, `InferenceFixtures`, `WorkflowFixtures`, `ApprovalFixtures`, `CycleFixtures`, `ContextFixtures`, `TransitionFixtures`), and `DeterministicHarness`.
+
+## Ownership
+
+This submodule is a library dependency for other `testing/*` submodules. Production modules it wraps: `core:events`, `core:transitions`, `core:approvals`, `core:sessions`, `core:tools`, `core:inference`, `core:context`, `core:kernel`, `core:validation`, `infrastructure:persistence`.
+
+## Local Contracts
+
+- All mocks must remain stateless or explicitly reset between uses — callers cannot assume shared state across tests.
+- `DeterministicHarness` must not make live LLM or network calls.
+- `koverVerify` is disabled (library code, not independently measurable coverage).
+
+## Work Guidance
+
+- Add fixtures here only when two or more `testing/*` submodules need the same setup. Single-use helpers stay local to the submodule that needs them.
+- No domain logic in fixtures — only wiring and canned data.
+
+## Verification
+
+```
+./gradlew :testing:fixtures:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

testing/integration/AGENTS.md

@@ -0,0 +1,30 @@
+# testing/integration
+
+## Purpose
+
+End-to-end integration tests that wire multiple core modules together without live LLM or network. Covers: `SessionOrchestrator` full flows, tool-call gate, freestyle approval gate, clarification loop, steering preemption, graph reroute, artifact injection, workspace-scoped tool registry, validation pipeline integration, critique calibration wiring, session rehydration, repo-map reuse, and subagent runner seam.
+
+## Ownership
+
+Tests in this submodule. Production modules exercised: `core:events`, `core:sessions`, `core:transitions`, `core:validation`, `core:approvals`, `core:context`, `core:inference`, `core:kernel`, `core:journal`, `core:risk`, `core:tools`, `core:toolintent`, `core:artifacts`, `core:artifacts-store`, `core:router`, `core:config`, `infrastructure:persistence`, `infrastructure:tools`, `infrastructure:tools:filesystem`, `apps:server`.
+
+## Local Contracts
+
+- Tests use mock inference (`MockInferenceProvider` from `testing:fixtures`) — no live LLM.
+- `apps:server` is imported for Ktor wiring tests only; no external HTTP calls.
+- Two-plane validation (Plane 2 / `core:toolintent`) must be exercised by at least one test here — `ToolCallGateTest` covers this.
+
+## Work Guidance
+
+- Suspend tests use `runBlocking { ... }` or `kotlinx-coroutines-test`.
+- These are the slowest tests; run targeted with `:testing:integration:test --tests "ClassName"` during development.
+
+## Verification
+
+```
+./gradlew :testing:integration:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

testing/kernel/AGENTS.md

@@ -0,0 +1,30 @@
+# testing/kernel
+
+## Purpose
+
+Focused tests for `core:kernel` internals that require real event-store plumbing. Covers: approval-before-emit ordering race, retry coordinator behavior, replay inference provider, launch registration race conditions, workspace derivation from replay, and context feedback propagation.
+
+## Ownership
+
+Tests and `MockEventReplayer` helper in this submodule. Production modules exercised: `core:kernel`, `core:events`, `core:sessions`, `core:inference`, `core:approvals`, `core:context`, `core:transitions`, `core:validation`, `core:risk`, `core:tools`, `core:artifacts`, `core:artifacts-store`, `infrastructure:persistence`.
+
+## Local Contracts
+
+- `ApprovalRegisterBeforeEmitTest` pins the ordering invariant: approval listener must be registered before the event is emitted or the gate is missed.
+- `LaunchRegistrationRaceTest` pins that concurrent session launches do not corrupt registration state.
+- `koverVerify` is disabled for this submodule.
+
+## Work Guidance
+
+- Suspend tests use `runBlocking { ... }` or `kotlinx-coroutines-test`.
+- Race tests (`LaunchRegistrationRaceTest`) must not use `Thread.sleep()` — use coroutine barriers.
+
+## Verification
+
+```
+./gradlew :testing:kernel:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

testing/projections/AGENTS.md

@@ -0,0 +1,30 @@
+# testing/projections
+
+## Purpose
+
+Verifies that reducers and projectors rebuild state correctly from event sequences. Covers: `DefaultSessionReducer`, `OrchestrationReducer`/`Projector`, `InferenceReducer`/`Projector`, `ArtifactReducer`, `ContextReducer`/`Projector`, `RouterProjector`, `DecisionJournalProjector`, `SessionProjector`, `ProjectMemoryDistiller`, and `PreemptSteeringJournal`.
+
+## Ownership
+
+Tests in this submodule. Production modules exercised: `core:events`, `core:sessions`, `core:transitions`, `core:context`, `core:inference`, `core:kernel`, `core:artifacts`, `core:router`, `core:journal`.
+
+## Local Contracts
+
+- Projections must be rebuilt from events only — no test may assert on a persisted State object.
+- Reducers are pure functions: same events → same state, always. Tests must verify this property explicitly (run twice, compare).
+- Any new reducer or projector added to a `core:*` module needs a corresponding test here.
+
+## Work Guidance
+
+- Suspend tests use `runBlocking { ... }`.
+- Keep event sequences in tests minimal — use `testing:fixtures` builders rather than raw event construction.
+
+## Verification
+
+```
+./gradlew :testing:projections:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

testing/replay/AGENTS.md

@@ -0,0 +1,30 @@
+# testing/replay
+
+## Purpose
+
+Pins replay determinism end-to-end: feeds a recorded event log through the full replay stack and asserts the resulting state is identical to what was produced during original execution. Covers: session replay, approval replay, validation replay, decision journal replay, refinement iteration replay, execution-plan-locked replay, repo-map replay, repo-knowledge replay, transition replay integration, and empty-session edge cases. Also exercises `DeterministicHarness` directly.
+
+## Ownership
+
+Tests in this submodule. Production modules exercised: `core:events`, `core:journal`, `core:kernel`, `core:context`, `core:sessions`, `core:transitions`, `core:validation`, `core:approvals`, `core:artifacts`, `infrastructure:persistence`, `infrastructure:workflow`.
+
+## Local Contracts
+
+- Hard invariant #8: replay must complete without any external service calls, live LLM, or network.
+- Hard invariant #9: environment observations (filesystem, clock, embedder) must be read from recorded events — replay tests must not re-query the environment.
+- Every replay test must compare final state byte-for-byte (or field-for-field) against a known-good fixture.
+
+## Work Guidance
+
+- Suspend tests use `runBlocking { ... }`.
+- Do not add `Thread.sleep()` or timing-sensitive assertions — replay is synchronous over a fixed event log.
+
+## Verification
+
+```
+./gradlew :testing:replay:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).

testing/transitions/AGENTS.md

@@ -0,0 +1,29 @@
+# testing/transitions
+
+## Purpose
+
+Verifies `core:transitions` — the FSM/workflow graph layer. Covers: `DefaultTransitionResolver` correctness, transition event serialization round-trips, and fuzz coverage over random graph topologies.
+
+## Ownership
+
+Tests in this submodule. Production modules exercised: `core:transitions`, `core:events`, `core:inference`.
+
+## Local Contracts
+
+- `TransitionEventSerializationTest` pins that every transition event survives a serialize → deserialize round-trip without data loss; must be updated when new transition event types are added.
+- `TransitionFuzzTest` generates random graphs; add new resolver logic → extend the fuzz domain.
+
+## Work Guidance
+
+- Suspend tests use `runBlocking { ... }`.
+- This is a narrow module — keep tests focused on graph resolution and serialization; cross-cutting concerns belong in `testing:integration` or `testing:deterministic`.
+
+## Verification
+
+```
+./gradlew :testing:transitions:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).