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

# 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.