# Tasks: System Operations Surface Alignment **Input**: Design documents from `/specs/170-system-operations-surface-alignment/` **Prerequisites**: plan.md, spec.md, research.md, data-model.md, quickstart.md, contracts/system-ops-surface-contract.yaml **Tests**: Runtime behavior changes in this repo require Pest coverage. Each story below includes test work and focused verification. **Organization**: Tasks are grouped by user story so each story can be implemented and validated independently where the current surface boundaries allow it. ## Phase 1: Setup **Purpose**: Lock the implementation targets to the generated plan artifacts before runtime edits begin. - [X] T001 Reconfirm the implementation and verification targets in `specs/170-system-operations-surface-alignment/contracts/system-ops-surface-contract.yaml` and `specs/170-system-operations-surface-alignment/quickstart.md` before editing runtime files. - [X] T002 Inspect the current system ops touchpoints in `app/Filament/System/Pages/Ops/Runs.php`, `app/Filament/System/Pages/Ops/Failures.php`, `app/Filament/System/Pages/Ops/Stuck.php`, `app/Filament/System/Pages/Ops/ViewRun.php`, `tests/Feature/System/Spec114/OpsTriageActionsTest.php`, and `tests/Feature/Guards/ActionSurfaceContractTest.php` so every direct row-triage assertion is mapped to the aligned target behavior. --- ## Phase 2: Foundational **Purpose**: Establish the shared regression baseline that all story work must satisfy. **⚠️ CRITICAL**: No user story work should be considered complete until these shared assertions are updated. - [X] T003 Update the shared system surface regression contract in `tests/Feature/Guards/ActionSurfaceContractTest.php` so the baseline expects clickable rows, canonical `Operations` naming, explicit list CTA behavior, and no row triage on the changed system pages. - [X] T004 Update the shared system triage and navigation scenario coverage in `tests/Feature/System/Spec114/OpsTriageActionsTest.php` so list-surface, detail-surface, view-only, and `Show all operations` assertions can be expressed separately. **Checkpoint**: Shared contract coverage is ready; story implementation can now proceed. --- ## Phase 3: User Story 1 - Scan Lists Without Competing Actions (Priority: P1) 🎯 MVP **Goal**: Make the Operations, Failed operations, and Stuck operations pages behave as scan-first registry surfaces with row-click-only inspection, stable naming, and one clear CTA each. **Independent Test**: Load each list page and verify `recordUrl()` row navigation remains intact, all row-level triage actions are absent, visible copy uses `Operations` / `Operation`, and the correct single CTA appears in both header and empty state. ### Tests for User Story 1 - [X] T005 [US1] Add failing list-behavior and CTA assertions in `tests/Feature/System/Spec114/OpsTriageActionsTest.php` that require row-click-only behavior, canonical `Operations` naming, and the correct single CTA on the changed system lists. ### Implementation for User Story 1 - [X] T006 [P] [US1] Remove `retry`, `cancel`, and `mark_investigated` row actions, rename the visible label to `Operations`, add the `Go to runbooks` header and empty-state CTA, and update the action-surface declaration wording in `app/Filament/System/Pages/Ops/Runs.php`. - [X] T007 [P] [US1] Remove `retry`, `cancel`, and `mark_investigated` row actions, rename the visible label to `Failed operations`, add the `Show all operations` header and empty-state CTA, and update the action-surface declaration wording in `app/Filament/System/Pages/Ops/Failures.php`. - [X] T008 [P] [US1] Remove `retry`, `cancel`, and `mark_investigated` row actions, rename the visible label to `Stuck operations`, add the `Show all operations` header and empty-state CTA, and update the action-surface declaration wording in `app/Filament/System/Pages/Ops/Stuck.php`. - [X] T009 [US1] Verify the three list pages still use `recordUrl()` and expose the correct CTA behavior in `app/Filament/System/Pages/Ops/Runs.php`, `app/Filament/System/Pages/Ops/Failures.php`, and `app/Filament/System/Pages/Ops/Stuck.php`. - [X] T010 [US1] Run the focused list-surface regression checks in `tests/Feature/Guards/ActionSurfaceContractTest.php` and `tests/Feature/System/Spec114/OpsTriageActionsTest.php`. **Checkpoint**: The three system list pages are row-click-only registry surfaces and can be validated independently. --- ## Phase 4: User Story 2 - Perform Triage From The Canonical Detail Page (Priority: P1) **Goal**: Keep the existing `ViewRun` page as the sole triage surface for retry, cancel, and mark investigated while exposing `Show all operations` as the canonical return path. **Independent Test**: Open a system operation detail page as a manage-capable platform user and verify header-based retry, cancel, and mark-investigated behavior still works with the same queued-toast, confirmation, and audit expectations, while `Show all operations` and `Go to runbooks` remain available. ### Tests for User Story 2 - [X] T011 [US2] Add failing detail-page triage and return-path assertions in `tests/Feature/System/Spec114/OpsTriageActionsTest.php` for `Retry`, `Cancel`, `Mark investigated`, `Show all operations`, and visible `Operation` copy on `app/Filament/System/Pages/Ops/ViewRun.php`. ### Implementation for User Story 2 - [X] T012 [US2] Keep `app/Filament/System/Pages/Ops/ViewRun.php` as the sole triage owner and ensure header actions expose `Show all operations`, `Go to runbooks`, and the existing manage-only triage behavior through `app/Support/System/SystemOperationRunLinks.php`. - [X] T013 [US2] Update the visible detail copy and return-link presentation in `resources/views/filament/system/pages/ops/view-run.blade.php` so the page uses `Operation #...` and shows `Show all operations` alongside `Go to runbooks`. - [X] T014 [US2] Preserve existing retry, cancel, and investigation behavior without new lifecycle or audit changes in `app/Services/SystemConsole/OperationRunTriageService.php`. - [X] T015 [US2] Run the focused detail-triage and return-path checks in `tests/Feature/System/Spec114/OpsTriageActionsTest.php`. **Checkpoint**: Detail-page triage ownership is intact and independently verified. --- ## Phase 5: User Story 3 - Preserve View-Only Access Semantics (Priority: P2) **Goal**: Preserve the existing view/manage capability split so view-only operators can inspect and navigate but not triage. **Independent Test**: Render the aligned list and detail surfaces for a view-only platform user and verify inspection and navigation remain available while triage actions stay hidden. ### Tests for User Story 3 - [X] T016 [US3] Add failing view-only authorization assertions in `tests/Feature/System/Spec114/OpsTriageActionsTest.php` covering list inspection, visible CTA navigation, and hidden detail-header triage. ### Implementation for User Story 3 - [X] T017 [US3] Keep manage-only detail action visibility intact in `app/Filament/System/Pages/Ops/ViewRun.php` while preserving view access and list CTA visibility in `app/Filament/System/Pages/Ops/Runs.php`, `app/Filament/System/Pages/Ops/Failures.php`, and `app/Filament/System/Pages/Ops/Stuck.php`. - [X] T018 [US3] Reconfirm platform operations access expectations in `tests/Feature/System/Spec114/OpsFailuresViewTest.php` and `tests/Feature/System/Spec114/OpsStuckViewTest.php` after the surface alignment changes. - [X] T019 [US3] Run the focused authorization checks in `tests/Feature/System/Spec114/OpsTriageActionsTest.php`, `tests/Feature/System/Spec114/OpsFailuresViewTest.php`, and `tests/Feature/System/Spec114/OpsStuckViewTest.php`. **Checkpoint**: View-only operators can inspect aligned system surfaces without gaining triage controls. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Final cleanup and verification across all stories. - [X] T020 Run formatting with `vendor/bin/sail bin pint --dirty --format agent` for `app/Filament/System/Pages/Ops/Runs.php`, `app/Filament/System/Pages/Ops/Failures.php`, `app/Filament/System/Pages/Ops/Stuck.php`, `app/Filament/System/Pages/Ops/ViewRun.php`, `resources/views/filament/system/pages/ops/view-run.blade.php`, `tests/Feature/System/Spec114/OpsTriageActionsTest.php`, and `tests/Feature/Guards/ActionSurfaceContractTest.php`. - [X] T021 Run the full focused regression pack from `specs/170-system-operations-surface-alignment/quickstart.md` against `tests/Feature/Guards/ActionSurfaceContractTest.php`, `tests/Feature/System/Spec114/OpsTriageActionsTest.php`, `tests/Feature/System/Spec114/OpsFailuresViewTest.php`, and `tests/Feature/System/Spec114/OpsStuckViewTest.php`. - [X] T022 Validate the final behavior against `specs/170-system-operations-surface-alignment/contracts/system-ops-surface-contract.yaml` and `specs/170-system-operations-surface-alignment/quickstart.md` before handoff. --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies. - **Foundational (Phase 2)**: Depends on Setup and establishes the shared regression baseline. - **User Story 1 (Phase 3)**: Depends on Foundational. - **User Story 2 (Phase 4)**: Depends on Foundational. - **User Story 3 (Phase 5)**: Depends on User Story 1 and User Story 2 because it validates the final aligned list-plus-detail authorization and navigation behavior. - **Polish (Phase 6)**: Depends on the desired user stories being complete. ### User Story Dependencies - **US1**: Independent after Phase 2; it only changes list-surface semantics. - **US2**: Independent after Phase 2; it preserves existing detail-surface triage ownership. - **US3**: Validates the final permission split across the aligned list and detail surfaces, so it should run after US1 and US2 settle the interaction model. ### Within Each User Story - Update story-specific tests first and make them fail for the intended new behavior. - Apply source changes next. - Run the smallest focused verification pack before moving on. --- ## Parallel Opportunities - T006, T007, and T008 can run in parallel because they modify different list-page files. - US1 and US2 can proceed in parallel after Phase 2 if test-file coordination is handled deliberately. - Polish verification can start as soon as the last required story is merged locally. --- ## Parallel Example: User Story 1 ```bash Task: "T006 Remove row triage actions in app/Filament/System/Pages/Ops/Runs.php" Task: "T007 Remove row triage actions in app/Filament/System/Pages/Ops/Failures.php" Task: "T008 Remove row triage actions in app/Filament/System/Pages/Ops/Stuck.php" ``` --- ## Parallel Example: User Story 2 ```bash Task: "T011 Add detail-page triage and return-path assertions in tests/Feature/System/Spec114/OpsTriageActionsTest.php" Task: "T013 Update visible detail copy in resources/views/filament/system/pages/ops/view-run.blade.php" ``` --- ## Parallel Example: User Story 3 ```bash Task: "T016 Add view-only authorization assertions in tests/Feature/System/Spec114/OpsTriageActionsTest.php" Task: "T018 Reconfirm access expectations in tests/Feature/System/Spec114/OpsFailuresViewTest.php and tests/Feature/System/Spec114/OpsStuckViewTest.php" ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup. 2. Complete Phase 2: Foundational. 3. Complete Phase 3: User Story 1. 4. Validate the row-click-only list behavior with the focused regression pack. 5. Demo the aligned registry surfaces before touching any further hardening. ### Incremental Delivery 1. Finish Setup + Foundational to lock the shared regression baseline. 2. Deliver US1 to normalize the list surfaces. 3. Deliver US2 to prove detail-page triage remains the sole operational owner and preserves the canonical return path. 4. Deliver US3 to confirm the final view/manage capability split. 5. Run Phase 6 polish checks and hand off. ### Parallel Team Strategy 1. One engineer updates the shared regression baseline in Phase 2. 2. After Phase 2: - Engineer A can take US1 list-page updates. - Engineer B can take US2 detail-page preservation work. 3. Once US1 and US2 land locally, a final pass can execute US3 authorization hardening and the polish phase. --- ## Notes - `[P]` tasks touch different files and have no unfinished dependencies. - Story labels map directly to the three user stories in `spec.md`. - This feature intentionally avoids route renames, capability changes, schema changes, and new UI exemptions. - Keep `OperationRunTriageService` narrow unless a behavior-preserving tweak is genuinely required.