TenantAtlas/specs/185-workspace-recovery-posture-visibility/tasks.md

Tasks: Workspace Recovery Posture Visibility

Input: Design documents from /specs/185-workspace-recovery-posture-visibility/ (spec.md, plan.md, research.md, data-model.md, contracts/, quickstart.md)
Prerequisites: /specs/185-workspace-recovery-posture-visibility/plan.md (required), /specs/185-workspace-recovery-posture-visibility/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/WorkspaceOverviewSummaryMetricsTest.php, tests/Feature/Filament/WorkspaceOverviewRecoveryAttentionTest.php, tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php, tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php, tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php, tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php, tests/Feature/Filament/WorkspaceOverviewContentTest.php, tests/Feature/Filament/WorkspaceOverviewDbOnlyTest.php, tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php, and existing upstream tenant-truth guards in tests/Feature/Filament/DashboardRecoveryPosturePerformanceTest.php, tests/Feature/Filament/DashboardKpisWidgetTest.php, and tests/Feature/Filament/NeedsAttentionWidgetTest.php.
Operations: This feature does not create a new OperationRun type or change operation lifecycle ownership. Existing Operations surfaces remain diagnostic-only and are not expanded as part of this slice.
RBAC: Preserve workspace membership enforcement on /admin, deny-as-not-found 404 semantics for non-members or out-of-scope tenants, existing 403 semantics for in-scope actors lacking deeper capabilities, visible-tenant-only aggregation, and safe tenant-dashboard or choose-tenant fallbacks for new workspace signals.
Operator Surfaces: WorkspaceOverview, WorkspaceSummaryStats, and WorkspaceNeedsAttention must stay operator-first, keep backup health and recovery evidence separate, and make tenant identity explicit on every new workspace attention item.
Filament UI Action Surfaces: No destructive actions or redundant inspect affordances are added. WorkspaceSummaryStats remains a stat drill-through surface, WorkspaceNeedsAttention remains an item-based triage surface, and WorkspaceOverview remains the singleton landing page.
Filament UI UX-001: No new create, edit, or view pages are introduced. Existing workspace landing layout remains in place while metrics, calmness, and attention semantics are hardened.
Badges: Existing badge and tone semantics remain authoritative; no new page-local portfolio recovery badge language may be 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 Seam Review)

Purpose: Reconfirm the exact workspace overview seams, tenant truth sources, and regression surfaces before changing /admin semantics.

• T001 Review the current workspace overview composition in apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php, apps/platform/app/Filament/Pages/WorkspaceOverview.php, apps/platform/app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php, apps/platform/app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php, and apps/platform/resources/views/filament/pages/workspace-overview.blade.php
• T002 [P] Review the existing tenant backup-health and recovery-evidence source truths in apps/platform/app/Support/BackupHealth/TenantBackupHealthResolver.php, apps/platform/app/Support/BackupHealth/TenantBackupHealthAssessment.php, apps/platform/app/Support/RestoreSafety/RestoreSafetyResolver.php, apps/platform/app/Filament/Widgets/Dashboard/DashboardKpis.php, and apps/platform/app/Filament/Widgets/Dashboard/NeedsAttention.php
• T003 [P] Review the existing workspace overview regression seams and contract expectations in specs/185-workspace-recovery-posture-visibility/contracts/workspace-recovery-posture-visibility.openapi.yaml, apps/platform/tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php, and apps/platform/tests/Feature/Filament/WorkspaceOverviewDbOnlyTest.php

---

Phase 2: Foundational (Blocking Payload And Derivation Seams)

Purpose: Establish the shared workspace payload, visible-tenant derivation seams, and regression scaffolding that every user story depends on.

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

• T004 Create the initial recovery-visibility test scaffolding in apps/platform/tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewDbOnlyTest.php, and apps/platform/tests/Feature/Filament/WorkspaceOverviewRecoveryAttentionTest.php
• T005 Extend the shared workspace overview payload to align with specs/185-workspace-recovery-posture-visibility/contracts/workspace-recovery-posture-visibility.openapi.yaml for new metric keys, attention families, reason-context payloads, destination kinds, and checked domains in apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php
• T006 [P] Add batch-friendly visible-tenant backup-health derivation support in apps/platform/app/Support/BackupHealth/TenantBackupHealthResolver.php and apps/platform/app/Support/BackupHealth/TenantBackupHealthAssessment.php
• T007 [P] Add batch-friendly visible-tenant recovery-evidence derivation support while preserving the latest-10 restore-history cap in apps/platform/app/Support/RestoreSafety/RestoreSafetyResolver.php and apps/platform/tests/Feature/Filament/DashboardRecoveryPosturePerformanceTest.php

Checkpoint: The builder exposes the shared backup-health and recovery-evidence workspace payload shape, and the visible-tenant derivation seams are ready for story work.

---

Phase 3: User Story 1 - See Backup And Recovery Hotspots Fast (Priority: P1) 🎯 MVP

Goal: Make /admin show separate backup-attention and recovery-attention counts for visible tenants.

Independent Test: Seed visible tenants with absent, stale, degraded, unvalidated, weakened, and calm states, then verify that /admin shows separate backup and recovery summary metrics without overclaiming workspace confidence.

Tests for User Story 1

• T008 [P] [US1] Add mixed, calm, single-tenant, and multi-tenant backup and recovery metric scenarios in apps/platform/tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php
• T009 [P] [US1] Add content assertions for separate backup-attention and recovery-attention labels, descriptions, and destination semantics in apps/platform/tests/Feature/Filament/WorkspaceOverviewContentTest.php

Implementation for User Story 1

• T010 [US1] Compute backup_attention_tenants and recovery_attention_tenants from visible-tenant backup and recovery contexts in apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php
• T011 [US1] Render the new workspace backup-attention and recovery-attention metrics plus stat-card destination behavior in apps/platform/app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php and apps/platform/resources/views/filament/pages/workspace-overview.blade.php
• T012 [US1] Run focused US1 verification against apps/platform/tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewContentTest.php, and apps/platform/tests/Feature/Filament/WorkspaceOverviewDbOnlyTest.php

Checkpoint: The workspace overview now answers how many visible tenants need backup follow-up and how many need recovery-evidence follow-up.

---

Phase 4: User Story 2 - Open The Right Tenant First (Priority: P1)

Goal: Make workspace attention rank backup and recovery weakness by severity and send the operator to the correct tenant first.

Independent Test: Seed mixed visible tenants and verify that absent ranks above stale above degraded, weakened ranks above unvalidated, and each new attention item opens the affected tenant dashboard with the same weakness still visible there.

Tests for User Story 2

• T013 [P] [US2] Add backup-health and recovery-evidence family ordering, no_recent_issues_visible suppression, and cross-family queue-preservation scenarios in apps/platform/tests/Feature/Filament/WorkspaceOverviewRecoveryAttentionTest.php and apps/platform/tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php
• T014 [P] [US2] Add backup-health and recovery-evidence drill-through continuity plus rendered attention-item contract assertions in apps/platform/tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php and apps/platform/tests/Feature/Filament/WorkspaceOverviewContentTest.php

Implementation for User Story 2

• T015 [US2] Add backup_health and recovery_evidence attention candidate building, tenant-bound reason context, severity ordering, and cross-family insertion that preserves existing governance and operations priorities in apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php
• T016 [US2] Render tenant-bound backup-health and recovery-evidence items with one clear tenant-dashboard action in apps/platform/app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php and apps/platform/resources/views/filament/widgets/workspace/workspace-needs-attention.blade.php
• T017 [US2] Wire single-tenant metric drill-through and multi-tenant choose-tenant fallback semantics for the new backup-attention and recovery-attention metrics plus attention items in apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php and apps/platform/app/Filament/Pages/WorkspaceOverview.php
• T018 [US2] Run focused US2 verification against apps/platform/tests/Feature/Filament/WorkspaceOverviewRecoveryAttentionTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php, and apps/platform/tests/Feature/Filament/WorkspaceOverviewContentTest.php

Checkpoint: The workspace overview now tells the operator which tenant to open first and why.

---

Phase 5: User Story 3 - Trust Calmness Boundaries (Priority: P2)

Goal: Make workspace calmness explicitly include backup health and recovery evidence instead of hiding blind spots.

Independent Test: Render calm and non-calm visible-workspace scenarios and verify that calmness is suppressed whenever backup-health attention or recovery-evidence attention exists, that checked_domains includes both new domains, and that calm copy explicitly names those domains.

Tests for User Story 3

• T019 [P] [US3] Add calmness and checked-domain scenarios for backup-health and recovery-evidence coverage in apps/platform/tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php and apps/platform/tests/Feature/Filament/WorkspaceOverviewContentTest.php
• T020 [P] [US3] Add builder-level calmness suppression coverage for mixed backup and recovery portfolios in apps/platform/tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php

Implementation for User Story 3

• T021 [US3] Extend checked_domains, calmness suppression, and calm next-action selection for backup_health and recovery_evidence in apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php
• T022 [US3] Update calmness and empty-state copy to state explicitly that backup health and recovery evidence were checked in apps/platform/resources/views/filament/pages/workspace-overview.blade.php and apps/platform/app/Filament/Pages/WorkspaceOverview.php
• T023 [US3] Run focused US3 verification against apps/platform/tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewContentTest.php, and apps/platform/tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php

Checkpoint: Calmness can no longer read as honest if backup-health weakness or recovery-evidence weakness is still present in the visible tenant slice.

---

Phase 6: User Story 4 - Preserve Permission-Safe Portfolio Truth (Priority: P3)

Goal: Keep the new workspace backup-health and recovery-evidence signals truthful under partial tenant visibility and limited downstream capability.

Independent Test: Mix visible and hidden tenants with backup and recovery issues, then verify that /admin counts only visible tenants, leaks no hidden tenant labels or reason text, stays bounded in calmness claims, and degrades safely when a deeper destination is unavailable.

Tests for User Story 4

• T024 [P] [US4] Add hidden-tenant omission and bounded-calmness visibility scenarios in apps/platform/tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php
• T025 [P] [US4] Add positive and negative authorization plus safe fallback scenarios for new metric and item destinations in apps/platform/tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php and apps/platform/tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php

Implementation for User Story 4

• T026 [US4] Enforce visible-tenant-only aggregation for backup-health and recovery-evidence signals plus safe single-tenant versus choose-tenant destination selection in apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php
• T027 [US4] Keep capability-limited backup-health and recovery-evidence item rendering tenant-safe with disabled states and helper text in apps/platform/app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php and apps/platform/resources/views/filament/widgets/workspace/workspace-needs-attention.blade.php
• T028 [US4] Run focused US4 verification against apps/platform/tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php, and apps/platform/tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php

Checkpoint: The new workspace backup-health and recovery-evidence signals are now tenant-safe, bounded, and authorization-aware.

---

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Finish copy alignment, cleanup, formatting, and the final focused verification pack.

• T029 [P] Align final operator copy, claim-boundary wording, and family labels across apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php, apps/platform/app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php, apps/platform/app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php, apps/platform/resources/views/filament/pages/workspace-overview.blade.php, and apps/platform/resources/views/filament/widgets/workspace/workspace-needs-attention.blade.php
• T030 [P] Collapse any temporary workspace-only posture mapping back into the existing truth seams in apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php, apps/platform/app/Support/BackupHealth/TenantBackupHealthResolver.php, and apps/platform/app/Support/RestoreSafety/RestoreSafetyResolver.php
• T031 Run formatting with cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent for the affected app/, resources/views/, and tests/Feature/Filament/ files
• T032 Run the final quickstart verification pack from specs/185-workspace-recovery-posture-visibility/quickstart.md against apps/platform/tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewRecoveryAttentionTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewDbOnlyTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewContentTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php, apps/platform/tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php, apps/platform/tests/Feature/Filament/DashboardRecoveryPosturePerformanceTest.php, apps/platform/tests/Feature/Filament/DashboardKpisWidgetTest.php, and apps/platform/tests/Feature/Filament/NeedsAttentionWidgetTest.php
• T033 Run the manual smoke checks from specs/185-workspace-recovery-posture-visibility/quickstart.md for mixed workspace, single-tenant metric drill-through, multi-tenant fallback, calm workspace, and RBAC-limited member scenarios

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies; can start immediately.
• Foundational (Phase 2): Depends on Setup; blocks all user-story work.
• User Story 1 (Phase 3): Depends on Foundational completion.
• User Story 2 (Phase 4): Depends on Foundational completion and reuses the shared visible-tenant payload from Phase 2.
• User Story 3 (Phase 5): Depends on Foundational completion and is best delivered after the new backup and recovery families exist.
• User Story 4 (Phase 6): Depends on Foundational completion and is best delivered after the new metric, attention, and calmness paths exist.
• Polish (Phase 7): Depends on all desired user stories being complete.

User Story Dependencies

• User Story 1 (P1): Can start after Foundational work and is the recommended MVP.
• User Story 2 (P1): Can start after Foundational work and remains independently testable, though it shares the same visible-tenant payload with US1.
• User Story 3 (P2): Can start after Foundational work, but is clearest once US1 and US2 have introduced the new metrics and attention families it must govern.
• User Story 4 (P3): Can start after Foundational work, but is most effective once the new signals from US1 through US3 already exist.

Within Each User Story

• Tests should be added before or alongside implementation and must fail before the story is considered complete.
• Builder and resolver changes should land before widget or page rendering tasks that depend on the new payload.
• Rendering changes should land before focused story verification runs.
• Focused story verification should complete before moving on to the next story.

Parallel Opportunities

• Setup tasks T002 and T003 can run in parallel.
• Foundational tasks T006 and T007 can run in parallel after T005 defines the shared workspace payload shape.
• In US1, T008 and T009 can run in parallel.
• In US2, T013 and T014 can run in parallel.
• In US3, T019 and T020 can run in parallel.
• In US4, T024 and T025 can run in parallel.
• In Phase 7, T029 and T030 can run in parallel before the final verification pack.

---

Parallel Example: User Story 1

# Launch US1 test work in parallel:
T008 apps/platform/tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php
T009 apps/platform/tests/Feature/Filament/WorkspaceOverviewContentTest.php

Parallel Example: User Story 2

# Launch US2 ordering and continuity coverage in parallel:
T013 apps/platform/tests/Feature/Filament/WorkspaceOverviewRecoveryAttentionTest.php
T014 apps/platform/tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php

Parallel Example: User Story 3

# Launch US3 calmness coverage in parallel:
T019 apps/platform/tests/Feature/Filament/WorkspaceOverviewEmptyStatesTest.php + apps/platform/tests/Feature/Filament/WorkspaceOverviewContentTest.php
T020 apps/platform/tests/Feature/Filament/WorkspaceOverviewGovernanceAttentionTest.php

Parallel Example: User Story 4

# Launch US4 visibility and authorization coverage in parallel:
T024 apps/platform/tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php
T025 apps/platform/tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php + apps/platform/tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.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 now answers how many visible tenants need backup follow-up and how many need recovery-evidence follow-up.

Incremental Delivery

1. Ship US1 to make the workspace home count backup-health and recovery-evidence hotspots honestly.
2. Add US2 to prioritize the right tenant and preserve tenant-dashboard drill-through continuity.
3. Add US3 to make calmness explicit and remove blind-spot calmness.
4. Add US4 to harden RBAC-safe omission, fallback behavior, and bounded claims.
5. Finish with copy alignment, cleanup, 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], [US3], and [US4] labels.
• Parallel markers are used only on tasks that can proceed independently without conflicting incomplete prerequisites.