first commit

openspec/changes/redesign-platform-web-interactions/specs/operation-feedback-and-safety/spec.md

@@ -0,0 +1,93 @@
+## ADDED Requirements
+
+### Requirement: User actions have visible lifecycle feedback
+The platform web application SHALL show visible lifecycle feedback for user-triggered operations.
+
+#### Scenario: Button enters pending state
+- **WHEN** a user submits an operation from a button or form
+- **THEN** the initiating control shows a pending or loading state and prevents accidental duplicate submission until the operation state is known
+
+#### Scenario: Operation success is visible
+- **WHEN** a submitted operation completes successfully
+- **THEN** the UI shows a success result and provides relevant next actions such as viewing logs or operation history when available
+
+#### Scenario: Operation failure is visible
+- **WHEN** a submitted operation fails
+- **THEN** the UI shows a failure result with an error reason and relevant retry or diagnostic actions when available
+
+### Requirement: Operations are traceable
+The platform web application SHALL expose a traceable operation or job identity for operations that affect platform, run, plugin, server, or LLM systems.
+
+#### Scenario: Operation detail includes trace data
+- **WHEN** an operation is created or retrieved
+- **THEN** the UI can display its operation/job ID, target, requester, status, timestamps, and error reason when available
+
+#### Scenario: Failure includes diagnostic identifier
+- **WHEN** an operation or data load fails with a diagnostic identifier
+- **THEN** the UI displays the identifier or provides a copyable diagnostic summary for debugging
+
+### Requirement: One user intent maps to one visible business operation
+The platform web application SHALL present each user-triggered action as one visible business operation even if the backend performs multiple internal steps.
+
+#### Scenario: Complex action is tracked as one operation
+- **WHEN** a user triggers a complex action such as restart server, send gift, apply plugin control, or write configuration
+- **THEN** the UI displays one operation lifecycle for the user intent and tracks progress or result through one operation/job context
+
+#### Scenario: Multi-step backend failure is debuggable
+- **WHEN** an internal step of a complex action fails
+- **THEN** the operation result identifies the failing stage or error reason when that information is available
+
+### Requirement: Empty states are actionable
+The platform web application SHALL show actionable empty states instead of blank pages for expected no-data conditions.
+
+#### Scenario: Server list is empty for server administrator
+- **WHEN** a server administrator has no manageable servers
+- **THEN** the server list shows an empty state explaining that no manageable servers are available and provides a refresh action
+
+#### Scenario: Platform overview has no servers
+- **WHEN** a platform administrator opens the platform overview and no server instances exist
+- **THEN** the overview shows an empty state with a management-oriented next action rather than a blank page
+
+### Requirement: Loading states are scoped
+The platform web application SHALL use scoped loading states so one slow module does not blank unrelated content.
+
+#### Scenario: Dashboard module loads independently
+- **WHEN** one platform overview module is loading slowly
+- **THEN** the UI shows a loading state for that module while keeping already loaded modules visible
+
+#### Scenario: Server card metrics load independently
+- **WHEN** server metrics are still loading
+- **THEN** the server card remains visible with stable placeholders for pending metrics
+
+### Requirement: Errors identify affected scope
+The platform web application SHALL display errors with enough scope and recovery information for operators to act.
+
+#### Scenario: Module load error is localized
+- **WHEN** a dashboard module or server detail section fails to load
+- **THEN** the error is shown within the affected module or section with retry and diagnostic information when available
+
+#### Scenario: Full-page error preserves navigation
+- **WHEN** a full-page error prevents rendering the requested workspace
+- **THEN** the application preserves usable global navigation or a safe route back to an authorized workspace
+
+### Requirement: Dangerous actions require confirmation
+The platform web application SHALL require explicit confirmation for destructive or disruptive operations.
+
+#### Scenario: Restart or stop requires confirmation
+- **WHEN** a user initiates a disruptive server action such as stop or restart
+- **THEN** the UI asks for confirmation before submitting the operation
+
+#### Scenario: Configuration write requires diff confirmation
+- **WHEN** a user initiates a configuration write from manual edits or LLM output
+- **THEN** the UI requires the user to review and confirm the diff before submission
+
+### Requirement: AI and run safety boundaries are preserved
+The platform web application SHALL preserve platform AI provider and run communication safety boundaries in all redesigned interactions.
+
+#### Scenario: AI keys are never exposed to frontend
+- **WHEN** platform_web uses AI provider health or LLM assistance features
+- **THEN** raw AI keys and provider secrets are not exposed to platform_web or plugin pages
+
+#### Scenario: Run internals are not exposed to frontend
+- **WHEN** platform_web displays server operations, logs, artifacts, or diagnostics
+- **THEN** host paths, raw credentials, and direct run sockets are not exposed to platform_web or plugin pages