ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
140399f96f
TenantAtlas/specs/175-workspace-governance-attention/tasks.md

20 KiB
Raw Blame History

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.

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

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

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

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

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

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

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

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

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

# 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

# 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

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