# Tasks: Canonical Tenant Context Resolution

**Input**: Design documents from `/specs/135-canonical-tenant-context-resolution/`  
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/context-resolution-matrix.yaml`, `quickstart.md`

**Tests**: Tests are REQUIRED for this feature because it changes runtime behavior across existing Filament admin flows, filter persistence, direct-record access, and search safety.

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Create the focused documentation and regression entry points used by the implementation slices.

- [X] T001 Create the focused regression test entry points in `tests/Feature/Monitoring/OperationsKpiHeaderTenantContextTest.php`, `tests/Feature/Filament/EntraGroupAdminScopeTest.php`, `tests/Feature/Filament/EntraGroupGlobalSearchScopeTest.php`, and `tests/Feature/Guards/AdminTenantResolverGuardTest.php`
- [X] T002 Create the durable architecture note and residual admin call-site inventory entry point in `docs/research/canonical-tenant-context-resolution.md`
- [X] T003 [P] Align the verification references in `specs/135-canonical-tenant-context-resolution/quickstart.md` and `specs/135-canonical-tenant-context-resolution/contracts/context-resolution-matrix.yaml` with the final implementation slices

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Lock in the single public admin resolver rule, explicit per-surface no-context behavior, shared context display, and reusable admin reference pattern before story-specific remediation begins.

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

- [X] T004 Define `app/Support/OperateHub/OperateHubShell.php::activeEntitledTenant(request())` as the only public admin resolver, keep any helpers internal-only, and codify Filament-wins conflict precedence plus explicit no-context outcomes in `app/Support/OperateHub/OperateHubShell.php` and `app/Support/Workspaces/WorkspaceContext.php`
- [X] T005 [P] Add remembered-only, Filament-only, conflict, and no-context resolver coverage in `tests/Feature/OpsUx/OperateHubShellTest.php`
- [X] T006 [P] Align shared admin context display with the canonical resolver in `resources/views/filament/partials/context-bar.blade.php` and `tests/Feature/Monitoring/HeaderContextBarTest.php`
- [X] T007 [P] Document the admin-versus-tenant panel rule, exact no-context outcomes per in-scope surface, approved exception inventory, and residual admin call-site inventory in `docs/research/canonical-tenant-context-resolution.md`
- [X] T008 Preserve `app/Filament/Resources/AlertDeliveryResource.php` and `app/Filament/Resources/AlertDeliveryResource/Pages/ListAlertDeliveries.php` as the non-regression admin reference pattern, extracting only the smallest reusable filter-persistence helper if a minimal extraction is necessary

**Checkpoint**: The canonical rule, shared resolver behavior, and reusable admin reference pattern are ready; user-story work can now begin.

---

## Phase 3: User Story 1 - Trust The Visible Tenant Context (Priority: P1) 🎯 MVP

**Goal**: Make the workspace-admin operations shell, KPI widget, and related detail affordances resolve one tenant context per request.

**Independent Test**: Load the operations monitoring flow under remembered-only, Filament-only, conflict, and no-context request states and verify that the header, KPIs, table scope, and run-detail affordances all resolve the same tenant or the same safe bounded outcome.

### Tests for User Story 1

- [X] T009 [P] [US1] Extend operations-shell parity coverage in `tests/Feature/Spec085/OperationsIndexHeaderTest.php` and `tests/Feature/Monitoring/OperationsTenantScopeTest.php`, including the explicit workspace-scoped `All tenants` no-context state
- [X] T010 [P] [US1] Add KPI tenant-context coverage in `tests/Feature/Monitoring/OperationsKpiHeaderTenantContextTest.php` and `tests/Feature/078/KpiHeaderTenantlessTest.php`
- [X] T011 [P] [US1] Extend run-detail context-affordance and authorization coverage in `tests/Feature/Spec085/RunDetailBackAffordanceTest.php` and `tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php`, including positive access plus `404` for out-of-scope tenant-bound runs

### Implementation for User Story 1

- [X] T012 [US1] Update `app/Filament/Widgets/Operations/OperationsKpiHeader.php` to resolve tenant context only through `app/Support/OperateHub/OperateHubShell.php` and keep polling safe when no canonical tenant exists
- [X] T013 [US1] Update `app/Filament/Pages/Monitoring/Operations.php` so header actions, scope labels, tab queries, table filter state, and the no-context `All tenants` view all use the same canonical admin tenant contract
- [X] T014 [US1] Update `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` and `app/Filament/Resources/OperationRunResource.php` so run-detail affordances stay aligned with the canonical operations context and enforce the documented no-context detail rule

**Checkpoint**: User Story 1 is complete when the operations monitoring shell and its KPI widget no longer drift from each other across all four request states.

---

## Phase 4: User Story 2 - Use Filters And Detail Links Safely (Priority: P1)

**Goal**: Keep tenant-sensitive filters, persisted filter state, direct record access, and global-search entry points within the same scope contract as the visible list.

**Independent Test**: Use the operations and Entra group flows from list pages, persisted filters, direct URLs, and search entry points while switching tenant context between requests, and verify that filters, records, and search results never exceed the current canonical scope.

### Tests for User Story 2

- [X] T015 [P] [US2] Add OperationRun filter default, filter-option, persisted-state, and positive or negative admin detail-authorization coverage in `tests/Feature/Filament/OperationRunListFiltersTest.php` and `tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php`
- [X] T016 [P] [US2] Add Entra group admin list and detail scope coverage plus explicit `404` versus `403` authorization coverage in `tests/Feature/Filament/EntraGroupAdminScopeTest.php` and `tests/Feature/Filament/EntraGroupEnterpriseDetailPageTest.php`
- [X] T017 [P] [US2] Add Entra group global-search parity coverage and non-member-safe no-result coverage in `tests/Feature/Filament/EntraGroupGlobalSearchScopeTest.php` and `tests/Feature/Filament/EntraGroupResolvedReferencePresentationTest.php`

### Implementation for User Story 2

- [X] T018 [US2] Harden tenant-sensitive filter defaults, option builders, and workspace-bounded list queries in `app/Filament/Resources/OperationRunResource.php`
- [X] T019 [US2] Apply the alert-delivery persisted-filter seeding pattern from `app/Filament/Resources/AlertDeliveryResource.php` and `app/Filament/Resources/AlertDeliveryResource/Pages/ListAlertDeliveries.php` to `app/Filament/Pages/Monitoring/Operations.php` and `app/Filament/Resources/OperationRunResource.php`
- [X] T020 [US2] Align tenantless operation-run detail authorization and deep-link behavior in `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` and `app/Filament/Resources/OperationRunResource.php`, using `404` for out-of-scope tenant-bound records and no broader no-context lookup path
- [X] T021 [US2] Harden admin list, direct-record, and view scoping in `app/Filament/Resources/EntraGroupResource.php`, `app/Filament/Resources/EntraGroupResource/Pages/ListEntraGroups.php`, and `app/Filament/Resources/EntraGroupResource/Pages/ViewEntraGroup.php`, with deny-as-not-found as the explicit admin no-context outcome
- [X] T022 [US2] Make Entra group global search tenant-safe or explicitly disable it in `app/Filament/Resources/EntraGroupResource.php` and `app/Filament/Concerns/ScopesGlobalSearchToTenant.php`, returning no tenant-owned admin search results when no canonical admin tenant exists
- [X] T023 [US2] Preserve canonical related links after Entra group scope hardening in `app/Support/References/Resolvers/EntraGroupReferenceResolver.php` and `app/Support/OperationRunLinks.php`

**Checkpoint**: User Story 2 is complete when OperationRun and Entra group list, detail, filter, and search paths all obey one bounded scope contract.

---

## Phase 5: User Story 3 - Preserve Separate Panel Semantics (Priority: P2)

**Goal**: Keep tenant-panel-native behavior intact while enforcing the canonical admin resolver only in workspace-admin flows.

**Independent Test**: Verify that tenant-panel files continue to use panel-native tenant behavior while admin-panel flows use the canonical admin resolver, with no cross-plane mutation or hidden fallback semantics.

### Tests for User Story 3

- [X] T024 [P] [US3] Add panel-semantics non-regression coverage in `tests/Feature/Monitoring/HeaderContextBarTest.php`, `tests/Feature/Spec085/CanonicalMonitoringDoesNotMutateTenantContextTest.php`, and `tests/Feature/OpsUx/OperateHubShellTest.php`

### Implementation for User Story 3

- [X] T025 [US3] Preserve tenant-panel-native selection and remember-last-tenant flows in `app/Filament/Pages/ChooseTenant.php`, `app/Http/Controllers/SelectTenantController.php`, and `app/Support/Middleware/EnsureFilamentTenantSelected.php`
- [X] T026 [US3] Preserve panel-aware Entra group navigation semantics in `app/Support/References/Resolvers/EntraGroupReferenceResolver.php` and `app/Support/OperationRunLinks.php`
- [X] T027 [US3] Keep tenant-panel global-search and record-resolution semantics explicit while admin paths stay canonical in `app/Filament/Concerns/ScopesGlobalSearchToTenant.php` and `app/Filament/Resources/EntraGroupResource.php`

**Checkpoint**: User Story 3 is complete when admin hardening no longer risks changing legitimate tenant-panel semantics.

---

## Phase 6: User Story 4 - Prevent Regressions Cheaply (Priority: P3)

**Goal**: Add a lightweight architectural guard and a focused non-regression suite so new admin-panel code cannot quietly reintroduce raw tenant-panel-native tenant reads.

**Independent Test**: Run the new architecture guard plus the focused alert-delivery and operations regression suite and verify that disallowed admin-panel raw tenant reads fail with actionable output while approved tenant-panel exceptions stay allowed.

### Tests for User Story 4

- [X] T028 [P] [US4] Implement the raw admin-tenant-read guard in `tests/Feature/Guards/AdminTenantResolverGuardTest.php` for `app/Filament/Pages/Monitoring`, `app/Filament/Pages/Operations`, `app/Filament/Resources`, and `app/Filament/Widgets/Operations`
- [X] T029 [P] [US4] Add non-regression coverage for the alert-delivery reference pattern in `tests/Feature/Filament/Alerts/AlertsKpiHeaderTest.php` and `tests/Feature/Alerts/AlertDeliveryDeepLinkFiltersTest.php`

### Implementation for User Story 4

- [X] T030 [US4] Maintain the executable allowlist and reviewer-facing exception notes in `tests/Feature/Guards/AdminTenantResolverGuardTest.php` so it stays aligned with the documented exception inventory

**Checkpoint**: User Story 4 is complete when new disallowed admin-panel tenant reads fail CI cheaply and the approved exception set stays explicit.

---

## Phase 7: Polish & Cross-Cutting Concerns

**Purpose**: Finalize wording, run the focused verification pack, and format touched files.

- [X] T031 [P] Reconcile operator-facing scope-label and safe-state copy in `app/Support/OperateHub/OperateHubShell.php`, `app/Filament/Pages/Monitoring/Operations.php`, and `resources/views/filament/partials/context-bar.blade.php`
- [X] T032 Run the focused validation commands documented in `specs/135-canonical-tenant-context-resolution/quickstart.md`
- [X] T033 Run formatting on touched files with `vendor/bin/sail bin pint --dirty --format agent` from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas`

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies; can start immediately.
- **Foundational (Phase 2)**: Depends on Setup completion; blocks all user-story implementation.
- **User Stories (Phases 3-6)**: Depend on Foundational completion.
- **Polish (Phase 7)**: Depends on the desired user stories being complete.

### User Story Dependencies

- **User Story 1 (P1)**: Starts after Foundational and delivers the MVP by aligning the operations monitoring shell and KPI widget.
- **User Story 2 (P1)**: Starts after Foundational and can run in parallel with US1, but it should land after T004-T008 so it reuses the canonical resolver and alert-delivery reference pattern.
- **User Story 3 (P2)**: Starts after Foundational and should land before release so tenant-panel semantics remain explicitly protected.
- **User Story 4 (P3)**: Depends on the in-scope remediation work from US1-US3 so the final guardrail can reflect the intended allowlist and forbidden admin paths.

### Within Each User Story

- Write or update the story tests first and confirm they fail against pre-change behavior.
- Land shared resolver and scoping logic before adjusting page or resource affordances that consume it.
- Keep list, detail, deep-link, and global-search behavior aligned before closing the story.
- Finish story-level validation before moving to the next priority.

### Parallel Opportunities

- T003 can run in parallel with T001-T002 once the feature directory exists.
- T005-T007 can run in parallel after T004, while T008 completes the reusable admin reference pattern.
- In US1, T009-T011 can run in parallel before T012-T014.
- In US2, T015-T017 can run in parallel before T018-T023.
- In US3, T024 can run before T025-T027, and T026 can run in parallel with T025 once the test expectations are fixed.
- In US4, T028 and T029 can run in parallel before T030.
- T031 can run in parallel with T032 after the story phases are complete.

---

## Parallel Example: User Story 1

```bash
# Launch the US1 regression updates together:
Task: "Extend operations-shell parity coverage in tests/Feature/Spec085/OperationsIndexHeaderTest.php and tests/Feature/Monitoring/OperationsTenantScopeTest.php"
Task: "Add KPI tenant-context coverage in tests/Feature/Monitoring/OperationsKpiHeaderTenantContextTest.php and tests/Feature/078/KpiHeaderTenantlessTest.php"
Task: "Extend run-detail context-affordance coverage in tests/Feature/Spec085/RunDetailBackAffordanceTest.php and tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php"
```

---

## Parallel Example: User Story 2

```bash
# Launch the US2 regression updates together:
Task: "Add OperationRun filter default, filter-option, and persisted-state coverage in tests/Feature/Filament/OperationRunListFiltersTest.php and tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php"
Task: "Add Entra group admin list and detail scope coverage in tests/Feature/Filament/EntraGroupAdminScopeTest.php and tests/Feature/Filament/EntraGroupEnterpriseDetailPageTest.php"
Task: "Add Entra group global-search parity coverage in tests/Feature/Filament/EntraGroupGlobalSearchScopeTest.php and tests/Feature/Filament/EntraGroupResolvedReferencePresentationTest.php"
```

---

## Parallel Example: User Story 3

```bash
# Launch the US3 protection work together:
Task: "Add panel-semantics non-regression coverage in tests/Feature/Monitoring/HeaderContextBarTest.php, tests/Feature/Spec085/CanonicalMonitoringDoesNotMutateTenantContextTest.php, and tests/Feature/OpsUx/OperateHubShellTest.php"
Task: "Preserve tenant-panel-native selection and remember-last-tenant flows in app/Filament/Pages/ChooseTenant.php, app/Http/Controllers/SelectTenantController.php, and app/Support/Middleware/EnsureFilamentTenantSelected.php"
Task: "Preserve panel-aware Entra group navigation semantics in app/Support/References/Resolvers/EntraGroupReferenceResolver.php and app/Support/OperationRunLinks.php"
```

---

## Parallel Example: User Story 4

```bash
# Launch the US4 guardrail work together:
Task: "Implement the raw admin-tenant-read guard in tests/Feature/Guards/AdminTenantResolverGuardTest.php for app/Filament/Pages/Monitoring, app/Filament/Pages/Operations, app/Filament/Resources, and app/Filament/Widgets/Operations"
Task: "Add non-regression coverage for the alert-delivery reference pattern in tests/Feature/Filament/Alerts/AlertsKpiHeaderTest.php and tests/Feature/Alerts/AlertDeliveryDeepLinkFiltersTest.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 operations monitoring shell across remembered-only, Filament-only, conflict, and no-context states before moving on.

### Incremental Delivery

1. Finish Setup and Foundational shared resolver work.
2. Deliver User Story 1 to establish canonical operations context parity.
3. Deliver User Story 2 to harden filters, persisted state, direct record access, and global search.
4. Deliver User Story 3 to preserve tenant-panel semantics while admin behavior is tightened.
5. Deliver User Story 4 to lock in the lightweight guardrail.
6. Finish with wording cleanup, focused validation, and formatting.

### Parallel Team Strategy

1. One contributor handles the support-layer resolver contract and shared context-bar behavior while another prepares the new regression files.
2. After Foundation is ready, split US1 and US2 between monitoring-shell parity and resource-scope hardening.
3. Reserve one contributor for tenant-panel non-regression and the guardrail so the exception inventory stays coherent while implementation lands.

---

## Notes

- `[P]` tasks touch different files and can be executed in parallel.
- User-story labels map directly to the prioritized stories in `spec.md`.
- Tests are mandatory in this repo for every runtime change in the resulting implementation.
- The suggested MVP scope is Phase 3 only after Setup and Foundational are complete.
