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:
2026-06-28 20:43:27 +04:00
parent 1cb7fec677
commit d26f20c316
48 changed files with 1783 additions and 0 deletions
+36
View File
@@ -0,0 +1,36 @@
# core/approvals — AGENTS.md
## Purpose
Approval gate logic: evaluates tool-execution requests against active grants and session approval mode, records decisions as events, and exposes an engine interface for the kernel to query.
## Ownership
CORREX kernel team. Changes to approval semantics must be validated against `testing/approvals/`.
## Local Contracts
- `ApprovalEngine` — primary interface; `DefaultApprovalEngine` evaluates `DomainApprovalRequest` against `ApprovalState`.
- `NoOpApprovalEngine` — always grants; used in test/replay contexts.
- `ApprovalState` rebuilt from events via `ApprovalReducer` + `ApprovalProjector`.
- `ApprovalGrant` holds scope identity (`ApprovalScopeIdentity`), mode, and expiry. Grants are recorded as events in `core:events` (`ApprovalEvents.kt`).
- Hard Invariant #4 applies: approvals cannot override policy denial. Policy failure is terminal.
## Work Guidance
- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
- `DefaultApprovalReducer` only does `state.copy(...)`. No grant-evaluation logic in the reducer.
- Grant evaluation lives in `DefaultApprovalEngine`, not in the reducer or projector.
- `ApprovalContext` carries per-request context; `ApprovalDecision` is a sealed result type.
## Verification
```bash
./gradlew :core:approvals:test --rerun-tasks
```
Extended tests in `testing/approvals/`: edge cases, fuzz, grant security, tier immutability.
## Child DOX Index
No child AGENTS.md (leaf module).