docs(dox): build out the DOX AGENTS.md hierarchy

Root Child DOX Index assembled, plus a per-module AGENTS.md across the tree (core/*, infrastructure/*, apps/*, testing/*, and docs/examples/frontend/etc), each following the DOX section shape: Purpose, Ownership, Local Contracts, Work Guidance, Verification, Child DOX Index.
2026-06-28 20:43:27 +04:00
parent 1cb7fec677
commit d26f20c316
48 changed files with 1783 additions and 0 deletions
@@ -0,0 +1,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).