TenantAtlas/specs/170-system-operations-surface-alignment/spec.md

# Feature Specification: System Operations Surface Alignment

**Feature Branch**: `170-system-operations-surface-alignment`  
**Created**: 2026-03-30  
**Status**: Draft  
**Input**: User description: "System Operations Surface Alignment"

## Spec Scope Fields *(mandatory)*

- **Scope**: platform
- **Primary Routes**:
  - `/system/ops/runs`
  - `/system/ops/failures`
  - `/system/ops/stuck`
  - `/system/ops/runs/{run}`
- **Data Ownership**:
  - No new platform-owned, workspace-owned, or tenant-owned records are introduced
  - Existing `OperationRun` records remain the only source of truth for system operations list and detail surfaces
  - This feature changes only operator-facing interaction semantics for existing system operations pages
- **RBAC**:
  - Platform plane only
  - Existing `platform.operations.view` and `platform.operations.manage` capability boundaries remain authoritative
  - Users without system access remain deny-as-not-found by existing platform routing and auth guards
  - Users with view capability but without manage capability remain able to inspect runs but unable to execute triage actions

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| Surface | Surface Type | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type |
|---|---|---|---|---|---|---|---|---|---|---|---|
| System operations list | Read-only Registry / Report | Full-row click to system operation detail | required | header CTA only | none on the list | `/system/ops/runs` | `/system/ops/runs/{run}` | Platform scope only | Operations / Operation | status, outcome, operation type, workspace, tenant, recency | none |
| System failed operations list | Read-only Registry / Report | Full-row click to system operation detail | required | header CTA only | none on the list | `/system/ops/failures` | `/system/ops/runs/{run}` | Platform scope only | Operations / Operation | failed outcome, operation type, workspace, tenant, recency | none |
| System stuck operations list | Read-only Registry / Report | Full-row click to system operation detail | required | header CTA only | none on the list | `/system/ops/stuck` | `/system/ops/runs/{run}` | Platform scope only | Operations / Operation | queued or running stale state, operation type, workspace, tenant, recency | none |
| System operation detail | Detail-first Operational Surface | Dedicated detail page | forbidden | detail header groups only | detail header only | `/system/ops/runs` | `/system/ops/runs/{run}` | Platform scope only | Operations / Operation | operation truth, failure cause, context, related navigation, next actions | none |

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| Surface | Primary Persona | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|
| System operations list | Platform operator | Read-only Registry / Report | Which operation should I open next? | status, outcome, operation label, workspace, tenant, initiator, activity time | raw payloads and deeper traces stay on detail | execution outcome, recency | Read-only list | Open operation, go to runbooks | none |
| System failed operations list | Platform operator | Read-only Registry / Report | Which failed operation needs investigation first? | failed outcome, operation label, workspace, tenant, activity time | raw payloads and deeper traces stay on detail | execution outcome, failure state, recency | Read-only list | Open operation, show all operations | none |
| System stuck operations list | Platform operator | Read-only Registry / Report | Which queued or running operation has crossed the stuck threshold? | stuck class, operation label, workspace, tenant, activity time | raw payloads and deeper traces stay on detail | lifecycle stall state, recency | Read-only list | Open operation, show all operations | none |
| System operation detail | Platform operator | Detail-first Operational Surface | What happened on this operation, and what follow-up is appropriate? | operation identity, status, outcome, related scope, dominant failure or stall context, related links | low-level payloads, internal traces, and extended diagnostics | execution outcome, lifecycle state, operability context | Existing platform triage only | Show all operations, go to runbooks, retry operation, mark investigated | Cancel operation when still cancellable |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: No
- **New persisted entity/table/artifact?**: No
- **New abstraction?**: No
- **New enum/state/reason family?**: No
- **New cross-domain UI framework/taxonomy?**: No
- **Current operator problem**: The three system operations list pages currently behave like scan-first registry surfaces but also expose direct triage actions, underdefined empty states, and competing Operations versus Runs naming that duplicate or dilute the canonical detail model.
- **Existing structure is insufficient because**: The current list surfaces split triage ownership between list and detail, which makes the lists behave like mini control centers instead of scan-first registries.
- **Narrowest correct implementation**: Keep the existing system lists and the existing system operation detail page, but move triage ownership fully onto the detail page, align visible naming to Operations / Operation, and give each list one clear navigation CTA without changing persistence or introducing new surfaces.
- **Ownership cost**: Existing list and guard tests need to be updated, and operators lose direct row-level triage from the lists in exchange for one consistent detail-first follow-up model.
- **Alternative intentionally rejected**: Reclassifying the system lists into a queue or review surface was rejected because the pages are scan-first registries split by status family, not context-preserving queue workflows.
- **Release truth**: Current-release truth. The repo already contains the canonical detail page and the duplicated list triage actions; this slice removes the duplication rather than adding new capability.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Scan Lists Without Competing Actions (Priority: P1)

As a platform operator, I want the Operations, Failed operations, and Stuck operations lists to behave as scan-first registries with one obvious open path and one clear navigation CTA, so that I can inspect the right operation without row-level action clutter.

**Why this priority**: This is the direct constitution violation on the current system operations surfaces.

**Independent Test**: Can be fully tested by loading each system operations list and asserting that rows remain clickable, row-level triage actions are absent, visible labels use Operations / Operation vocabulary, and each list exposes the expected primary CTA in header and empty state.

**Acceptance Scenarios**:

1. **Given** a platform operator opens the system Operations list, **When** the table renders, **Then** each row opens the system operation detail page through row click, exposes no row-level triage actions, and keeps `Go to runbooks` as the single header and empty-state CTA.
2. **Given** a platform operator opens the system Failed operations list, **When** the table renders, **Then** the row remains clickable, the list does not expose retry, cancel, or investigate actions inline, and `Show all operations` is the single header and empty-state CTA.
3. **Given** a platform operator opens the system Stuck operations list, **When** the table renders, **Then** the row remains clickable, the list does not expose retry, cancel, or investigate actions inline, and `Show all operations` is the single header and empty-state CTA.

---

### User Story 2 - Perform Triage From The Canonical Detail Page (Priority: P1)

As a platform operator with manage capability, I want system operation triage to live on the canonical operation detail page, so that every follow-up action happens in the surface that already owns full context and keeps a clear return path to all operations.

**Why this priority**: The lists can only become constitution-compliant if the detail page becomes the single triage destination.

**Independent Test**: Can be fully tested by opening a system operation detail page as a manage-capable operator and asserting that retry, cancel, and mark investigated remain available there with the same audit and queued-run behavior, while `Show all operations` remains available as the return path.

**Acceptance Scenarios**:

1. **Given** a failed operation and a manage-capable platform operator, **When** the operator opens the system operation detail page, **Then** retry remains available on the detail header and still queues a replacement operation.
2. **Given** a cancellable operation and a manage-capable platform operator, **When** the operator opens the system operation detail page, **Then** cancel remains available on the detail header and still requires confirmation.
3. **Given** an operation that needs documentation, **When** the operator opens the system operation detail page, **Then** mark investigated remains available there, still records the investigation action, and the page keeps `Show all operations` as the canonical return link.

---

### User Story 3 - Preserve View-Only Access Semantics (Priority: P2)

As a platform operator with view-only access, I want to inspect system operations without being offered triage controls, so that the platform plane stays capability-correct while the aligned surfaces remain usable.

**Why this priority**: Surface alignment must not weaken the existing view/manage separation.

**Independent Test**: Can be fully tested by rendering list and detail surfaces for a view-only system user and asserting that inspection and navigation remain available while triage actions remain hidden.

**Acceptance Scenarios**:

1. **Given** a platform user with operations view but not operations manage, **When** the user opens any system operations list, **Then** the user can inspect rows, use the page CTA, but sees no triage actions there.
2. **Given** a platform user with operations view but not operations manage, **When** the user opens a system operation detail page, **Then** retry, cancel, and mark investigated remain hidden while `Show all operations` and `Go to runbooks` remain available.

### Edge Cases

- A failed operation appears on both the all-operations list and the failed-operations list; both surfaces must expose the same single open model and must not diverge in row actions or naming.
- A queued or running operation later becomes cancellable or non-cancellable; the list remains read-only while the detail page resolves whether cancel is available.
- The system operation detail page must keep a clear return path to the canonical Operations list even when opened from Failed operations or Stuck operations.
- Empty Operations, Failed operations, and Stuck operations states must remain explanation-first while still exposing exactly one primary CTA that matches the page contract.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no Microsoft Graph calls, no new write workflow, and no new long-running work. Existing `OperationRun` and triage services remain the underlying execution model. The feature only realigns where platform operators inspect and triage existing system runs.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** This feature adds no new structure, persistence, abstraction, or state family. It reduces surface complexity by removing duplicated triage ownership from the lists.

**Constitution alignment (OPS-UX):** Existing retry and cancel flows continue to reuse the current queued-run UX, terminal notification rules, and service-owned `OperationRun` lifecycle. This feature does not introduce a new run type or change lifecycle ownership.

**Constitution alignment (RBAC-UX):** This feature stays in the platform plane only. Existing `OPERATIONS_VIEW` and `OPERATIONS_MANAGE` capability checks remain the server-side source of truth. List alignment must not weaken the current distinction between view-only inspection and manage-capable triage.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable.

**Constitution alignment (BADGE-001):** Existing status and outcome badge semantics remain unchanged and centralized.

**Constitution alignment (UI-FIL-001):** The feature continues to use Filament-native tables, row navigation, header actions, confirmation modals, and notifications. No custom local action framework or styling language is introduced.

**Constitution alignment (UI-NAMING-001):** This slice standardizes the changed system-plane surfaces to the canonical visible nouns `Operations` and `Operation`. Existing internal PHP class names and route paths may remain stable, but operator-facing labels, headings, and return links MUST stop presenting `Runs` as the primary noun.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001):** The system Runs, Failures, and Stuck pages MUST align to the Read-only Registry / Report surface rules: one-click row open, no competing inline triage controls, and no destructive actions on the list rows. The system run detail page MUST remain the sole triage surface for retry, cancel, and mark investigated.

**Constitution alignment (OPSURF-001):** The lists remain operator-first scan surfaces that show only the truth needed to choose the next run to inspect. Full follow-up context and triage remain on the detail page, where diagnostic depth already exists.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** This feature does not add a new semantic layer. It removes duplicated action ownership and keeps tests focused on operator-visible behavior: list inspect model, detail triage ownership, and manage-vs-view capability behavior.

**Constitution alignment (Filament Action Surfaces):** The Action Surface Contract is satisfied when Operations, Failed operations, and Stuck operations expose row click only, keep bulk actions absent by explicit no-bulk need, provide one header and empty-state CTA each, and leave retry, cancel, and mark investigated to the detail header. No new exemption is introduced.

**Constitution alignment (UX-001 — Layout & Information Architecture):** List layouts remain scanable registry tables. The system run detail page remains the operational detail surface and continues to own richer follow-up actions. No create or edit layout changes are introduced.

### Functional Requirements

- **FR-170-001**: The system Operations list MUST behave as a read-only registry surface with one primary inspect model: full-row click to the canonical system operation detail page.
- **FR-170-002**: The system Failed operations list MUST behave as a read-only registry surface with one primary inspect model: full-row click to the canonical system operation detail page.
- **FR-170-003**: The system Stuck operations list MUST behave as a read-only registry surface with one primary inspect model: full-row click to the canonical system operation detail page.
- **FR-170-004**: the Operations, Failed operations, and Stuck operations lists MUST NOT render retry, cancel, or mark investigated as row actions.
- **FR-170-005**: The canonical system operation detail page MUST remain the only system-plane surface that exposes retry, cancel, and mark investigated actions.
- **FR-170-006**: Retry on the system operation detail page MUST preserve the current queued-run feedback behavior and the current link back to the newly queued operation.
- **FR-170-007**: Cancel on the system operation detail page MUST remain confirmation-gated and MUST stay available only when the current operation is still cancellable.
- **FR-170-008**: Mark investigated on the system operation detail page MUST remain confirmation-gated and MUST continue to require an operator-supplied reason.
- **FR-170-009**: View-only platform operators MUST remain able to open list rows and detail pages while triage actions remain hidden.
- **FR-170-010**: Manage-capable platform operators MUST retain triage capability on the system operation detail page after list row actions are removed.
- **FR-170-011**: Existing audit behavior for retry and mark investigated MUST remain unchanged.
- **FR-170-012**: The system operation detail page MUST provide a clear `Show all operations` return path to the canonical collection route while preserving `Go to runbooks` navigation.
- **FR-170-013**: This feature MUST NOT introduce a new page, a new system operations capability, or a new persisted artifact.
- **FR-170-014**: Repository guard tests for the system operations surfaces MUST be updated so they assert row-click-only lists, list CTAs, canonical Operations / Operation naming, and detail-owned triage instead of direct row triage.
- **FR-170-015**: The changed system surfaces MUST use `Operations` as the canonical visible collection noun and `Operation` as the canonical visible singular noun.
- **FR-170-016**: Each changed system list surface MUST expose exactly one primary empty-state CTA and the corresponding header action when records exist.

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| System operations list | `app/Filament/System/Pages/Ops/Runs.php` | `Go to runbooks` | `recordUrl()` full-row click | none | none | `Go to runbooks` | n/a | n/a | no new audit behavior | Read-only Registry / Report; visible label becomes `Operations` |
| System failed operations list | `app/Filament/System/Pages/Ops/Failures.php` | `Show all operations` | `recordUrl()` full-row click | none | none | `Show all operations` | n/a | n/a | no new audit behavior | Read-only Registry / Report; visible label becomes `Failed operations` |
| System stuck operations list | `app/Filament/System/Pages/Ops/Stuck.php` | `Show all operations` | `recordUrl()` full-row click | none | none | `Show all operations` | n/a | n/a | no new audit behavior | Read-only Registry / Report; visible label becomes `Stuck operations` |
| System operation detail | `app/Filament/System/Pages/Ops/ViewRun.php`, `resources/views/filament/system/pages/ops/view-run.blade.php` | `Show all operations`, `Go to runbooks` | n/a | n/a | n/a | n/a | `Retry`, `Cancel`, `Mark investigated` | n/a | existing retry and mark-investigated audit behavior remains | Detail-first operational owner of triage; heading and return link use `Operation` |

### Key Entities *(include if feature involves data)*

- **System operations list surface**: The system-panel Operations, Failed operations, and Stuck operations pages that scan existing `OperationRun` records.
- **System operation detail surface**: The canonical system detail page for one selected `OperationRun`.
- **System operation triage action**: Existing follow-up actions for retry, cancel, and mark investigated.

## Success Criteria *(mandatory)*

- **SC-170-001**: Operations, Failed operations, and Stuck operations each expose exactly one primary inspect model in automated coverage: row click to the canonical system operation detail page.
- **SC-170-002**: Automated coverage verifies that Operations, Failed operations, and Stuck operations expose zero row-level triage actions.
- **SC-170-003**: Automated coverage verifies that the system operation detail page still exposes retry, cancel, and mark investigated for manage-capable operators when each action is legitimately available.
- **SC-170-004**: Automated coverage verifies that view-only platform operators can inspect system operations but cannot see manage-only triage actions on the detail page.
- **SC-170-005**: Automated coverage verifies that the changed system surfaces use the canonical visible nouns `Operations` and `Operation` and expose the expected header or empty-state CTA on each list surface.
- **SC-170-006**: The feature ships without adding any new capability, persistence, or UI exemption.

## Assumptions

- The current system run detail page remains the correct canonical place for triage ownership.
- Existing audit behavior for retry and mark investigated is correct and does not need redesign in this slice.
- Existing internal route paths under `/system/ops/runs` may remain stable while visible system-surface naming is standardized in this slice.

## Non-Goals

- Renaming internal PHP class names or changing existing `/system/ops/runs` route paths
- Retrofitting deferred dashboard, onboarding, or landing surfaces
- Changing `OperationRun` lifecycle semantics, run creation behavior, or notification taxonomy
- Introducing a queue/review model for the system Operations, Failed operations, or Stuck operations pages

## Dependencies

- Existing system operations list pages: Runs, Failures, and Stuck
- Existing system run detail page
- Existing `OperationRunTriageService`
- Existing platform capability and audit behavior
- Existing action-surface and system operations guard coverage

## Definition of Done

Spec 170 is complete when the three changed system list pages are scan-first row-click-only registry surfaces, visible system naming uses Operations / Operation, each list has one matching header and empty-state CTA, the system operation detail page is the sole owner of retry/cancel/investigate triage and exposes `Show all operations`, existing view/manage capability semantics remain intact, and guard tests reflect the aligned interaction model.