TenantAtlas/specs/341-canonical-link-query-cleanup/plan.md

Implementation Plan: Spec 341 - Canonical Link / Query Cleanup

Branch: 341-canonical-link-query-cleanup | Date: 2026-05-31 | Spec: specs/341-canonical-link-query-cleanup/spec.md
Input: Candidate canonical-link-query-cleanup from docs/product/spec-candidates.md + repo inspection of legacy scope query parsing seams.

Summary

Inventory and remove remaining legacy “scope hint” query parsing (tenant, managed_environment_id, etc.) in shared request-scoping seams and align canonical link generation so that:

• workspace hubs are workspace-wide unless explicitly filtered via environment_id;
• environment-bound pages are route-owned and do not accept legacy query aliases as authority; and
• “clear filter” behavior returns to clean canonical URLs.

This is contract hardening; it must not introduce new abstractions, persistence, or UI frameworks.

Technical Context

• Language/Version: PHP 8.4.15, Laravel 12.52.x
• Primary Dependencies: Filament v5, Livewire v4, Pest v4
• Storage: PostgreSQL (no schema changes planned)
• Testing: Pest Feature tests (navigation + scope contracts)
• Validation Lanes: fast-feedback (Feature); browser only if later proven necessary for visible UX behaviors that cannot be asserted reliably in Feature tests
• Target Platform: apps/platform (Sail locally; Dokploy/container posture unchanged)
• Constraints:
  • no compatibility redirects or “legacy alias preservation”
  • no new packages, migrations, queues, scheduler, storage changes
  • deny-as-not-found semantics remain authoritative

UI / Surface Guardrail Plan

• Guardrail scope: existing reachable surfaces; navigation + scope contract hardening
• Affected routes/pages/actions/states (inventory-driven):
  • workspace hubs that accept environment narrowing via environment_id and expose “clear filter” behavior
  • environment-bound pages under /admin/workspaces/{workspace}/environments/{environment}/... that must remain route-owned
  • shared request-scoping seams that must not treat legacy query keys as authority
• State layers in scope: URL/query + route parameters + session workspace context
• Handling mode: review-mandatory (scope/authority semantics)
• Required tests or manual smoke: Feature contract tests for clean vs filtered hub URLs and legacy alias rejection/ignore behavior; browser smoke only if required later
• UI/Productization coverage decision: existing pages changed / navigation semantics changed; no new reachable surface added; do not update docs/ui-ux-enterprise-audit/* unless implementation materially changes navigation entries or routes (not expected)

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched (expected):
  • apps/platform/app/Support/Navigation/WorkspaceHubNavigation.php
  • apps/platform/app/Support/Navigation/WorkspaceHubEnvironmentFilter.php
  • apps/platform/app/Filament/Concerns/UsesAdminEnvironmentFilterQueryParameter.php
  • apps/platform/app/Http/Middleware/EnsureWorkspaceSelected.php
  • apps/platform/app/Support/Middleware/EnsureEnvironmentContextSelected.php
  • apps/platform/app/Support/OperateHub/OperateHubShell.php
  • apps/platform/tests/Feature/Navigation/*
• Shared abstractions reused: existing hub filter contract helpers, WorkspaceContext, deny-as-not-found semantics, existing guard-test patterns
• New abstraction introduced?: none
• Spread control: inventory-driven; limit changes to URL/query scope semantics and canonical link generation only

OperationRun UX Impact

N/A — no OperationRun start/completion/link UX changes.

Implementation Approach

Phase 1 — Repo truth inventory + failing tests first

• inventory every remaining legacy scope query parsing seam (query keys only, not DB naming)
• add/adjust Feature tests that fail on today’s behavior and encode the intended contract

Phase 2 — Remove legacy query scope hint parsing in shared seams

• remove or strictly ignore legacy scope hints in:
  • EnsureWorkspaceSelected
  • EnsureEnvironmentContextSelected
  • OperateHubShell
  • EnvironmentRequiredPermissions (query-hint handling only)
• ensure out-of-scope requests preserve deny-as-not-found semantics

Phase 3 — Align canonical link generation

• ensure link generation:
  • never emits legacy scope query keys
  • uses environment_id only for workspace hub narrowing
  • does not treat environment_id as a replacement for route-owned environment pages

Phase 4 — Regression guards

• add/extend guard tests that block:
  • parsing legacy scope keys as authority
  • generating navigation URLs containing forbidden scope query keys

Phase 5 — Validation + close-out

• run the narrowest Feature tests
• run pint on dirty files and git diff --check

Test Governance Check

• Test purpose / classification: Feature
• Affected validation lanes: fast-feedback (Feature)
• Narrowest proving command(s):
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Navigation --filter=Spec341
• Fixture / helper cost risks: none expected; reuse existing workspace/environment factories + navigation harness helpers
• Escalation path: document-in-feature if a bounded exception is proven necessary; otherwise treat legacy alias preservation as a blocker

Deployment / Ops Impact

No migrations, env vars, queues, scheduler, storage, or asset pipeline changes are planned.

Constitution Check (subset)

• Proportionality: no new persistence/abstractions/taxonomy introduced
• Compatibility posture: legacy alias preservation is out of scope
• Scope & isolation: route-owned environment remains authoritative; hub narrowing is environment_id only; deny-as-not-found semantics preserved