# Tasks: Canonical Operation Viewer Context Decoupling

**Input**: Design documents from `/specs/144-canonical-operation-viewer-context-decoupling/`
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/routes.md, quickstart.md

**Tests**: Required. This feature changes runtime behavior in canonical routing, authorization, and viewer UX, so Pest coverage must be added or updated before implementation is considered complete.
**Operations**: No new `OperationRun` type, no new queued work, and no changes to the Ops-UX notification contract are introduced. Existing canonical `OperationRun` behavior and `View run` routing remain in place.
**RBAC**: This feature changes authorization behavior in the admin plane. Tasks must preserve explicit 404 vs 403 semantics, use existing Gate or Policy enforcement, and avoid raw capability strings or role checks.
**UI Naming**: Any added banner or helper copy must preserve existing operator-facing vocabulary around `View run`, `Back to Operations`, current tenant context, and canonical workspace view.
**Filament UI Action Surfaces**: Existing action surfaces remain in scope. No new destructive action is introduced; existing `Resume capture` confirmation behavior must remain intact.
**Filament UI UX-001**: The canonical run page remains an infolist-based detail surface and the operations index remains a table surface; tasks must preserve that layout.

**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Create the spec-specific regression test files and implementation workspace for Spec 144.

- [X] T001 Create the spec-specific Pest files `tests/Feature/144/CanonicalOperationViewerContextMismatchTest.php` and `tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Lock the shared canonical-route and context-resolution baseline before user story work begins.

**⚠️ CRITICAL**: No user story work should begin until this phase is complete.

- [X] T002 [P] Extend `tests/Feature/OpsUx/OperateHubShellTest.php` with canonical `/admin/operations/{run}` remembered-vs-Filament tenant resolution coverage
- [X] T003 [P] Extend `tests/Feature/Monitoring/HeaderContextBarTest.php` with canonical run-page header context expectations for mismatched and missing tenant context
- [X] T004 Update `app/Support/Middleware/EnsureFilamentTenantSelected.php` and `app/Support/OperateHub/OperateHubShell.php` so canonical `/admin/operations/{run}` and related `/livewire/update` requests remain convenience-only, never force tenant-selection validity gates, and preserve a reusable canonical-viewer rule for future workspace-level record viewers

**Checkpoint**: Canonical route guardrails and context-resolution baselines are in place for all stories.

---

## Phase 3: User Story 1 - Open A Canonical Run Reliably (Priority: P1) 🎯 MVP

**Goal**: Keep canonical run viewing valid whenever the run exists and the actor is authorized, regardless of remembered tenant-context mismatch.

**Independent Test**: Open `/admin/operations/{run}` for an authorized tenant-linked run while a different tenant is selected, and verify the viewer renders. Open a tenantless run and verify it also renders. Verify non-entitled access remains 404 and in-scope capability denial remains 403.

### Tests for User Story 1

- [X] T005 [P] [US1] Extend `tests/Feature/Operations/TenantlessOperationRunViewerTest.php` with mismatched-header-tenant success coverage and tenantless-run success coverage for `/admin/operations/{run}`
- [X] T006 [P] [US1] Extend `tests/Feature/RunAuthorizationTenantIsolationTest.php` with canonical run-detail 404 deny-as-not-found and 403 capability-denial assertions

### Implementation for User Story 1

- [X] T007 [US1] Refine `app/Policies/OperationRunPolicy.php` so canonical run authorization remains run-first, workspace-scoped, and directly tenant-entitlement-based with no remembered-context coupling
- [X] T008 [US1] Update `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` so `mount()` and any derived state helpers preserve canonical run validity independently of selected tenant context
- [X] T009 [US1] Run focused US1 verification in `tests/Feature/Operations/TenantlessOperationRunViewerTest.php` and `tests/Feature/RunAuthorizationTenantIsolationTest.php`

**Checkpoint**: Canonical run legitimacy is independent of remembered tenant context and still preserves 404 vs 403 authorization semantics.

---

## Phase 4: User Story 2 - Trust Deep Links From Other Surfaces (Priority: P1)

**Goal**: Keep `View run` deep links canonical and self-sufficient from tenant pages, monitoring surfaces, notification-style entry points, and verification surfaces.

**Independent Test**: Open canonical run links generated from a tenant page, a notification-style entry point, and a workspace verification or monitoring surface while changing or clearing the current header tenant, and verify each link still resolves to the correct run viewer.

### Tests for User Story 2

- [X] T010 [P] [US2] Add tenant-page, notification-style, and verification-surface deep-link trust coverage to `tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php`
- [X] T011 [P] [US2] Extend `tests/Feature/OpsUx/CanonicalViewRunLinksTest.php` and `tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php` for canonical run-route continuity under changed or missing header tenant context across monitoring and verification surfaces

### Implementation for User Story 2

- [X] T012 [US2] Keep canonical run-link generation normalized through `app/Support/OperationRunLinks.php` and update any touched canonical-route or lifecycle-safe follow-up expectations in `tests/Feature/OpsUx/CanonicalViewRunLinksTest.php`
- [X] T013 [US2] Update `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` so canonical navigation context and header or follow-up actions remain self-sufficient and lifecycle-safe after deep-link entry regardless of prior tenant context
- [X] T014 [US2] Run focused US2 verification in `tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php`, `tests/Feature/OpsUx/CanonicalViewRunLinksTest.php`, and `tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php`

**Checkpoint**: Canonical run links remain dependable from tenant pages, notifications, verification surfaces, and monitoring surfaces.

---

## Phase 5: User Story 3 - Understand Context And Lifecycle Without Being Blocked (Priority: P2)

**Goal**: Show non-blocking context and lifecycle messaging so operators can distinguish mismatch, tenantless, onboarding, archived, and selector-excluded states without mistaking them for access failure or over-trusting follow-up actions.

**Independent Test**: Open canonical runs for matching tenant, mismatched tenant, tenantless, onboarding-tenant, archived-tenant, and selector-excluded scenarios, and verify the page stays viewable with the correct informational banner or framing plus lifecycle-safe follow-up action treatment.

### Tests for User Story 3

- [X] T015 [P] [US3] Add mismatch, tenantless, onboarding, archived, and selector-excluded banner assertions to `tests/Feature/144/CanonicalOperationViewerContextMismatchTest.php`
- [X] T016 [P] [US3] Extend `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php` and `tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php` for non-blocking context, lifecycle presentation, and lifecycle-safe follow-up affordances

### Implementation for User Story 3

- [X] T017 [US3] Add derived canonical viewer banner and follow-up-affordance state in `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` for run tenant, current header tenant, tenantless, and selector-excluded lifecycle scenarios
- [X] T018 [US3] Render the non-blocking canonical context and lifecycle banner in `resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php` above the existing redaction note and infolist, with reduced follow-up actions handled safely when unavailable
- [X] T019 [US3] Adjust display wording or fallback handling in `app/Support/OperateHub/OperateHubShell.php` only as needed to keep banner, return-affordance, and reduced follow-up-action language aligned with remembered-context semantics
- [X] T020 [US3] Run focused US3 verification in `tests/Feature/144/CanonicalOperationViewerContextMismatchTest.php`, `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`, and `tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php`

**Checkpoint**: Canonical run viewing stays accessible and explains mismatch and lifecycle state clearly without blocking the page or overstating available follow-up actions.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Preserve convenience-only operations-index behavior, run the full focused regression pack, and finalize formatting.

- [X] T021 [P] Validate convenience-only tenant-prefilter behavior in `tests/Feature/Monitoring/OperationsTenantScopeTest.php` after viewer hardening changes
- [X] T022 [P] Re-run shared canonical-context regressions in `tests/Feature/OpsUx/OperateHubShellTest.php` and `tests/Feature/Monitoring/HeaderContextBarTest.php`, confirming the canonical-viewer rule remains reusable beyond operation-run-specific wording
- [X] T023 Format touched files, including `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`, `app/Policies/OperationRunPolicy.php`, `app/Support/OperateHub/OperateHubShell.php`, `app/Support/Middleware/EnsureFilamentTenantSelected.php`, `app/Support/OperationRunLinks.php`, and `resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php`, with `vendor/bin/sail bin pint --dirty --format agent`
- [X] T024 Run the full focused verification command documented in `specs/144-canonical-operation-viewer-context-decoupling/quickstart.md`

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies; start immediately.
- **Foundational (Phase 2)**: Depends on Setup; blocks all user stories.
- **User Story 1 (Phase 3)**: Starts after Foundational; establishes the MVP legitimacy boundary.
- **User Story 2 (Phase 4)**: Starts after Foundational; final verification is safer after User Story 1 because deep-link trust depends on canonical viewer legitimacy being correct.
- **User Story 3 (Phase 5)**: Starts after User Story 1 because it layers UX messaging on the validated canonical viewer semantics.
- **Polish (Phase 6)**: Depends on the desired user stories being complete.

### User Story Dependencies

- **US1**: No dependency on other stories after Foundational; this is the MVP slice.
- **US2**: Can begin after Foundational, but should merge after US1 to avoid deep-link tests masking viewer-legitimacy issues.
- **US3**: Depends on US1's run-validity behavior and should be applied after the canonical viewer semantics are stable.

### Within Each User Story

- Tests must be written or updated first and must fail before implementation.
- Authorization boundary changes come before presentation changes.
- Viewer logic changes come before Blade wrapper changes.
- Focused test runs complete each story before the next story is closed.

### Parallel Opportunities

- T002 and T003 can run in parallel.
- T005 and T006 can run in parallel.
- T010 and T011 can run in parallel.
- T015 and T016 can run in parallel.
- T021 and T022 can run in parallel.

---

## Parallel Example: User Story 1

```bash
# Launch the US1 regression updates together:
Task: "Extend tests/Feature/Operations/TenantlessOperationRunViewerTest.php with mismatched-header-tenant and tenantless-run coverage"
Task: "Extend tests/Feature/RunAuthorizationTenantIsolationTest.php with canonical run-detail 404 and 403 assertions"
```

## Parallel Example: User Story 2

```bash
# Launch the US2 deep-link coverage updates together:
Task: "Add tenant-page, notification-style, and verification-surface deep-link trust coverage to tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php"
Task: "Extend tests/Feature/OpsUx/CanonicalViewRunLinksTest.php and tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php for canonical route continuity"
```

## Parallel Example: User Story 3

```bash
# Launch the US3 messaging coverage updates together:
Task: "Add mismatch, tenantless, onboarding, archived, and selector-excluded banner assertions to tests/Feature/144/CanonicalOperationViewerContextMismatchTest.php"
Task: "Extend tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php and tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php"
```

---

## Implementation Strategy

### MVP First

Deliver **User Story 1** first. That gives the repo the core guarantee that canonical run validity is no longer coupled to remembered tenant context.

### Incremental Delivery

1. Complete Setup and Foundational work.
2. Deliver US1 and validate canonical 404 vs 403 semantics.
3. Deliver US2 to prove deep-link trust across source surfaces.
4. Deliver US3 to add transparent, non-blocking context and lifecycle messaging.
5. Finish with the cross-cutting regression and formatting sweep.

### Validation Standard

No phase is complete until its focused Pest files pass. The full focused command in `specs/144-canonical-operation-viewer-context-decoupling/quickstart.md` is the final acceptance gate before implementation is considered ready for review.
