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.
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user