TenantAtlas/specs/314-workspace-hub-navigation-context-contract/tasks.md

Tasks: Workspace Hub Navigation Context Contract

Input: spec.md and plan.md in specs/314-workspace-hub-navigation-context-contract/ Prerequisites: Spec 313 audit artifacts are completed context. Do not rewrite Specs 311, 312, or 313. Tests: Required. Use Pest 4 Feature/Livewire tests and one focused Pest Browser smoke for critical flows.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in the smallest honest family, and the Spec 314 browser smoke is explicit.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• The declared surface test profile is global-context-shell plus targeted monitoring-state-page/exception-coded-surface.
• Any material budget, baseline, trend, or escalation note is recorded in the implementation close-out.

Phase 1: Preparation and Guardrails

Purpose: Confirm scope and protect against accidental implementation drift before changing runtime code.

• T001 Confirm current branch is 314-workspace-hub-navigation-context-contract with git status --short --branch.
• T002 Re-read specs/314-workspace-hub-navigation-context-contract/spec.md, plan.md, and this tasks.md.
• T003 Re-read Spec 313 artifacts: audit-report.md, surface-inventory.md, page-matrix.md, query-param-inventory.md, clear-filter-inventory.md, and code-ownership-map.md.
• T004 Confirm no application implementation from Specs 315, 316, 317, or 318 is being pulled into this spec.
• T005 Confirm no migrations, seeders, packages, env vars, queues, scheduler, storage, or asset registration are needed.
• T006 Document the implementation close-out target: Guardrail / Exception / Smoke Coverage.

Phase 2: Contract Tests First

Purpose: Add failing tests that define the workspace hub navigation contract before runtime changes.

• T007 [P] Add apps/platform/tests/Feature/Navigation/WorkspaceHubRegistryTest.php covering registry entries, explicit exclusions, forbidden query keys, and environment-like persisted filter keys.
• T008 [P] Add apps/platform/tests/Feature/Navigation/WorkspaceHubSidebarUrlContractTest.php with table-driven coverage for every registry workspace hub URL.
• T009 [P] In the sidebar URL contract test, assert every workspace hub URL excludes tenant, tenant_id, managed_environment_id, environment_id, tenant_scope, and tableFilters.
• T010 [P] Add apps/platform/tests/Feature/Workspaces/WorkspaceHubContextContractTest.php covering Environment Dashboard state -> sidebar/global workspace hub entry clears active shell Managed Environment while preserving selected Workspace.
• T011 [P] Add remembered-environment setup to WorkspaceHubContextContractTest.php proving WorkspaceContext::LAST_TENANT_IDS_SESSION_KEY does not affect workspace hub sidebar URLs or shell context.
• T012 [P] Add persisted filter setup to WorkspaceHubContextContractTest.php proving environment-like filters do not override sidebar/global intent for at least Customer Reviews, Finding Exceptions Queue, Evidence, and Provider Connections.

Phase 3: Critical Page Regression Tests

Purpose: Prove the concrete Spec 313 regressions before fixing them.

• T013 [P] Add apps/platform/tests/Feature/ProviderConnections/ProviderConnectionsWorkspaceHubContractTest.php proving sidebar/global Provider Connections entry is workspace-wide and does not inject managed_environment_id.
• T014 [P] In the Provider Connections test, seed two entitled Managed Environments with provider connections and assert both rows are visible from clean workspace entry.
• T015 [P] Add a Provider Connections regression assertion that remembered Managed Environment does not influence ProviderConnectionResource::getUrl('index', panel: 'admin') when used for sidebar/global entry.
• T016 [P] Add apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueWorkspaceHubContractTest.php proving sidebar/global queue entry has no tenant query param and no remembered environment shell restoration.
• T017 [P] In the Finding Exceptions Queue test, seed at least two entitled environments with pending exceptions where practical and assert workspace-wide row scope; if exact row proof is blocked by existing factories, assert table filter/session state and document the limitation in test comments.
• T018 [P] Add apps/platform/tests/Feature/Monitoring/OperationsWorkspaceHubContractTest.php proving sidebar/global Operations entry has no managed_environment_id, tenant_scope, or tableFilters.
• T019 [P] In the Operations test, seed operation runs for two entitled environments and assert sidebar/global entry sees both where fixtures allow.
• T020 [P] Add apps/platform/tests/Feature/Governance/DecisionRegisterWorkspaceHubContractTest.php proving clean Decision Register URL opens for an authorized workspace user without environment query params.
• T021 [P] In the Decision Register test, cover a truthful empty workspace register state instead of 403 when the user is authorized but no environment filter is supplied.
• T022 [P] Add apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceHubContractTest.php proving sidebar/global Customer Review Workspace entry ignores stale environment query/session filters.
• T023 [P] Add apps/platform/tests/Feature/Monitoring/EvidenceOverviewWorkspaceHubContractTest.php proving sidebar/global Evidence Overview entry ignores stale environment-like persisted filters.

Phase 4: Workspace Hub Registry

Purpose: Implement the narrow code-level contract that owns workspace hub identity.

• T024 Create apps/platform/app/Support/Navigation/WorkspaceHubRegistry.php.
• T025 Include registry entries for Workspace Overview, Operations, Provider Connections, Finding Exceptions Queue, Evidence Overview, Review Register, Customer Review Workspace, Governance Inbox, Decision Register, Audit Log, Alerts, Alert Deliveries, Alert Rules, Alert Destinations, Workspace Settings, Manage Workspaces, and Managed Environments Landing.
• T026 Encode explicit exclusions for Stored Reports environment routes, Support Request modal/action surface, Environment Dashboard, and environment child routes in tests or registry documentation.
• T027 Add registry methods for route/page identity checks, clean workspace hub URL policy, forbidden query keys, and environment-like persisted filter keys.
• T028 Keep the registry static/narrow; do not introduce database state, config persistence, provider frameworks, or product IA abstractions.

Phase 5: Central Sidebar and Global URL Generation

Purpose: Ensure workspace hub URLs from central navigation are clean and deterministic.

• T029 Update apps/platform/app/Support/Navigation/WorkspaceSidebarNavigation.php so workspace hub URLs are generated through the clean workspace hub contract.
• T030 Update apps/platform/app/Providers/Filament/AdminPanelProvider.php duplicated navigation items to use the same clean workspace hub URL contract.
• T031 Ensure Operations sidebar/global URL uses clean workspace route with only required workspace route parameter.
• T032 Ensure Provider Connections sidebar/global URL bypasses any ProviderConnectionResource::getUrl() behavior that injects remembered environment context.
• T033 Ensure Finding Exceptions Queue sidebar/global URL does not include tenant.
• T034 Ensure Decision Register, Governance Inbox, Customer Reviews, Reviews, Evidence, Audit Log, Alerts, Workspace Settings, Manage Workspaces, and Workspace Overview sidebar/global URLs exclude all forbidden keys.
• T035 Add or update tests proving WorkspaceSidebarNavigation and AdminPanelProvider navigation sources stay in parity.

Phase 6: Shell and Remembered Environment Isolation

Purpose: Stop remembered or Filament tenant state from becoming a workspace hub default data boundary.

• T036 Inspect apps/platform/app/Support/Tenants/TenantPageCategory.php and apps/platform/app/Support/Navigation/NavigationScope.php and adjust workspace hub classification only where needed.
• T037 Update apps/platform/app/Support/OperateHub/OperateHubShell.php so sidebar/global workspace hub entry resolves as tenantless workspace shell context.
• T038 Ensure WorkspaceContext::rememberedTenant() and lastTenantId() are not used as workspace hub sidebar URL inputs or data filters.
• T039 Preserve remembered Managed Environment switcher convenience outside workspace hub sidebar/global data scope.
• T040 Add assertions to existing or new shell context tests proving valid query hints do not make sidebar/global workspace hub shell environment-scoped.

Phase 7: Persisted Filter Safety

Purpose: Prevent old environment table filters from overriding workspace-wide entry.

• T041 Extend apps/platform/app/Support/Filament/CanonicalAdminTenantFilterState.php or a sibling helper so workspace hub entry can clear/ignore environment-like persisted filters.
• T042 The helper must cover tenant, tenant_id, managed_environment_id, environment_id, environment, and tenant_scope.
• T043 Apply the helper to Customer Review Workspace, Finding Exceptions Queue, Evidence Overview, Review Register, Operations, Audit Log, Alerts/Alert Deliveries, Governance Inbox, and Decision Register where each page uses persisted table/session filters.
• T044 Avoid one-off page clearing unless Livewire lifecycle requires it; if one-off handling is required, document the bounded reason in code comments or implementation close-out.
• T045 Add tests proving session-persisted environment filters are cleared or ignored on clean sidebar/global workspace hub entry.

Phase 8: Critical Page Fixes

Purpose: Resolve the concrete Spec 313 critical/high findings in scope.

• T046 Update apps/platform/app/Filament/Resources/ProviderConnectionResource.php so workspace hub sidebar/global entry is workspace-wide and not filtered by remembered context.
• T047 Keep explicit Provider Connections environment filtering only for explicit CTA/query flows that already exist; do not standardize CTA naming in this spec.
• T048 Update apps/platform/app/Support/ManagedEnvironmentLinks.php only where needed so sidebar/global Provider Connections entry is clean while environment-specific helper calls remain explicit.
• T049 Update apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php so sidebar/global entry does not restore tenant or persisted environment filters.
• T050 Update apps/platform/app/Http/Controllers/OpenFindingExceptionsQueueController.php only if necessary to preserve explicit environment entry while keeping sidebar/global entry clean.
• T051 Update apps/platform/app/Filament/Pages/Monitoring/Operations.php and/or apps/platform/app/Support/OperationRunLinks.php so sidebar/global entry cannot carry managed_environment_id, tenant_scope, or environment tableFilters.
• T052 Update apps/platform/app/Filament/Pages/Governance/DecisionRegister.php so clean workspace URL opens for authorized users and uses workspace/capability authorization rather than requiring an environment filter.
• T053 Update apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php so sidebar/global entry is workspace-wide and stale environment filters do not reload-restore.
• T054 Update apps/platform/app/Filament/Pages/Reviews/ReviewRegister.php so sidebar/global entry is workspace-wide and stale environment filters do not reload-restore.
• T055 Update apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php only where needed to preserve its existing clean clear behavior and enforce sidebar/global stale-filter safety.
• T056 Update apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php only where needed for sidebar/global clean entry; leave explicit CTA filter behavior for Spec 315.

Phase 9: Browser Verification

Purpose: Repeat the focused Spec 313 browser flows after runtime fixes.

• T057 Add apps/platform/tests/Browser/Spec314WorkspaceHubNavigationContextSmokeTest.php or run an equivalent existing browser-smoke pattern if the repo already has the right harness.
• T058 Browser flow: Environment Dashboard -> Sidebar -> Provider Connections, Finding Exceptions Queue, Operations, Decision Register, Customer Reviews, Evidence, Reviews, and Governance Inbox.
• T059 Browser flow: Workspace Overview -> Sidebar -> the same critical pages.
• T060 Browser flow: reload after sidebar entry for Provider Connections, Finding Exceptions Queue, Operations, Decision Register, Customer Reviews, Evidence, Reviews, and Governance Inbox.
• T061 Browser flow: back/forward for Provider Connections, Customer Reviews, Finding Exceptions Queue, Operations, and Decision Register.
• T062 Save screenshots under specs/314-workspace-hub-navigation-context-contract/artifacts/screenshots/ when useful for before/after evidence.
• T063 Record any remaining mismatch as follow-up for Spec 315, 316, or 317 rather than broadening this spec.

Phase 10: Validation and Close-Out

Purpose: Prove the contract and record implementation impact.

• T064 Run cd apps/platform && ./vendor/bin/sail artisan test --filter=WorkspaceHub.
• T065 Run cd apps/platform && ./vendor/bin/sail artisan test --filter=ProviderConnectionsWorkspaceHub.
• T066 Run cd apps/platform && ./vendor/bin/sail artisan test --filter=FindingExceptionsQueueWorkspaceHub.
• T067 Run cd apps/platform && ./vendor/bin/sail artisan test --filter=OperationsWorkspaceHub.
• T068 Run cd apps/platform && ./vendor/bin/sail artisan test --filter=DecisionRegisterWorkspaceHub.
• T069 Run cd apps/platform && ./vendor/bin/sail artisan test --filter=CustomerReviewWorkspaceHub.
• T070 Run cd apps/platform && ./vendor/bin/sail artisan test --filter=EvidenceOverviewWorkspaceHub.
• T071 Run cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec314WorkspaceHubNavigationContextSmoke or document why browser lane could not run.
• T072 Run git diff --check.
• T073 Confirm git diff --name-only contains expected runtime/test files plus specs/314-workspace-hub-navigation-context-contract/ only.
• T074 Confirm no files under apps/platform/database/migrations/ or seeders changed.
• T075 Confirm no new legacy compatibility adapter, alias layer, dual-read, dual-write, migration shim, or backfill was introduced.
• T076 Fill the final implementation report in the format required by spec.md.

Explicit Non-Goals for Implementers

• Do not implement Spec 315 Environment CTA Explicit Filter Contract.
• Do not implement Spec 316 Workspace Hub Clear Filter Contract.
• Do not implement Spec 317 Legacy Tenant / Environment Context Cleanup beyond sidebar/global workspace hub entry.
• Do not implement Spec 318 durable browser regression guard beyond the focused Spec 314 smoke.
• Do not redesign pages, tables, navigation IA, cards, chips, or copy beyond what is required for scope truth.
• Do not change provider credential actions, destructive actions, Graph calls, queues, migrations, seeders, or packages.