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