correx/AGENTS.md

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

Project Architecture

• Correx is a local-first, event-sourced orchestration kernel for LLM workflows, built with Kotlin/JVM 21 and Gradle.
• The event log is the sole source of truth. State is rebuilt from events; projections are disposable and owned by their bounded context.
• Keep deterministic core logic separate from nondeterministic inputs: LLM and tool outputs are untrusted proposals until validation; policy denials are terminal and cannot be overridden.
• Record each nondeterministic environment observation (for example filesystem, network, retrieval, or clock data) as an event when observed. Replay and downstream logic must use recorded facts and make no external calls.
• Tools must declare an execution tier and record every side effect as events. Compression and other derived representations are non-authoritative and cannot replace original events.
• New EventPayload implementations must be registered in core/events/.../serialization/Serialization.kt in the eventModule polymorphic block; otherwise runtime deserialization can fail silently.

Module Boundaries

• core/ contains domain logic and may not depend on infrastructure/ or apps/.
• infrastructure/ implements adapters against core contracts; apps/ composes core and infrastructure into runnable processes.
• Do not introduce circular dependencies or dependencies from a module to a sibling core module unless the module architecture explicitly establishes one. Shared event vocabulary belongs in core:events.
• Inject dependencies rather than constructing concrete collaborators inside domain classes; use existing interfaces at boundaries.

Kotlin Work Guidance

• Keep reducers limited to deterministic state transitions; do not put domain decisions or side effects in reducers.
• Convert exceptions to sealed domain results at the earliest practical boundary. Do not use broad try/catch that silently returns a fallback.
• Use coroutine-safe patterns: put blocking I/O in Dispatchers.IO, never use Thread.sleep(), and do not swallow CancellationException.
• Before finalizing a Kotlin file, remove unused imports and verify direct imports only.

Verification and Context

• Tests for production modules may live under testing/; search there before deciding a module has no tests.
• Run focused tests with ./gradlew :path:to:module:test --rerun-tasks. Run ./gradlew check for the full test, Detekt, and Kover verification suite.
• Detekt failures are enforced. Prefer correcting violations; use the narrowest suppression only for a genuine false positive.
• Use python scripts/ctx.py <query> for ranked code context and python scripts/ctx.py --deps <file> for symbol dependency context when relevant.

Task Tracking

• Use the Vikunja Correx project (project_id: 4) as the cross-session, user-visible backlog for follow-up work the user wants retained, such as deferred fixes, unverified QA gates, and designed-but-unimplemented work.
• Use the available Vikunja integration to review, create, and close tasks. Keep each task self-contained with its root cause, chosen fix, and relevant file paths so it can be resumed without prior session context.

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