oskar/agent-system
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
agent-system/docs/operator/approval-workflow.md

1.5 KiB
Raw Blame History

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.