ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
fdd3a85b64
TenantAtlas/specs/170-system-operations-surface-alignment/tasks.md
ahmido fdd3a85b64 feat: align system operations surfaces (#201) 
## Summary
- align the system-panel Operations, Failed operations, and Stuck operations pages to the read-only registry contract by removing inline row triage and keeping row-click inspection
- keep retry, cancel, and mark-investigated behavior on the canonical system operation detail page while adding the explicit `Show all operations` return path and updated `Operations / Operation` copy
- add and update focused Pest and Livewire coverage for list CTA behavior, detail-owned triage, and view-only versus manage-capable platform access
- add Spec 170 implementation artifacts plus the follow-on Spec 171 and Spec 172 packages

## Testing
- `vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsTriageActionsTest.php`
- `vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php`
- `vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsFailuresViewTest.php`
- `vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsStuckViewTest.php`
- integrated browser smoke on `/system/ops/runs`, `/system/ops/failures`, `/system/ops/stuck`, empty states via search filter, and detail-page retry confirmation visibility

## Notes
- branch pushed from `170-system-operations-surface-alignment`
- latest commit: `64b4d741 feat: align system operations surfaces`

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #201
2026-03-30 19:08:56 +00:00

12 KiB
Raw Blame History

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.

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

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

  • 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

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

  • 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

  • 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.
  • 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.
  • T014 [US2] Preserve existing retry, cancel, and investigation behavior without new lifecycle or audit changes in app/Services/SystemConsole/OperationRunTriageService.php.
  • 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

  • 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

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

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

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

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

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.