# Tasks: Workspace Governance Attention Foundation **Input**: Design documents from `/specs/175-workspace-governance-attention/` (`spec.md`, `plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`) **Prerequisites**: `/specs/175-workspace-governance-attention/plan.md` (required), `/specs/175-workspace-governance-attention/spec.md` (required for user stories) **Tests**: REQUIRED (Pest) for all runtime behavior changes in this repo. Use focused workspace overview coverage in `tests/Feature/Filament/WorkspaceOverviewAccessTest.php`, `tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php`, `tests/Feature/Filament/WorkspaceOverviewLandingTest.php`, `tests/Feature/Filament/WorkspaceOverviewNavigationTest.php`, `tests/Feature/Filament/WorkspaceOverviewContentTest.php`, `tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php`, `tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php`, `tests/Feature/Filament/WorkspaceOverviewOperationsTest.php`, `tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php`, `tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php`, `tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php`, and `tests/Feature/Filament/WorkspaceOverviewDbOnlyTest.php`. **Operations**: This feature does not create a new `OperationRun` type or change operations lifecycle ownership. Existing canonical Operations routes remain the only operations destinations involved, and the work here is limited to truthful workspace aggregation and destination continuity. **RBAC**: Preserve workspace membership enforcement on `/admin`, deny-as-not-found `404` for non-members or out-of-scope tenants, capability-safe fallback or disabled states for drill-through items, and visible-tenant-only aggregation. **Operator Surfaces**: `WorkspaceOverview`, `WorkspaceSummaryStats`, `WorkspaceNeedsAttention`, and `WorkspaceRecentOperations` must stay operator-first, with governance truth above recency context and no dead-end navigation. **Filament UI Action Surfaces**: No destructive actions or redundant inspect affordances are added. `WorkspaceSummaryStats` and `WorkspaceNeedsAttention` remain drill-through summary surfaces, and `WorkspaceRecentOperations` remains a row-open diagnostic surface. **Filament UI UX-001**: No new create, edit, or view pages are introduced. Existing workspace landing layout remains in place while semantics, ordering, and empty-state wording are hardened. **Badges**: Existing badge semantics for findings severity, compare posture, governance validity, operations status, and operations outcome remain authoritative; no new page-local badge vocabulary is introduced. **Organization**: Tasks are grouped by user story so each story can be implemented and verified as an independent increment. ## Phase 1: Setup (Context And Existing Surface Review) **Purpose**: Reconfirm the exact workspace overview seams, tenant truth sources, and canonical destinations before changing `/admin` semantics. - [X] T001 Review current workspace overview composition in `app/Support/Workspaces/WorkspaceOverviewBuilder.php`, `app/Filament/Pages/WorkspaceOverview.php`, `app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php`, `app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php`, and `app/Filament/Widgets/Workspace/WorkspaceRecentOperations.php` - [X] T002 [P] Review existing tenant governance and compare truth sources in `app/Support/Baselines/TenantGovernanceAggregateResolver.php`, `app/Support/Baselines/TenantGovernanceAggregate.php`, `app/Support/Baselines/BaselineCompareStats.php`, `app/Support/Baselines/BaselineCompareSummaryAssessor.php`, and `app/Filament/Widgets/Dashboard/NeedsAttention.php` - [X] T003 [P] Review canonical drill-through destinations and current workspace overview regression seams in `app/Filament/Pages/TenantDashboard.php`, `app/Filament/Pages/BaselineCompareLanding.php`, `app/Filament/Resources/FindingResource/Pages/ListFindings.php`, `app/Filament/Pages/Monitoring/Operations.php`, and `tests/Feature/Filament/WorkspaceOverview*.php` --- ## Phase 2: Foundational (Blocking Payload And Continuity Seams) **Purpose**: Establish the shared workspace payload and continuity helpers that every user story depends on. **⚠️ CRITICAL**: No user story work should begin until this phase is complete. - [X] T004 Create governance-attention and performance regression scaffolding in `tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php`, `tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php`, `tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php`, and `tests/Feature/Filament/WorkspaceOverviewDbOnlyTest.php` - [X] T005 Extend the shared workspace overview payload to match `specs/175-workspace-governance-attention/contracts/workspace-governance-attention.openapi.yaml` for metric categories, calmness state, zero-tenant recovery, and structured attention destinations in `app/Support/Workspaces/WorkspaceOverviewBuilder.php` - [X] T006 [P] Prepare canonical findings-subset, alerts-overview, and operations-continuity seams for workspace-originated drill-through in `app/Filament/Resources/FindingResource/Pages/ListFindings.php`, `app/Filament/Pages/Monitoring/Alerts.php`, and `app/Support/OperationRunLinks.php` - [X] T007 [P] Add shared authorization, visibility, zero-tenant recovery, and DB-only query-bounded assertions for workspace governance destinations in `tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php`, `tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php`, `tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php`, and `tests/Feature/Filament/WorkspaceOverviewDbOnlyTest.php` **Checkpoint**: The builder exposes the shared payload shape, the destination seams are ready, and the new regression files exist. --- ## Phase 3: User Story 1 - See The Right Tenant First (Priority: P1) 🎯 MVP **Goal**: Make `/admin` surface governance-critical tenants ahead of operational noise so the riskiest visible tenant is obvious first. **Independent Test**: Seed multiple visible tenants with overdue findings, lapsed governance, expiring governance, stale, failed, or materially degraded compare posture, high-severity active findings, alerts, and operations, then verify governance-critical tenants rank above activity-only and alert-only items and suppress false calmness. ### Tests for User Story 1 - [X] T008 [P] [US1] Add governance-ranking scenarios for overdue findings, lapsed governance, expiring governance, high-severity active findings, stale, failed, or materially degraded compare posture, and alert-only supporting items in `tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php` - [X] T009 [P] [US1] Add false-calmness and zero-tenant distinctness scenarios for quiet operations but risky governance in `tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php` and `tests/Feature/Filament/WorkspaceOverviewContentTest.php` ### Implementation for User Story 1 - [X] T010 [US1] Promote visible-tenant governance aggregate states into bounded governance-first attention candidates, including expiring governance, stale, failed, or materially degraded compare posture, and lower-priority alert-only supporting items when they can be attributed to one visible tenant, in `app/Support/Workspaces/WorkspaceOverviewBuilder.php` - [X] T011 [US1] Render tenant label, problem family, urgency, and governance-first ordering in `app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php` and `resources/views/filament/widgets/workspace/workspace-needs-attention.blade.php` - [X] T012 [US1] Align workspace landing copy and calmness framing so operations-only quiet never implies portfolio health in `app/Filament/Pages/WorkspaceOverview.php` and `resources/views/filament/pages/workspace-overview.blade.php` - [X] T013 [US1] Run focused US1 verification against `tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php`, `tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php`, and `tests/Feature/Filament/WorkspaceOverviewContentTest.php` **Checkpoint**: The workspace home no longer looks calmer than the worst visible tenant governance state. --- ## Phase 4: User Story 2 - Distinguish Risk From Activity (Priority: P1) **Goal**: Make the workspace home clearly separate governance risk from operational activity so the portfolio can be read as risky, busy, both, or calm. **Independent Test**: Render `/admin` in governance-only, activity-only, mixed, and healthy scenarios, then verify metrics, attention, and empty states describe those cases differently and truthfully. ### Tests for User Story 2 - [X] T014 [P] [US2] Add governance-risk-versus-activity metric scenarios, including expiring governance and stale, failed, or materially degraded compare posture counts, in `tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php` and `tests/Feature/Filament/WorkspaceOverviewContentTest.php` - [X] T015 [P] [US2] Add operations-only, risk-only, mixed, healthy-state, and zero-tenant recovery scenarios in `tests/Feature/Filament/WorkspaceOverviewOperationsTest.php` and `tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php` ### Implementation for User Story 2 - [X] T016 [US2] Split workspace summary metrics into scope, governance-risk, activity, and alert categories, preserving expiring governance and stale, failed, or materially degraded compare posture as governance-risk inputs, in `app/Support/Workspaces/WorkspaceOverviewBuilder.php` - [X] T017 [US2] Update stat-card labels, descriptions, and destination semantics for governance-risk versus activity counts in `app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php` and `resources/views/filament/pages/workspace-overview.blade.php` - [X] T018 [US2] Keep recent operations diagnostic-only and remove its ability to define calmness on its own in `app/Filament/Widgets/Workspace/WorkspaceRecentOperations.php`, `resources/views/filament/widgets/workspace/workspace-recent-operations.blade.php`, and `app/Support/Workspaces/WorkspaceOverviewBuilder.php` - [X] T019 [US2] Run focused US2 verification against `tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php`, `tests/Feature/Filament/WorkspaceOverviewOperationsTest.php`, `tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php`, and `tests/Feature/Filament/WorkspaceOverviewDbOnlyTest.php` **Checkpoint**: The summary strip and surrounding copy now distinguish portfolio risk from portfolio activity. --- ## Phase 5: User Story 3 - Jump Into The Right Tenant Surface (Priority: P2) **Goal**: Make each attention item identify the tenant and open a trustworthy next surface for the same problem family. **Independent Test**: Seed representative findings, stale, failed, or materially degraded compare, evidence, review, alert, and operations cases, then verify each workspace attention item preserves tenant identity and reaches the correct destination or a safe fallback or disabled state. ### Tests for User Story 3 - [X] T020 [P] [US3] Add drill-through continuity coverage for tenant dashboard, findings, stale, failed, or materially degraded compare posture, evidence, review, alerts overview, and operations destinations in `tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php` - [X] T021 [P] [US3] Add capability-limited fallback, non-clickable state, zero-tenant choose-workspace recovery, and low-permission operations fallback coverage in `tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php` and `tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php` ### Implementation for User Story 3 - [X] T022 [US3] Implement per-family primary destination selection with tenant-safe fallback or disabled states, explicit alerts-overview routing, `switch_workspace` as the zero-tenant default next action, `operations_index` as the low-permission workspace-state fallback, aggregate lapsed-governance fallback to the tenant dashboard when findings filters would narrow the invalid-governance family, and tenant-scope authorization checks through `app/Services/Auth/CapabilityResolver.php` alongside `app/Services/Auth/WorkspaceCapabilityResolver.php` in `app/Support/Workspaces/WorkspaceOverviewBuilder.php` - [X] T023 [US3] Wire primary actions and helper text for workspace attention items across findings, compare, evidence, reviews, alerts, and operations, keeping every promoted item tenant-identified, in `app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php`, `resources/views/filament/widgets/workspace/workspace-needs-attention.blade.php`, and `app/Filament/Pages/WorkspaceOverview.php` - [X] T024 [US3] Preserve canonical subset continuity for workspace-originated findings and operations drill-throughs, and route aggregate lapsed-governance attention through the tenant dashboard when a findings filter would otherwise narrow the invalid-governance family, in `app/Filament/Resources/FindingResource/Pages/ListFindings.php`, `app/Filament/Pages/Monitoring/Operations.php`, and `app/Support/Workspaces/WorkspaceOverviewBuilder.php` - [X] T025 [US3] Run focused US3 verification against `tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php`, `tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php`, and `tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php` **Checkpoint**: Every central attention family now opens the correct tenant surface or a safe, non-deceptive fallback state. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Finish copy alignment, formatting, and the final focused verification pack across all stories. - [X] T026 [P] Align final operator copy, urgency labels, disabled helper text, zero-tenant recovery wording, and low-permission `Open operations` fallback wording across `app/Filament/Pages/WorkspaceOverview.php`, `app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php`, `app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php`, `resources/views/filament/pages/workspace-overview.blade.php`, and `resources/views/filament/widgets/workspace/workspace-needs-attention.blade.php` - [X] T027 Run formatting with `vendor/bin/sail bin pint --dirty --format agent` for `app/Support/Workspaces/WorkspaceOverviewBuilder.php`, `app/Filament/Pages/WorkspaceOverview.php`, `app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php`, `app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php`, `app/Filament/Widgets/Workspace/WorkspaceRecentOperations.php`, `resources/views/filament/pages/workspace-overview.blade.php`, `resources/views/filament/widgets/workspace/workspace-needs-attention.blade.php`, and `resources/views/filament/widgets/workspace/workspace-recent-operations.blade.php` - [X] T028 Run the final quickstart verification pack from `specs/175-workspace-governance-attention/quickstart.md` against `tests/Feature/Filament/WorkspaceOverviewAccessTest.php`, `tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php`, `tests/Feature/Filament/WorkspaceOverviewLandingTest.php`, `tests/Feature/Filament/WorkspaceOverviewNavigationTest.php`, `tests/Feature/Filament/WorkspaceOverviewContentTest.php`, `tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php`, `tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php`, `tests/Feature/Filament/WorkspaceOverviewOperationsTest.php`, `tests/Feature/Filament/WorkspaceOverviewDbOnlyTest.php`, `tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php`, `tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php`, and `tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php` - [X] T029 Run the manual smoke checks in `specs/175-workspace-governance-attention/quickstart.md` for quiet-operations-risky-governance, stale or failed compare posture, healthy workspace, zero-tenant recovery, and permission-limited member scenarios - [X] T030 Fix the low-permission workspace operations fallback so workspace-originated drill-through clears tenant context and immediately shows workspace-wide follow-up in `app/Support/Workspaces/WorkspaceOverviewBuilder.php`, `app/Support/OperationRunLinks.php`, `app/Filament/Pages/Monitoring/Operations.php`, `tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php`, and `tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php` --- ## 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 stays independently testable, though it overlaps with the same workspace builder and page shell. - **User Story 3 (Phase 5)**: Depends on Foundational completion and benefits from User Stories 1 and 2 because the destination contract is clearer once governance promotion and metric separation are in place. - **Polish (Phase 6)**: Depends on all desired user stories being complete. ### User Story Dependencies - **User Story 1 (P1)**: First deliverable and recommended MVP. No dependency on other user stories after Foundational work. - **User Story 2 (P1)**: Can start after Foundational completion and remains independently testable, though it shares the builder and page shell with US1. - **User Story 3 (P2)**: Can start after Foundational completion and is best delivered after US1 and US2 because it hardens the attention items already introduced there. ### Within Each User Story - Story tests should be added before or alongside implementation and must fail before the story is considered complete. - Builder changes should land before widget and page copy refinements that depend on the new payload. - Destination continuity changes should land before story-level verification runs. - Story-level verification should complete before moving on to polish. ### Parallel Opportunities - Setup review tasks `T002` and `T003` can run in parallel. - In Foundational work, `T006` and `T007` can run in parallel after `T005` defines the payload contract. - In US1, `T008` and `T009` can run in parallel. - In US2, `T014` and `T015` can run in parallel. - In US3, `T020` and `T021` can run in parallel. - In Phase 6, `T026` can run while the final verification command set for `T028` is being prepared. --- ## Parallel Example: User Story 1 ```bash # Launch US1 tests in parallel: T008 tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php T009 tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php + tests/Feature/Filament/WorkspaceOverviewContentTest.php ``` ## Parallel Example: User Story 2 ```bash # Launch US2 test work in parallel: T014 tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php + tests/Feature/Filament/WorkspaceOverviewContentTest.php T015 tests/Feature/Filament/WorkspaceOverviewOperationsTest.php + tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php ``` ## Parallel Example: User Story 3 ```bash # Launch US3 drill-through and fallback tests in parallel: T020 tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php T021 tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php + tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.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 that `/admin` no longer emits a false calm signal when visible tenant governance issues exist. ### Incremental Delivery 1. Ship US1 to make the workspace home governance-aware and suppress false calmness. 2. Add US2 to separate governance risk from activity and protect calmness semantics. 3. Add US3 to harden drill-through continuity and capability-safe fallbacks. 4. Finish with copy alignment, formatting, the quickstart verification pack, and manual smoke checks. ### Suggested MVP Scope - MVP = Phases 1 through 3 only. --- ## 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.