TenantAtlas/specs/313-workspace-environment-context-browser-verification/plan.md

# Implementation Plan: Full Workspace / Environment Context Browser Verification Audit

**Branch**: `313-workspace-environment-context-browser-verification` | **Date**: 2026-05-16 | **Spec**: `specs/313-workspace-environment-context-browser-verification/spec.md`
**Input**: Feature specification from `specs/313-workspace-environment-context-browser-verification/spec.md`

## Summary

Prepare and execute an analysis-only audit that discovers every relevant TenantPilot admin surface from repo sources and browser-verifies Workspace / Managed Environment context behavior. The audit produces markdown matrices, screenshots, and a risk-ranked remediation sequence. It must not change runtime code, tests, migrations, routes, resources, views, config, seeders, or behavior.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52.0
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, PostgreSQL via Sail, Codex Browser / Playwright-style browser tooling where available
**Storage**: No database schema changes. Audit may read local seeded data only.
**Testing**: Browser/manual verification and repo-discovery checks; no Pest runtime changes in Spec 313.
**Validation Lanes**: docs/spec validation, browser verification, optional read-only route/db inspection.
**Target Platform**: TenantPilot admin panel under `apps/platform`.
**Project Type**: Laravel monolith in a repo with Spec Kit under `.specify/`.
**Performance Goals**: Discovery commands and browser flows should be bounded and evidence-focused; no broad test-suite expansion.
**Constraints**: No runtime edits. No test edits. No migrations. No seeders. No route/resource/page/view/config edits. No commits unless explicitly requested.
**Scale/Scope**: all discovered admin surfaces that interact with workspace/environment context, route/query/table/session state, navigation, dashboard CTAs, or link helpers.

## UI / Surface Guardrail Plan

- **Guardrail scope**: observed admin shell/context/filter/navigation behavior only.
- **Native vs custom classification summary**: existing Filament pages/resources/widgets/views; no new UI.
- **Shared-family relevance**: navigation, context bar, table filters, dashboard action cards, header actions, row actions, report/evidence/review links, support/help links.
- **State layers in scope**: route params, query params, shell context, breadcrumbs, visible filter chips, Filament table filters, deferred table filters, session-persisted table state, Livewire hydration, remembered environment state, browser reload, back, and forward.
- **Audience modes in scope**: MSP/admin operator and customer-safe review consumption surfaces where already present.
- **Decision/diagnostic/raw hierarchy plan**: N/A for runtime; audit report must separate executive findings from raw matrix evidence.
- **Raw/support gating plan**: do not bypass gated surfaces; classify blocked or system/support-scoped.
- **One-primary-action / duplicate-truth control**: N/A for runtime; clear-filter behavior is observed and documented.
- **Handling modes by drift class or surface**: critical/high/medium/low risk classification in `audit-report.md`.
- **Repository-signal treatment**: every source hit is inventory input, not final truth until classified.
- **Special surface test profiles**: `global-context-shell`, `monitoring-state-page`, `shared-detail-family`, `exception-coded-surface`, `environment-owned-resource`.
- **Required tests or manual smoke**: browser verification is required for in-scope reachable surfaces; missing data/tooling becomes explicit blocker.
- **Exception path and spread control**: no exceptions to no-runtime-change rule.
- **Active feature PR close-out entry**: `Spec 313 Audit Evidence / No Runtime Changes`.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: context contract audit across admin shell, route/query/filter state, and link helpers.
- **Systems touched by inspection**:
  - `apps/platform/app/Providers/Filament/AdminPanelProvider.php`
  - `apps/platform/app/Support/Navigation/WorkspaceSidebarNavigation.php`
  - `apps/platform/routes/web.php`
  - `apps/platform/app/Filament/Pages`
  - `apps/platform/app/Filament/Resources`
  - `apps/platform/app/Filament/Clusters`
  - `apps/platform/resources/views`
  - `apps/platform/app/Support/Operations`
  - `apps/platform/app/Support/ManagedEnvironmentLinks.php`
  - `apps/platform/app/Support/Filament`
  - `apps/platform/app/Support/Tenants`
  - `apps/platform/app/Support/Workspaces`
  - dashboard summary builders, context bar, support/report/evidence/review helpers.
- **Shared abstractions reused**: none modified. Audit maps existing `WorkspaceContext`, `OperateHubShell`, `ResolvedShellContext`, `TenantPageCategory`, `NavigationScope`, `ManagedEnvironmentLinks`, `OperationRunLinks`, `CanonicalAdminTenantFilterState`, table persistence APIs, and page state contracts.
- **New abstraction introduced? why?**: none.
- **Why the existing abstraction was sufficient or insufficient**: unknown until audit completes. The plan is to prove which mechanisms currently compete.
- **Bounded deviation / spread control**: all findings stay under `specs/313-workspace-environment-context-browser-verification/`.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no runtime touch. Operations page and `OperationRunLinks` are audited.
- **Central contract reused**: existing `OperationRunLinks::index()` and operation detail routes are observed.
- **Delegated UX behaviors**: unchanged.
- **Surface-owned behavior kept local**: unchanged.
- **Queued DB-notification policy**: unchanged.
- **Terminal notification path**: unchanged.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: audit observes provider connection and provider readiness/required permissions surfaces.
- **Provider-owned seams**: Microsoft/Entra/Intune semantics in provider readiness, required permissions, Graph callback/onboarding, and environment resources are not changed.
- **Platform-core seams**: workspace hub navigation, provider connection workspace view, environment filter semantics, operation/evidence/review reporting surfaces.
- **Neutral platform terms / contracts preserved**: workspace, managed environment, provider connection, environment filter, workspace-wide hub.
- **Retained provider-specific semantics and why**: observed only; no refactor.
- **Bounded extraction or follow-up path**: likely Spec 314/315/316/317 based on evidence.

## Constitution Check

- Inventory-first: PASS. No inventory or snapshot truth changes.
- Read/write separation: PASS. Audit-only, read-only verification.
- Graph contract path: PASS. No Graph calls are added or changed.
- Deterministic capabilities: PASS. Existing capabilities only gate visibility/access during verification.
- Workspace isolation: PASS. Audit must not bypass workspace access.
- Tenant/environment isolation: PASS. Audit must not bypass environment access.
- RBAC-UX: PASS. Blocked access is recorded as evidence.
- Run observability: N/A. No operations are started.
- Test governance: PASS. Browser verification is explicit audit scope, not hidden test-suite growth.
- Proportionality: PASS. No runtime complexity; temporary audit artifacts only.
- No premature abstraction: PASS. No abstraction introduced.
- Persisted truth: PASS. No new database or runtime truth.
- Shared pattern first: PASS. Existing shared paths are mapped before remediation.
- Provider boundary: PASS. No provider/platform seam changes.
- Filament-native UI: PASS. Existing UI observed only.

## Test Governance Check

- **Test purpose / classification by changed surface**: docs/spec prep now; browser audit during Spec 313 implementation.
- **Affected validation lanes**: docs/spec validation, browser/manual verification.
- **Why this lane mix is narrowest sufficient proof**: The audit question is browser behavior, not unit behavior. Filament persisted filters and Livewire hydration require browser observation.
- **Narrowest proving commands**: discovery commands, Browser screenshots, `git diff --name-only`, `git diff --check`.
- **Fixture / helper / factory / seed / context cost risks**: no fixture changes allowed; missing seeded data becomes blocker.
- **Expensive defaults or shared helper growth introduced?**: none.
- **Heavy-family additions, promotions, or visibility changes**: none in preparation. Browser evidence is the feature output.
- **Surface-class relief / special coverage rule**: no runtime UI change, so no visual regression requirement beyond screenshot evidence.
- **Closing validation and reviewer handoff**: verify all required files exist, screenshots are referenced, no runtime files changed, and every surface has final status.
- **Budget / baseline / trend follow-up**: none.
- **Review-stop questions**: any runtime file change, unclassified surface, "likely OK" status, unreferenced screenshot, claimed data-scope proof without rows, or missing command log.
- **Escalation path**: remediation follow-up spec, not in Spec 313.
- **Active feature PR close-out entry**: `Spec 313 Audit Evidence / No Runtime Changes`.

## Project Structure

### Preparation Artifacts Created Now

```text
specs/313-workspace-environment-context-browser-verification/
├── checklists/
│   └── requirements.md
├── spec.md
├── plan.md
└── tasks.md
```

### Audit Artifacts To Create During Spec 313 Execution

```text
specs/313-workspace-environment-context-browser-verification/
├── audit-report.md
├── surface-inventory.md
├── page-matrix.md
├── query-param-inventory.md
├── clear-filter-inventory.md
├── code-ownership-map.md
└── artifacts/
    ├── context-search.txt
    ├── filament-files.txt
    ├── routes-admin.txt
    └── screenshots/
```

### Must Not Change

```text
apps/platform/app/
apps/platform/config/
apps/platform/database/
apps/platform/resources/
apps/platform/routes/
apps/platform/tests/
apps/platform/lang/
apps/platform/package.json
apps/platform/composer.json
```

## Current Repo Findings From Preparation

These findings guide the audit plan only. They are not final browser conclusions.

- `docs/product/roadmap.md` still recommends "Spec 313" for Decision-Based Governance Inbox v1. This is a numbering note, not a completed spec conflict: the user directly supplied Spec 313 as the workspace/environment context browser verification audit. Product roadmap docs are not edited in this preparation-only package.
- Admin panel provider registers workspace/global navigation and pages in `apps/platform/app/Providers/Filament/AdminPanelProvider.php`.
- Workspace sidebar builder exists at `apps/platform/app/Support/Navigation/WorkspaceSidebarNavigation.php` and includes Finding Exceptions Queue, Operations, Alerts, Audit Log, Reviews, Customer Reviews, Provider Connections/Integrations, Workspace Settings, Manage Workspaces, Governance Inbox, and Decision Register.
- Admin routes include workspace hubs such as `/admin/workspaces/{workspace}/operations`, `/admin/provider-connections`, `/admin/finding-exceptions/queue`, `/admin/evidence/overview`, `/admin/reviews`, `/admin/reviews/workspace`, `/admin/governance/inbox`, `/admin/governance/decisions`, `/admin/audit-log`, `/admin/alerts`, and environment-owned routes under `/admin/workspaces/{workspace}/environments/{environment}/...`.
- `WorkspaceContext` stores `current_workspace_id` and `workspace_last_tenant_ids`, so remembered environment behavior is a required audit target.
- `OperateHubShell` resolves route tenant, query hint tenant, Filament tenant, remembered tenant, and tenantless workspace state. Its precedence is a required code ownership seam.
- `ManagedEnvironmentLinks` passes `managed_environment_id` for provider connections and operations URLs when given an environment.
- `OperationRunLinks::index()` uses `managed_environment_id`, `tenant_scope=all`, `activeTab`, `problemClass`, and `tableFilters[type][value]`.
- `ProviderConnectionResource` is not tenant-scoped but contains request/context tenant resolution paths, including `managed_environment_id`, Livewire original URL/referer extraction, and remembered context fallback.
- `FindingExceptionsQueue` uses `tenant` as a contextual prefilter, persisted table state, clear-filter action, and selected exception query param.
- `EvidenceOverview`, `ReviewRegister`, and `CustomerReviewWorkspace` persist filters/search/sort in session and expose clear-filter behavior.
- `GovernanceInbox` and `DecisionRegister` use `managed_environment_id` query params and clearable URL construction, making them likely reference candidates for explicit filter behavior.
- Environment Dashboard CTAs and `EnvironmentDashboardSummaryBuilder` link to tenant-owned resources, operations, customer workspace, evidence, review packs, required permissions, and governance inbox paths.
- Reports / Stored Reports and Support Requests need explicit classification because route visibility and entry points are not obvious from sidebar alone.

## Required Markdown File Schemas

### `surface-inventory.md`

Columns:

```text
Surface | Type | Class/resource/component | Route | Sidebar visible? | Dashboard/card/action linked? | Workspace-scoped? | Environment-scoped? | System/platform scoped? | Ambiguous? | Browser verified? | Final status | Notes
```

### `page-matrix.md`

Columns:

```text
Page | Origin | URL | Query params | Shell workspace | Shell environment | Breadcrumb | Header/title | Visible scope/filter chip | Table filter state | Data scope proven? | Clear filter exists? | Clear filter result | Reload result | Back/forward result | Screenshot | Status | Risk | Notes
```

Allowed origins:

```text
workspace_origin
environment_sidebar_origin
environment_cta_origin
manual_filter_origin
reload
back_forward
```

### `query-param-inventory.md`

Columns:

```text
Query param | Pages using it | Identifier type | Allowed? | Visible to user? | Clearable? | Persisted? | Conflicts | Notes
```

Identifier type values:

```text
database_id
slug
external_id
mixed
unknown
not_applicable
```

Required params:

```text
tenant
tenant_id
managed_environment_id
environment_id
tenant_scope
tableFilters
```

### `clear-filter-inventory.md`

Columns:

```text
Page | Filter type | Clear action exists? | Clear action label | Clears visible chip? | Clears URL query? | Clears Livewire property? | Clears Filament table filter? | Clears deferred filters? | Clears persisted/session state? | Clears actual data scope? | Reload safe? | Sidebar revisit safe? | Risk | Notes
```

### `code-ownership-map.md`

Columns:

```text
Behavior | File | Class/method/view | Pages affected | Risk | Notes
```

Must include these seams:

```text
Sidebar navigation URLs
Page getUrl overrides
Route helpers
Environment Dashboard CTAs
Workspace Overview CTAs
Header actions
Table row actions
Context bar
Shell context resolver
WorkspaceContext remembered environment
Filament tenant resolver
Table filter definitions
QueryString definitions
Livewire mount/hydration
Clear-filter actions/controllers
Canonical filter state helpers
Provider connection filter behavior
Finding exceptions filter behavior
Evidence filter behavior
Reviews/customer reviews filter behavior
Operations filter behavior
```

## Browser Verification Methodology

1. Start from a clean workspace browser state or document existing state.
2. Use an authorized local user and at least one workspace with two managed environments if available.
3. Verify workspace-origin flows first, then environment-sidebar flows, then environment CTA/card flows.
4. Capture screenshots with stable filenames under `artifacts/screenshots/`.
5. Record URL, query params, shell workspace/environment, breadcrumbs, title, chips, filters, table state, data-scope proof, clear-filter behavior, reload behavior, and back/forward behavior.
6. Mark data scope proven only when rows from at least two environments or explicit UI row labels make scope testable.
7. If seed data is absent, record shell-only observation and classify with an allowed blocked or ambiguous final status.
8. Reconcile browser findings back to repo seams and risk levels.

## High-Risk Browser Flow Set

Minimum stable screenshots:

```text
workspace-origin--operations.png
environment-sidebar--operations.png
environment-cta--operations.png
environment-cta--operations--after-clear.png
environment-cta--operations--after-reload.png

workspace-origin--provider-connections.png
environment-sidebar--provider-connections.png
environment-cta--provider-connections.png
environment-cta--provider-connections--after-clear.png
environment-cta--provider-connections--after-reload.png

workspace-origin--finding-exceptions-queue.png
environment-sidebar--finding-exceptions-queue.png
environment-cta--finding-exceptions-queue.png
environment-cta--finding-exceptions-queue--after-clear.png
environment-cta--finding-exceptions-queue--after-reload.png

workspace-origin--evidence.png
environment-sidebar--evidence.png
environment-cta--evidence.png
environment-cta--evidence--after-clear.png
environment-cta--evidence--after-reload.png

workspace-origin--reviews.png
environment-sidebar--reviews.png
environment-cta--reviews.png
environment-cta--reviews--after-clear.png

workspace-origin--customer-reviews.png
environment-sidebar--customer-reviews.png
environment-cta--customer-reviews.png
environment-cta--customer-reviews--after-clear.png

workspace-origin--governance-inbox.png
environment-sidebar--governance-inbox.png
environment-cta--governance-inbox.png

workspace-origin--decision-register.png
environment-sidebar--decision-register.png
environment-cta--decision-register.png
```

Additional pages follow the same naming convention.

## Discovery Commands

Use repo-local commands and write audit artifacts during Spec 313 execution:

```bash
git status --short --branch
cd apps/platform
find app/Filament -type f | sort > ../../specs/313-workspace-environment-context-browser-verification/artifacts/filament-files.txt
rg "getNavigationUrl|getUrl\\(|route\\(|->url\\(|Action::make|HeaderActions|tableFilters|persistFiltersInSession|defaultTableFilters|queryString|managed_environment_id|environment_id|tenant_scope|tenant_id|request\\('tenant'|Filament::getTenant|getTenant\\(|lastTenantId|lastEnvironmentId|clearFilter|clearEnvironment|clearScope" app resources routes tests -n > ../../specs/313-workspace-environment-context-browser-verification/artifacts/context-search.txt
```

Recommended route discovery:

```bash
cd apps/platform
./vendor/bin/sail artisan route:list --path=admin > ../../specs/313-workspace-environment-context-browser-verification/artifacts/routes-admin.txt
```

If Sail is unavailable, document that and use the Laravel Boost route listing or non-Docker fallback only for read-only route inspection.

## Optional Read-Only Test Commands

Run only if useful for audit confidence. Do not edit tests.

```bash
cd apps/platform
./vendor/bin/sail artisan test --compact --filter=Navigation
./vendor/bin/sail artisan test --compact --filter=Workspace
./vendor/bin/sail artisan test --compact --filter=Environment
```

If no tests are run, `audit-report.md` must state:

```text
Tests were not run. This spec was a read-only browser/code audit.
```

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| Broad audit surface | Systemic context drift crosses many surfaces and state carriers | Starting localized fixes before classifying all surfaces risks another partial remediation |
| Browser screenshots as required evidence | Livewire, SPA-like navigation, reload, and persisted Filament state differ from code-only assumptions | Code-only audit already proved insufficient for safe remediation |

## Implementation Phases

1. **Setup and safety**: confirm branch, working tree, no runtime edits, create audit artifact directories.
2. **Repo discovery**: inventory pages/resources/clusters/routes/navigation/actions/link helpers/query params/filter methods.
3. **Static classification draft**: classify likely workspace/environment/system/ambiguous surfaces before browser runs.
4. **Browser data readiness**: identify local workspace, two managed environments, user, and seed row coverage.
5. **Workspace-origin browser flow**: verify all workspace hubs from clean workspace origin.
6. **Environment-sidebar browser flow**: verify workspace hubs after environment dashboard/sidebar origin.
7. **Environment CTA/card browser flow**: verify CTA-filtered workspace hub flows and environment-owned pages.
8. **Manual filter/reload/back-forward flow**: verify high-risk persisted filter behavior.
9. **Clear-filter flow**: verify clear actions and state carriers.
10. **Matrix reconciliation**: reconcile browser evidence against repo inventory and code ownership map.
11. **Risk ranking and follow-up specs**: produce final remediation sequence.
12. **Close-out validation**: verify required files/screenshots exist, no runtime files changed, and final report includes commands/results.

## Definition of Done For Spec 313 Execution

- All required output files exist.
- Every discovered surface has an allowed final status.
- High-risk pages have required screenshots or documented blocker.
- Reports / Stored Reports and Support Requests are classified.
- Query parameter inventory includes all required params.
- Clear-filter inventory documents all clear actions and gaps.
- Code ownership map points to likely repo seams for remediation.
- Audit report includes counts, highest-risk findings, remediation sequence, exact commands, browser/test results, and no-runtime-change statement.
- `git diff --name-only` shows only files under `specs/313-workspace-environment-context-browser-verification/`.
- `git diff --check` passes.

## No Runtime Change Contract

Spec 313 implementation must not modify application runtime code. If a browser issue is found, record it in the audit report and propose a follow-up spec. Do not fix it inside Spec 313.

## Preparation Analyze Notes

Preparation review criteria:

- `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md` must exist.
- No template placeholders should remain.
- The tasks must lead to the required audit files and screenshots.
- The scope must remain analysis-only.
- Related completed specs 311 and 312 must be context only.
- Follow-up specs 314+ must not be started.