TenantAtlas/specs/175-workspace-governance-attention/tasks.md

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