agent-system/docs/operator/approval-workflow.md

# Operator Approval Workflow

This document describes the process of reviewing and approving actions generated by the reconciliation supervisor. The Control Plane is entirely filesystem-first, meaning all state is derived from and written to specific directories.

## Workflow Stages

### 1. Action Identification
When the supervisor (running in `homelab-codex-ws`) identifies a delta between desired and actual state, it generates a pending action JSON file in `/opt/homelab/actions/pending/`.

### 2. Risk Assessment
Actions are categorized by risk level:
- **Safe**: Low impact, high confidence. Can be auto-approved in autonomous mode.
- **Guarded**: Moderate impact. Requires explicit operator approval.
- **Dangerous**: High impact (e.g., node redeploy). Requires multi-step approval. These are highlighted in red in the UI.

### 3. Review Process
1. Navigate to the **Action Queue** view.
2. Review the **Confidence Score** and **Correlation Chain** (if available) to understand why the action was proposed.
3. Check the **Trace** to see the lifecycle of the action.

### 4. Decision
- **Approve**: Moves the action JSON file from `pending/` to `approved/`.
- **Reject**: Moves the action JSON file from `pending/` to `rejected/`.
- **Execute**: Moves an approved action from `approved/` to `running/`. The live executor in the runtime will then pick it up.

## Filesystem Semantics
The operator console performs "mutations" by moving files between subdirectories in `/opt/homelab/actions/`. This ensures a robust, local-first operational trail.