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.

- [X] 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`
- [X] 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`
- [X] 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.

- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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

- [X] T008 [P] [US1] Add mixed, calm, single-tenant, and multi-tenant backup and recovery metric scenarios in `apps/platform/tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php`
- [X] 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

- [X] 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`
- [X] 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`
- [X] 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

- [X] 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`
- [X] 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

- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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

- [X] 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`
- [X] 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

- [X] 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`
- [X] 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`
- [X] 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

- [X] T024 [P] [US4] Add hidden-tenant omission and bounded-calmness visibility scenarios in `apps/platform/tests/Feature/Filament/WorkspaceOverviewPermissionVisibilityTest.php`
- [X] 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

- [X] 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`
- [X] 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`
- [X] 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.

- [X] 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`
- [X] 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`
- [X] 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
- [X] 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`
- [X] 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

```bash
# 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

```bash
# 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

```bash
# 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

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