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.

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

• T004 Create the workspace overview page shell in app/Filament/Pages/WorkspaceOverview.php and resources/views/filament/pages/workspace-overview.blade.php
• T005 Create the shared workspace overview data builder in app/Support/Workspaces/WorkspaceOverviewBuilder.php
• 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
• 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

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

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

• T014 [P] [US2] Add workspace overview content and empty-state coverage in tests/Feature/Filament/WorkspaceOverviewContentTest.php and tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php
• 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

• 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
• T017 [US2] Extend WorkspaceOverviewBuilder to assemble bounded summary metrics, recent operations, attention items, and quick actions in app/Support/Workspaces/WorkspaceOverviewBuilder.php
• 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
• T019 [P] [US2] Implement the bounded needs-attention widget with polling disabled by default in app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php
• T020 [P] [US2] Implement the bounded recent-operations widget with polling disabled by default in app/Filament/Widgets/Workspace/WorkspaceRecentOperations.php
• 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

• T022 [P] [US3] Add authorization and non-member access coverage in tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php and tests/Feature/Guards/AdminWorkspaceRoutesGuardTest.php
• 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

• T024 [US3] Enforce membership-based page access and capability-safe surface gating in app/Filament/Pages/WorkspaceOverview.php and app/Support/Workspaces/WorkspaceOverviewBuilder.php
• 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
• 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.

• 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
• T028 Run focused Pest verification from specs/129-workspace-admin-home/quickstart.md
• 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

# 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

# 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

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