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