234 lines
6.6 KiB
Markdown
234 lines
6.6 KiB
Markdown
---
|
||
name: "Core Approvals Submodule Spec"
|
||
description: "Specification for :core:approvals – tiered approval system"
|
||
depth: 2
|
||
links: ["../index.md", "../decisions/adr-0004-approval-tier-design.md", "./core-validation-submodule-spec.md"]
|
||
---
|
||
|
||
# :core:approvals module specification
|
||
|
||
version: 0.1-draft
|
||
status: foundational specification
|
||
|
||
---
|
||
|
||
# 1. purpose
|
||
|
||
`:core:approvals` defines the risk-aware approval system that decides whether operations beyond pre‑configured thresholds may proceed.
|
||
|
||
It is the authoritative subsystem for:
|
||
|
||
* approval tier semantics
|
||
* approval mode enforcement
|
||
* approval request/decision lifecycle
|
||
* escalation rules
|
||
* steering injection
|
||
* approval history (immutable audit trail)
|
||
|
||
Approvals are the primary human‑in‑the‑loop safety mechanism. They are not a simple pop‑up; they gate execution by checking tiers and policies, and they record every decision.
|
||
|
||
---
|
||
|
||
# 2. responsibilities
|
||
|
||
`:core:approvals` owns:
|
||
|
||
* approval tier definitions (T0–T4)
|
||
* approval mode configurations (prompt, auto, deny, yolo)
|
||
* approval event contracts
|
||
* escalation rules
|
||
* session‑scope approval grants
|
||
* steering‑aware approval injection
|
||
* approval part of validation pipeline integration
|
||
* immutable approval ledger
|
||
|
||
---
|
||
|
||
# 3. non-responsibilities
|
||
|
||
`:core:approvals` MUST NOT own:
|
||
|
||
* the validation pipeline itself (that's `:core:validation`)
|
||
* artifact generation
|
||
* transition execution
|
||
* policy enforcement (policies may be evaluated, but the engine is separate)
|
||
* UI rendering of approval prompts
|
||
* persistence implementations
|
||
|
||
---
|
||
|
||
# 4. architectural role
|
||
|
||
`:core:approvals` acts as:
|
||
|
||
* human/system checkpoint authority
|
||
* risk boundary for mutable operations
|
||
* audit trail for sensitive decisions
|
||
|
||
All tool or stage escalation that exceeds the configured auto‑approved tier passes through this subsystem.
|
||
|
||
---
|
||
|
||
# 5. design principles
|
||
|
||
## 5.1 tiers enforce risk boundaries
|
||
|
||
Every tool and operation has a declared tier. By default, only T0 and T1 may be auto‑approved. Higher tiers require explicit human approval unless the session is in an elevated mode.
|
||
|
||
## 5.2 approvals are immutable
|
||
|
||
An approval decision, once recorded, cannot be changed. Corrections require a new decision that supersedes the previous one within the audit log.
|
||
|
||
## 5.3 steering is first‑class
|
||
|
||
Approval decisions may include steering instructions: natural language suggestions injected into the next context pack. This bridges human guidance into the execution loop without breaking replay.
|
||
|
||
## 5.4 replay-safe
|
||
|
||
Approval events are replayed deterministically. In replay, approval decisions are re‑applied from history, not re‑requested from the user.
|
||
|
||
---
|
||
|
||
# 6. tier model
|
||
|
||
```
|
||
T0 – inference only (read model outputs)
|
||
T1 – read‑only tool access
|
||
T2 – reversible mutation (e.g., git commit, file create)
|
||
T3 – external/network access
|
||
T4 – destructive (e.g., rm -rf, database drop)
|
||
```
|
||
|
||
Each tool, stage, or even artifact category may declare a tier requirement.
|
||
|
||
---
|
||
|
||
# 7. approval modes
|
||
|
||
Mode can be changed per session or per approval gate.
|
||
|
||
* **prompt** – always ask user
|
||
* **auto** – approve automatically if tier ≤ configured threshold
|
||
* **deny** – automatically reject
|
||
* **yolo** – bypass all checks (logging only); for sandboxed experimentation
|
||
|
||
---
|
||
|
||
# 8. approval request lifecycle
|
||
|
||
1. An artifact or tool invocation triggers an `ApprovalRequired` event from the validation pipeline.
|
||
2. `:core:approvals` evaluates:
|
||
- tier vs. current session mode
|
||
- any explicit denials
|
||
- session‑scoped grants (e.g., “auto‑approve all T2 for this session”)
|
||
3. If decision can be made automatically, emit `ApprovalGranted/Automatic`.
|
||
4. If human input needed, pause orchestration and emit `ApprovalPending`.
|
||
5. User supplies decision (approve/reject/steer). Decision is recorded, orchestration resumes.
|
||
|
||
---
|
||
|
||
# 9. steering injection
|
||
|
||
When user approves with a steering message, the approval event carries that text. The context processor later picks it up and injects it as additional instruction for the next stage, with proper delimiting (e.g., “User guidance: …”).
|
||
|
||
---
|
||
|
||
# 10. event ownership
|
||
|
||
`:core:approvals` owns:
|
||
|
||
* `ApprovalRequired`
|
||
* `ApprovalPending`
|
||
* `ApprovalGranted` / `ApprovalGrantedAuto`
|
||
* `ApprovalRejected`
|
||
* `ApprovalEscalated`
|
||
* `ApprovalSessionGrantAdded`
|
||
* `ApprovalModeChanged`
|
||
|
||
All carry causation back to the originating artifact or tool event.
|
||
|
||
---
|
||
|
||
# 11. consumed events
|
||
|
||
Consumes:
|
||
|
||
* `ArtifactValidated` (when approval layer decides escalation)
|
||
* `ToolAboutToExecute` (for tool-level approvals)
|
||
* `UserInput` (approval decision)
|
||
|
||
---
|
||
|
||
# 12. invariants
|
||
|
||
* Approval history is append-only.
|
||
* No operation above its tier may execute without a matching `ApprovalGranted` event.
|
||
* Session grants are ephemeral and must be replay‑reconstructed from events.
|
||
* Steering text is preserved verbatim.
|
||
|
||
---
|
||
|
||
# 13. replay semantics
|
||
|
||
During replay, `:core:approvals` replays decisions from the event log. No user interaction occurs. If a decision is missing (e.g., corrupted log), replay fails explicitly.
|
||
|
||
---
|
||
|
||
# 14. threading/concurrency
|
||
|
||
Approval handling is sequential within a session. The orchestration coroutine suspends until a decision is available. Timeout mechanisms exist for approval expiration.
|
||
|
||
---
|
||
|
||
# 15. failure semantics
|
||
|
||
If an approval request times out or the user refuses, the corresponding artifact or tool execution is rejected, and a failure event is emitted. The session may transition to a recovery or failed state according to transition rules.
|
||
|
||
---
|
||
|
||
# 16. observable requirements
|
||
|
||
Must expose:
|
||
|
||
* approval request frequency
|
||
* approval response latency
|
||
* rejection rates per tier
|
||
* active session grants
|
||
|
||
---
|
||
|
||
# 17. security boundaries
|
||
|
||
Approvals are a trust boundary. Untrusted plugins cannot circumvent approval checks. The approval engine runs inside core with no external dependencies.
|
||
|
||
---
|
||
|
||
# 18. extension model
|
||
|
||
Plugins cannot alter tier definitions but may add custom escalation logic or additional constraints (e.g., “never approve network access after 10pm”).
|
||
|
||
---
|
||
|
||
# 19. forbidden patterns
|
||
|
||
* silent escalation without event
|
||
* mutable approval records
|
||
* approval decisions that bypass tier checks
|
||
* replay that re‑prompts the user
|
||
* granting broad permissions without session scope
|
||
|
||
---
|
||
|
||
# 20. testing requirements
|
||
|
||
* tier enforcement across modes
|
||
* auto‑approve/deny logic
|
||
* steering injection hygiene
|
||
* replay of approval sequences
|
||
* timeout and cancellation behavior
|
||
|
||
---
|
||
|
||
# 21. philosophy
|
||
|
||
Approvals translate bounded autonomy into practice. They are the harness’s way of saying “you may go this far without me, but not further”, with a clear audit trail and the ability to inject human judgment exactly where it’s needed. |