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:
@@ -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).
|
||||
Reference in New Issue
Block a user