Operator Workflows

Stand: 2026-05-26

Ziel

OpenCode soll als Operations-Konsole nicht nur Tool-Rohdaten anzeigen, sondern Operatoren durch Review, Approval, Locking, Backup, Verification, Rollback und Recovery fuehren.

Diese Schicht fuehrt keine Infrastruktur-Aenderungen aus. Sie erzeugt strukturierte UX-Daten und Changeplan-Artefakte.

Unified Operator Response

Schema:

lanstyle.operator_response.v1

Pflichtfelder:

Feld	Zweck
summary	kurze Gesamtbewertung
operator_summary	menschenlesbarer Change-Ueberblick
risk_summary	Risk Level, Gruende, Blast Radius
policy_summary	Policy-Entscheidung, Blocker, Wartungsfenster
lock_summary	aktive Locks, Lock-Kandidaten, Blocker
backup_summary	erwartete oder erzeugte Backups
rollback_summary	Rueckweg und Grenzen
recovery_summary	Recovery-Bedarf und empfohlene Aktion
approval_summary	Approval-ID, Freigabetext, Ablauf
timeline_summary	strukturierte Timeline fuer OpenCode
next_action	empfohlene naechste Operator-Aktion
exact_approval_phrase	exakt zu sendender Freigabetext
explicit_out_of_scope	nicht enthaltene Aktionen
warnings	Warnungen
blockers	harte Blocker

Action Classification

Jede Action wird klassifiziert:

• read_only
• preflight_only
• mock_execution
• scoped_write
• destructive_prepare
• destructive_execute
• rollback
• recovery
• emergency

OpenCode darf aus der Klassifikation ableiten, ob ein Execute angeboten werden darf oder ob nur Review/Approval angezeigt wird.

Human Decision Points

Die API liefert explizite Entscheidungsflags:

• requires_human_review
• requires_approval
• requires_second_approval
• requires_maintenance_window
• requires_manual_verification
• requires_post_execution_validation

Das LLM darf diese Flags nicht selbst aufweichen.

Workflow States

Standardisierte Zustaende:

• planned
• awaiting_review
• awaiting_approval
• approved
• blocked
• executing
• verification_pending
• rollback_available
• recovery_required
• completed
• failed
• expired

Timeline UX

Timeline-Felder:

• who_requested
• who_approved
• when_locked
• when_executed
• when_verified
• when_audited
• when_released
• rollback_available_until
• approval_expires_at

OpenCode soll diese Werte als Timeline Cards darstellen.

Suggested Actions

Jede Operator-Antwort enthaelt:

• safest_next_action
• recommended_operator_action
• recommended_rollback_action
• recommended_recovery_action
• recommended_manual_checks

Bei Blockern ist safest_next_action immer Stop/Review, nicht Execute.

Wichtig fuer Golden-Path-Preflights:

• CTID-/IP-/Template-/Gateway-/Storage-Konflikte sind Ziel- bzw. Readiness-Konflikte.
• Sie duerfen keine Lock-Recovery empfehlen.
• Lock-Recovery wird nur empfohlen, wenn ein echter Dependency-Lock-, stale-, orphaned- oder failed-release-Konflikt vorliegt.
• Bei CTID/IP-Kollision ist die sichere naechste Aktion: freie CTID/IP waehlen und Preflight erneut ausfuehren.

Operatorfreundliche Darstellung

OpenCode soll zuerst die kompakten Felder anzeigen:

• operator_priority
• operator_card
• blockers
• warnings
• next_action
• approval_ux
• rollback_ux
• timeline_compact

Rohdaten wie policy_summary, risk_summary, lock_summary, backup_summary, recovery_summary und timeline_summary bleiben vorhanden, sollen aber einklappbar sein.

Approval-Texte werden nur prominent gezeigt, wenn die Aktion nicht blockiert ist und wirklich eine Freigabe erforderlich ist. Bei blocked_before_execution=true gilt: Es wurde nichts veraendert, Rollback ist nicht noetig.

Kompakte Cards

Die API liefert eine priorisierte Card-Struktur fuer OpenCode:

• operator_priority: Status, Risk, Next Action, Approval, Rollback, Backup, Drift
• operator_card.overall_status: ready, warning, blocked, awaiting_approval, completed
• operator_card.badges: 🟢 healthy, 🟡 warning, 🔴 critical, 🔒 approval required, ⛔ blocked, ♻ rollback available
• trust_summary: confirmed, interpreted, uncertain, observed_at, source_tool, confidence_level

Rohdaten sollen nur in einem Debug-/Engineering-Abschnitt sichtbar sein. Die erste Ansicht muss fuer Operatoren ohne JSON-Lesen verstaendlich bleiben.

Rendering-Hinweise

Serverseitige Hinweise:

• show_as_warning
• show_as_blocker
• highlight_risk
• highlight_approval
• highlight_recovery
• collapseable_sections
• timeline_cards
• risk_badges

API

Endpoint	Zweck	Infrastruktur-Write
GET /operator-workflows/policy	Schema, States, Action Classes	nein
GET /operator-workflows/lxc-124-description-change	hypothetischer LXC-124-Workflow	nein
GET /workflow-catalog	Golden-Path-Katalog	nein
POST /workflow-catalog/preflight	Golden-Path-Preflight	nein
POST /workflow-catalog/mock-execute	Golden-Path-Mock	nur Artefakte
POST /workflow-catalog/runtime-backup-validation	produktiver Read-only Backup-/Restore-Readiness-Report	nein
GET /scheduled-workflows	Scheduled Read-only Workflows	nein
GET /scheduled-workflows/history	Laufhistorie	nein
GET /scheduled-workflows/trends	Trendübersicht	nein
POST /scheduled-workflows/run-now-readonly	manueller Read-only Lauf	nur Artefakte/History

Bestehende Endpunkte geben zusaetzlich unified_operator_response zurueck:

• POST /execution-chains/preflight
• POST /execution-chains/mock-execute
• POST /dependency-locks/recovery/preflight
• POST /dependency-locks/recovery/approve-request
• POST /dependency-locks/recovery/execute

LXC 124 Beispielworkflow

Der Beispielworkflow simuliert:

• hypothetische Description-Aenderung
• Approval benoetigt
• Lock wuerde acquired
• Backup wuerde erstellt
• Verification erforderlich
• Rollback moeglich
• Cleanup nicht im Scope

Es wird kein Proxmox-Write ausgefuehrt. LXC 124 bleibt unveraendert gestoppt.

Golden Paths

Golden Paths nutzen dieselbe Unified Operator Response. OpenCode soll sie wie gefuehrte Standard-Runbooks anzeigen:

• Workflow-Metadaten
• validierte Inputs
• Risk/Policy/Lock Summary
• Suggested Actions
• Artefaktlinks
• explicit out of scope

Details: Golden Paths.

Read-only Betrieb

runtime_backup_validation_v1 ist als erster produktiver Read-only-Workflow freigegeben. OpenCode soll die Antwort als Betriebsreport anzeigen:

• Gesamtstatus grün/gelb/rot
• kritischste Lücken zuerst
• Komponentenmatrix
• Restore-Readiness
• empfohlene nächste Aktion
• Hinweis: keine Approval nötig, kein Lock nötig, keine Infrastrukturänderung

Details: Runtime Backup Validation.

Scheduled Workflows

Scheduled Workflows liefern OpenCode eine Betriebs-Konsolen-Sicht:

• letzter erfolgreicher Lauf
• nächster erwarteter Lauf
• stale Workflows
• neue Risiken
• gelbe/rote Komponenten
• Trendverschlechterungen
• empfohlene Operator-Aktion

Details: Scheduled Workflows.

OpenCode Operator UX

OpenCode soll bei allen Controlled-Execution- und Golden-Path-Antworten diese Reihenfolge bevorzugen:

1. summary
2. operator_priority
3. operator_card
4. blockers
5. warnings
6. next_action
7. approval_ux
8. rollback_ux
9. timeline_compact
10. trust_summary
11. einklappbare Details: risk_summary, policy_summary, lock_summary, backup_summary, timeline_summary

Zusätzliche Read-only-Hilfen liefert die Tools API:

Endpoint	Zweck
GET /ops/opencode-guidance	Rendering-Reihenfolge, Risk Badges, Approval-Hinweise
GET /ops/self-service-templates	sichere Startpunkte für Standardaufgaben
POST /ops/change-review/preflight	zweiter Review-Layer vor Changes
GET /ops/safe-mode-policy	Incident-/Safe-Mode-Verhalten

OpenCode soll Roh-JSON nur auf Nachfrage anzeigen. Standardmäßig reichen Operator Summary, Risiko, Blocker, Approval-Text und nächste sichere Aktion.

Lock-Konflikt Summary

Bei Lock-Konflikten muss die Operator Summary kompakt und eindeutig bleiben:

• Gesamtentscheidung: blocked_by_lock
• Warum blockiert: aktiver, stale, orphaned oder failed-release Lock
• Sicher als naechstes: inspect_lock, inspect_chain_status, state_drift_check, recovery_preflight
• Nicht tun: keine automatische Freigabe, keine automatische Folge-Chain, keine Fortsetzung nur wegen Timeout

Wenn kein echter Queue-Mechanismus aktiv ist, darf OpenCode keine wartende Chain darstellen. Die Chain ist blockiert; der Operator plant sie nach erfolgreicher Lock-Recovery neu und fuehrt die Validierung erneut aus.