TenantAtlas/specs/129-workspace-admin-home/tasks.md

# Tasks: Workspace Home & Admin Landing (129)

**Input**: Design documents from `specs/129-workspace-admin-home/` (`spec.md`, `plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`)  
**Prerequisites**: `specs/129-workspace-admin-home/plan.md` (required), `specs/129-workspace-admin-home/spec.md` (required for user stories)

**Tests**: REQUIRED (Pest) for all runtime behavior changes in this repo.  
**Operations**: No new `OperationRun` flow is introduced; this feature only reads existing operational data for workspace-safe overview surfaces.  
**RBAC**: Preserve admin workspace-plane isolation, deny-as-not-found 404 for non-members, 403 for in-scope capability denial on protected targets, and canonical capability-registry usage only.  
**Filament UI**: This feature adds a new Filament page and modifies admin panel navigation and home semantics; implement the overview as a view-style, sectioned workspace surface with explicit empty states and no destructive actions.

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Reconfirm the exact landing, navigation, and reusable surface seams before changing `/admin` semantics.

- [X] T001 Review current admin home, panel config, and workspace redirect call sites in `routes/web.php`, `app/Providers/Filament/AdminPanelProvider.php`, and `app/Support/Workspaces/WorkspaceRedirectResolver.php`
- [X] T002 [P] Review existing workspace-safe page patterns and reusable overview candidates in `app/Filament/Pages/Monitoring/Operations.php`, `app/Filament/Pages/Monitoring/Alerts.php`, and `app/Filament/Widgets/Dashboard/`
- [X] T003 [P] Review legacy `/admin` landing and chooser tests in `tests/Feature/Filament/AdminHomeRedirectsToChooseTenantWhenWorkspaceSelectedTest.php`, `tests/Feature/Filament/LoginRedirectsToChooseWorkspaceWhenMultipleWorkspacesTest.php`, and `tests/Feature/Filament/ChooseTenantRequiresWorkspaceTest.php`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Create the shared workspace-home shell and supporting seams that every user story depends on.

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

- [X] T004 Create the workspace overview page shell in `app/Filament/Pages/WorkspaceOverview.php` and `resources/views/filament/pages/workspace-overview.blade.php`
- [X] T005 Create the shared workspace overview data builder in `app/Support/Workspaces/WorkspaceOverviewBuilder.php`
- [X] T006 [P] Scaffold workspace overview widgets in `app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php`, `app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php`, and `app/Filament/Widgets/Workspace/WorkspaceRecentOperations.php`
- [X] T007 [P] Add foundational page access and render smoke coverage for workspace members versus non-members in `tests/Feature/Filament/WorkspaceOverviewAccessTest.php`

**Checkpoint**: The repo has a concrete workspace overview page shell, shared builder seam, and widget scaffolding ready for landing, content, and authorization work.

---

## Phase 3: User Story 1 - Land on a real workspace home (Priority: P1) 🎯 MVP

**Goal**: `/admin` becomes a stable workspace-level landing page for authenticated users with a selected workspace, without requiring tenant context.

**Independent Test**: Open `/admin` with a selected workspace and verify the workspace overview renders instead of redirecting to tenant context; open `/admin` without a selected workspace and verify the chooser flow still applies.

### Tests for User Story 1

- [X] T008 [P] [US1] Update selected-workspace landing coverage in `tests/Feature/Filament/AdminHomeRedirectsToChooseTenantWhenWorkspaceSelectedTest.php` and add canonical home assertions in `tests/Feature/Filament/WorkspaceOverviewLandingTest.php`
- [X] T009 [P] [US1] Add login, brand-logo, and chooser-first no-workspace landing coverage in `tests/Feature/Filament/LoginRedirectsToChooseWorkspaceWhenMultipleWorkspacesTest.php`, `tests/Feature/Filament/WorkspaceOverviewNavigationTest.php`, and `tests/Feature/Filament/WorkspaceOverviewLandingTest.php`

### Implementation for User Story 1

- [X] T010 [US1] Rewire `/admin` to render the workspace overview and constrain direct no-workspace entry to chooser-first behavior in `routes/web.php` and `app/Http/Middleware/EnsureWorkspaceSelected.php`
- [X] T011 [US1] Register `WorkspaceOverview` as the admin-panel home and primary overview page in `app/Providers/Filament/AdminPanelProvider.php` and `app/Filament/Pages/WorkspaceOverview.php`
- [X] T012 [US1] Narrow workspace post-selection branching so chooser-driven flows can still use tenant branching without defining normal `/admin` behavior in `app/Support/Workspaces/WorkspaceRedirectResolver.php` and `app/Filament/Pages/ChooseWorkspace.php`
- [X] T013 [US1] Align tenantless admin navigation behavior for the new workspace home in `app/Support/Middleware/EnsureFilamentTenantSelected.php`

**Checkpoint**: User Story 1 is complete when `/admin` is a real workspace home for selected workspaces, chooser gating still works, and brand-logo navigation resolves back to the workspace overview.

---

## Phase 4: User Story 2 - Reorient and continue work from workspace context (Priority: P2)

**Goal**: The workspace home shows useful workspace-scoped context, summary signals, recent operational visibility, and quick actions without forcing a tenant.

**Independent Test**: Render the workspace home for a normal workspace member and verify it shows workspace identity, bounded summary metrics, a recent or needs-attention surface, quick actions to existing flows, and intentional empty states when data is sparse.

### Tests for User Story 2

- [X] T014 [P] [US2] Add workspace overview content and empty-state coverage in `tests/Feature/Filament/WorkspaceOverviewContentTest.php` and `tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php`
- [X] T015 [P] [US2] Add bounded recent-operations, quick-action, and no-uncontrolled-polling coverage in `tests/Feature/Filament/WorkspaceOverviewOperationsTest.php`

### Implementation for User Story 2

- [X] T016 [US2] Implement workspace identity header, section layout, and quick-action presentation in `app/Filament/Pages/WorkspaceOverview.php` and `resources/views/filament/pages/workspace-overview.blade.php`
- [X] T017 [US2] Extend `WorkspaceOverviewBuilder` to assemble bounded summary metrics, recent operations, attention items, and quick actions in `app/Support/Workspaces/WorkspaceOverviewBuilder.php`
- [X] T018 [P] [US2] Implement the workspace summary KPI widget with the minimum target set and polling disabled by default in `app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php`
- [X] T019 [P] [US2] Implement the bounded needs-attention widget with polling disabled by default in `app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php`
- [X] T020 [P] [US2] Implement the bounded recent-operations widget with polling disabled by default in `app/Filament/Widgets/Workspace/WorkspaceRecentOperations.php`
- [X] T021 [US2] Wire overview widgets, empty-state copy, and canonical links into the workspace home page in `app/Filament/Pages/WorkspaceOverview.php` and `resources/views/filament/pages/workspace-overview.blade.php`

**Checkpoint**: User Story 2 is complete when the workspace home feels useful and tenantless, surfaces only bounded workspace-scoped signals, and degrades gracefully for low-data workspaces.

---

## Phase 5: User Story 3 - See only permitted workspace surfaces (Priority: P3)

**Goal**: The workspace home remains safe for minimally privileged users, hides unauthorized aggregates and actions, and preserves clear 404 versus 403 semantics.

**Independent Test**: Load the workspace home as a low-permission member and as a non-member, and verify safe rendering, hidden unauthorized surfaces, distinct switch-versus-manage behavior, and workspace-scope not-found semantics.

### Tests for User Story 3

- [X] T022 [P] [US3] Add authorization and non-member access coverage in `tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php` and `tests/Feature/Guards/AdminWorkspaceRoutesGuardTest.php`
- [X] T023 [P] [US3] Add low-permission visibility coverage for hidden counts and manage-versus-switch actions in `tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php`

### Implementation for User Story 3

- [X] T024 [US3] Enforce membership-based page access and capability-safe surface gating in `app/Filament/Pages/WorkspaceOverview.php` and `app/Support/Workspaces/WorkspaceOverviewBuilder.php`
- [X] T025 [US3] Gate overview navigation and workspace-management shortcuts with canonical capability checks in `app/Providers/Filament/AdminPanelProvider.php` and `app/Support/Middleware/EnsureFilamentTenantSelected.php`
- [X] T026 [US3] Harden overview aggregates and list queries against tenant leakage and unauthorized counts in `app/Support/Workspaces/WorkspaceOverviewBuilder.php`, `app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php`, and `app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php`

**Checkpoint**: User Story 3 is complete when the workspace home remains useful for low-permission members, hides unauthorized signals and actions, and preserves deny-as-not-found semantics for non-members.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Final regression protection, formatting, and manual verification across all stories.

- [X] T027 [P] Add final regression coverage that normal `/admin` access no longer silently redirects into tenant context and that direct no-workspace admin entry stays chooser-first in `tests/Feature/Filament/WorkspaceOverviewLandingTest.php`, `tests/Feature/Filament/LoginRedirectsToChooseWorkspaceWhenMultipleWorkspacesTest.php`, and `tests/Feature/Filament/ChooseTenantRequiresWorkspaceTest.php`
- [X] T028 Run focused Pest verification from `specs/129-workspace-admin-home/quickstart.md`
- [X] T029 Run formatting for changed files with `vendor/bin/sail bin pint --dirty --format agent`
- [ ] T030 Validate the manual QA scenarios in `specs/129-workspace-admin-home/quickstart.md`

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies; can start immediately.
- **Foundational (Phase 2)**: Depends on Setup; blocks all user stories.
- **User Story 1 (Phase 3)**: Depends on Foundational completion.
- **User Story 2 (Phase 4)**: Depends on Foundational completion and benefits from User Story 1 because canonical `/admin` landing makes the overview reachable through the primary flow.
- **User Story 3 (Phase 5)**: Depends on Foundational completion and should land after User Story 2 because capability-safe gating applies to real overview content.
- **Polish (Phase 6)**: Depends on all desired user stories being complete.

### User Story Dependencies

- **User Story 1 (P1)**: First deliverable and MVP. No dependency on other user stories.
- **User Story 2 (P2)**: Depends on the overview shell from the Foundational phase and works best after US1 establishes canonical landing semantics.
- **User Story 3 (P3)**: Depends on the overview shell and real content surfaces from US2 so authorization and visibility rules can be verified against actual widgets and quick actions.

### Within Each User Story

- Tests should be added before or alongside implementation and must fail before the story is considered complete.
- Route and panel-home behavior should be correct before quick actions and content widgets are treated as done.
- Builder and page wiring should exist before widget output is considered stable.
- Authorization hardening should be completed before final regression verification.

### Parallel Opportunities

- Setup review tasks `T002` and `T003` can run in parallel.
- In Foundational, `T006` and `T007` can run in parallel after the page and builder seam are defined.
- In US1, `T008` and `T009` can run in parallel.
- In US2, `T014` and `T015` can run in parallel, then widget tasks `T018`, `T019`, and `T020` can run in parallel after `T017` defines builder outputs.
- In US3, `T022` and `T023` can run in parallel.

---

## Parallel Example: User Story 1

```bash
# Launch US1 test work in parallel:
T008 tests/Feature/Filament/AdminHomeRedirectsToChooseTenantWhenWorkspaceSelectedTest.php + tests/Feature/Filament/WorkspaceOverviewLandingTest.php
T009 tests/Feature/Filament/LoginRedirectsToChooseWorkspaceWhenMultipleWorkspacesTest.php + tests/Feature/Filament/WorkspaceOverviewNavigationTest.php
```

## Parallel Example: User Story 2

```bash
# Launch US2 test work in parallel:
T014 tests/Feature/Filament/WorkspaceOverviewContentTest.php + tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php
T015 tests/Feature/Filament/WorkspaceOverviewOperationsTest.php

# Launch US2 widget work in parallel after builder output is defined:
T018 app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php
T019 app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php
T020 app/Filament/Widgets/Workspace/WorkspaceRecentOperations.php
```

## Parallel Example: User Story 3

```bash
# Launch US3 authorization tests in parallel:
T022 tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php + tests/Feature/Guards/AdminWorkspaceRoutesGuardTest.php
T023 tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.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 `/admin` landing, chooser preservation, and brand-logo return behavior independently.

### Incremental Delivery

1. Ship US1 to establish `/admin` as the canonical workspace home.
2. Add US2 to make the home useful with summary, attention, recent operations, and quick actions.
3. Add US3 to harden capability-safe rendering and low-permission behavior.

### Suggested MVP Scope

- MVP = Phases 1 through 3, then run the focused landing tests for `/admin`, chooser preservation, and navigation semantics.

---

## Format Validation

- Every task follows the checklist format `- [ ] T### [P?] [US?] Description with file path`.
- Setup, Foundational, and Polish phases intentionally omit story labels.
- User story phases use `[US1]`, `[US2]`, and `[US3]` labels.
- Parallel markers are used only on tasks that can proceed independently without conflicting incomplete prerequisites.