TenantAtlas/specs/338-workspace-environment-resource-scope-contract/tasks.md

Tasks: Spec 338 - Workspace / Environment Resource Scope Contract

• Input: specs/338-workspace-environment-resource-scope-contract/spec.md, specs/338-workspace-environment-resource-scope-contract/plan.md
• Preparation status: implemented + validated.

Tests: Required. This spec changes canonical link/query contract semantics for operator-facing hubs.

Test Governance Checklist

• Lane assignment remains explicit and narrowest sufficient (Feature + optional Browser smoke).
• No new default-heavy helpers/factories/seeds are introduced.
• Contract changes are guarded by deterministic tests before refactors.
• Any exception resolves as document-in-feature, follow-up-spec, or reject-or-split.

Phase 1: Preparation And Repo Truth (blocks runtime changes)

Purpose: Confirm repo truth and lock the current contract seams before changing runtime behavior.

• T001 Re-read spec.md + plan.md + this tasks.md.
• T002 Confirm working tree intent and record baseline commit (git status, git log -1).
• T003 Re-verify dependency specs as context only (do not reopen them):
  • specs/311-workspace-environment-surface-scope-contract/ (implemented)
  • specs/320-workspace-owned-analysis-surface-registration-shell-cutover/ (completed)
  • specs/322-browser-no-drift-regression-guard/ (guard posture)
• T004 Inspect the confirmed helper seams:
  • apps/platform/app/Support/OperationRunLinks.php (currently emits tableFilters[type][value] for operationType)
  • apps/platform/app/Support/Navigation/CanonicalNavigationContext.php (toQuery() behavior)
  • apps/platform/app/Support/Navigation/RelatedNavigationResolver.php (filter payload injection)
  • apps/platform/app/Filament/Pages/Monitoring/Operations.php (query parsing + filter handling)
  • apps/platform/app/Http/Controllers/ClearEnvironmentContextController.php (/admin/evidence/* special casing)
  • apps/platform/app/Support/Navigation/AdminSurfaceScope.php (evidence path classification)
  • apps/platform/routes/web.php (/admin/evidence/overview, operations routes)
• T005 Inspect existing guard tests that already encode parts of the contract:
  • apps/platform/tests/Feature/Navigation/Spec322LegacyQueryAliasGuardTest.php
  • apps/platform/tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php
  • apps/platform/tests/Unit/Tenants/AdminSurfaceScopeTest.php

Phase 2: Add failing contract tests first

Purpose: Make contract changes reviewable and regression-proof.

• T006 Add a new Spec 338 contract test for OperationRunLinks::index(..., operationType: ...):
  • asserts the generated URL does not contain tableFilters
  • asserts operation type deep-linking uses operation_type or is intentionally not supported
• T007 Add/extend tests ensuring environment filtering remains canonical:
  • environment_id works for Operations hub filtering
  • legacy aliases remain ignored (no regression vs Spec 322)
• T008 Add/extend Evidence scope tests:
  • Evidence Overview is workspace hub (/admin/evidence/overview)
  • /admin/evidence/* special casing is either removed as stale or explicitly covered by a route-inventory-backed test

Phase 3: Implement OperationRunLinks query contract

Purpose: Remove Filament internals from first-party helper outputs.

• T009 Update apps/platform/app/Support/OperationRunLinks.php so operationType does not emit tableFilters[type][value].
• T010 Decide and implement one of:
  • Map operation_type query to internal table state in apps/platform/app/Filament/Pages/Monitoring/Operations.php, or
  • Remove operation type deep-linking and keep only environment filtering + tabs/problem classes.
• T011 Update any call sites that depended on helper-emitted tableFilters and make them use the new canonical key (or drop the feature).

Phase 4: Navigation context payload hygiene

Purpose: Stop emitting legacy alias filters in navigation contexts.

• T012 Audit CanonicalNavigationContext usage where filterPayload includes tableFilters[managed_environment_id] and confirm whether it is still needed.
• T013 Update call sites (e.g. RelatedNavigationResolver) to avoid injecting legacy alias filters when linking to workspace hubs; use environment_id where filter intent exists.
• T014 Ensure no first-party helper emits legacy query aliases for hub filtering (tenant, tenant_id, managed_environment_id, tenant_scope, tableFilters) as canonical contract.

Phase 5: Evidence scope special casing cleanup

Purpose: Reduce ambiguity and stale branching.

• T015 Confirm whether any /admin/evidence/* non-overview route family is real and reachable on current branch:
  • if not real: remove/neutralize stale handling in ClearEnvironmentContextController and AdminSurfaceScope
  • if real: document intent in Spec 338 and add explicit tests proving the contract
• T016 Ensure Evidence Overview remains a workspace hub and accepts only explicit environment_id filtering.

Phase 6: Regression posture (baseline ownership)

Purpose: Ensure Spec 320 baseline ownership/navigation remains stable.

• T017 Confirm existing baseline ownership tests remain green (no new baseline work unless regression is proven):
  • apps/platform/tests/Feature/Baselines/BaselineProfileWorkspaceOwnershipTest.php
  • any Spec 320/322 smoke coverage already in repo

Phase 7: Optional browser smoke (only if navigation presentation changes)

• T018 Add a minimal browser smoke test apps/platform/tests/Browser/Spec338ScopeContractSmokeTest.php covering:
  • environment → operations filtered link uses environment_id
  • clearing environment context from an evidence page returns to Evidence Overview hub without ambiguous redirects

Phase 8: Validation

• T021 Add the sidebar scope identity indicator requested during browser review:
  • workspace-owned pages show Workspace scope + active workspace without a negative “no environment selected” topbar or picker status
  • environment-owned pages show Environment scope + active environment + containing workspace
  • use Filament render hooks rather than publishing internal sidebar views
• T022 Split environment sidebar IA for workspace-owned links:
  • workspace-wide hub entries move into a separate Workspace-wide group on environment pages
  • workspace configuration/admin entries move into Workspace admin
  • supported hub links carry explicit environment_id; clean workspace/admin links remain unfiltered
• T023 Remove the redundant “Choose environment” CTA from the Managed Environments registry:
  • environment cards remain the entry/open affordance
  • supporting actions stay limited to Add Environment and Switch Workspace
  • /admin/choose-environment remains the dedicated fast context-switch surface
• T024 Remove generic tenantless “All environments” badges from workspace-wide pages:
  • header scope actions are omitted when no concrete environment context exists
  • explicit environment_id filters remain visible through filter banners/table chips
• T019 Run narrow tests first:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact <new/updated Spec 338 tests>
• T020 Run formatting and patch checks:
  • cd apps/platform && ./vendor/bin/sail pint --dirty --format agent
  • git diff --check

Explicit Non-Goals

• NT001 Do not add migrations, new tables, or persisted truth.
• NT002 Do not restructure route families; keep canonical workspace/environment routes.
• NT003 Do not introduce a new navigation taxonomy framework; reuse existing AdminSurfaceScope / hub registry seams.
• NT004 Do not change destructive action behavior (confirmation/authorization/audit).