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