TenantAtlas/specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/plan.md

# Implementation Plan: Browser Audit Fixture Coverage for Evidence/System Surfaces v1

**Branch**: `376-browser-audit-fixture-coverage-evidence-system-surfaces` | **Date**: 2026-06-13 | **Spec**: `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/spec.md`
**Input**: Feature specification from `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/spec.md`

## Summary

Create a bounded local/testing browser fixture coverage package for five surfaces that were blocked, unstable, or spread across follow-up evidence after Spec 368: Evidence Snapshot View, Required Permissions, System Dashboard, System Operations, and Provider Connection Detail. Reuse existing admin smoke-login, direct Browser `actingAs()`/workspace-session harnesses, Spec 353/372 browser evidence, browser fixture seeding, scoped URL helpers, system panel auth patterns, and Pest Browser support. Do not redesign product UI or weaken production auth.

## 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, Laravel Sail
**Storage**: PostgreSQL locally via Sail; no new schema planned
**Testing**: Pest 4 Feature tests and Pest Browser smoke
**Validation Lanes**: fast-feedback/confidence for Feature tests, browser lane for screenshots
**Target Platform**: Laravel monolith under `apps/platform`
**Project Type**: Web app / Filament admin and system panels
**Performance Goals**: Fixture setup remains deterministic and bounded; browser smoke covers only five target surfaces
**Constraints**: No production-accessible fixture auth; no real customer data; no Graph calls during page render; no product UI refactor
**Scale/Scope**: Five surfaces, one spec-local evidence package, minimal local/testing fixture glue only if existing patterns are insufficient

## UI / Surface Guardrail Plan

- **Guardrail scope**: browser fixture/auditability for existing pages plus possible local/testing-only route.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - Evidence Snapshot View
  - Required Permissions
  - `/system`
  - `/system/ops/runs`
  - Provider Connection Detail
  - possible local/testing system smoke fixture route
- **No-impact class, if applicable**: no production product UI material change.
- **Native vs custom classification summary**: Existing pages remain native Filament/resource/page surfaces. Fixture route is tooling/test-only.
- **Shared-family relevance**: evidence viewer, provider readiness, system platform auth, browser smoke.
- **State layers in scope**: route, session/auth guard, workspace context, environment context, fixture data.
- **Audience modes in scope**: operator-MSP/support-platform; no customer content changes.
- **Decision/diagnostic/raw hierarchy plan**: document what the pages show; do not alter it.
- **Raw/support gating plan**: unchanged; document any issue as follow-up.
- **One-primary-action / duplicate-truth control**: N/A for implementation unless fixture code accidentally adds UI, which is forbidden.
- **Handling modes by drift class or surface**: blocked reachability becomes `document-in-feature`; UI defects become follow-up candidates.
- **Repository-signal treatment**: Specs 368 and 375 provide source signals; route/auth/test files provide repo truth.
- **Coverage registry plan**: No `docs/ui-ux-enterprise-audit` update is required unless implementation materially changes a production surface. Spec-local reports and screenshots are required.
- **Required tests or manual smoke**: targeted Feature tests for fixture auth safety and scoped route behavior; Pest Browser smoke for five surfaces where reachable.

## Architecture / Surface Approach

### Phase 1 - Source audit and route truth

Inspect and document:

- Spec 368 blocked pages and screenshots.
- Spec 353 Required Permissions / Provider Connection browser evidence and Spec 372 Evidence Snapshot browser evidence.
- Spec 370-375 relevant artifacts and whether they are available.
- Current Laravel route list for admin evidence, required permissions, system dashboard, system operations, provider connection detail, and existing smoke-login routes.
- Existing admin smoke-login implementation in `apps/platform/routes/web.php`.
- Existing review-output browser fixture command and tests.
- Existing system panel auth model: `SystemPanelProvider`, `PlatformUser`, `PlatformCapabilities`, `UseSystemSessionCookie`, `EnsurePlatformCapability`, and related tests.
- Existing resource/page route helpers:
  - `EvidenceSnapshotResource`
  - `EnvironmentRequiredPermissions`
  - `RequiredPermissionsLinks`
  - `ProviderConnectionResource`

Output: `artifacts/source-audit-summary.md`, `artifacts/route-reachability-report.md`.

### Phase 2 - Fixture design

For each surface, decide one of:

- `repo-verified`
- `browser-verified`
- `fixture-backed`
- `local-only`
- `test-only`
- `auth-blocked`
- `scope-blocked`
- `data-blocked`
- `route-blocked`
- `timeout-blocked`
- `deferred`
- `not available`

Admin-plane surfaces should first reuse:

- `/admin/local/smoke-login`
- direct Browser `actingAs()` with explicit workspace/environment session context
- Spec 353 and Spec 372 browser fixture/test patterns where they already prove current repo truth
- `SeedReviewOutputBrowserFixture`
- existing factories and test helpers
- existing scoped URL helpers

System-plane surfaces should first reuse:

- `PlatformUser::factory()`
- `PlatformCapabilities::ACCESS_SYSTEM_PANEL`
- existing system-panel Browser `actingAs($platformUser, 'platform')` pattern
- existing system panel auth tests
- Pest Browser `actingAs($platformUser, 'platform')` style if sufficient

Only add a system local/testing smoke-login route if the source audit proves existing Pest Browser platform-guard authentication cannot produce the required evidence and the route can be protected by environment checks, platform guard separation, and redirect allowlist validation.

Output: `artifacts/fixture-design.md`, `artifacts/fixture-coverage-matrix.md`.

### Phase 3 - Safe implementation

Allowed implementation areas only if necessary:

- `apps/platform/routes/web.php` for a local/testing-only system smoke fixture route only after existing Browser `actingAs(..., 'platform')` patterns prove insufficient.
- `apps/platform/config/...` only for fixture config if an existing fixture config pattern is reused.
- `apps/platform/app/Console/Commands/...` only if extending an existing local/testing fixture seed command is narrower than adding a new helper.
- `apps/platform/tests/Feature/Auth/...` for fixture route safety.
- `apps/platform/tests/Feature/...` for scoped fixture behavior.
- `apps/platform/tests/Browser/...` for Spec 376 smoke coverage.

Forbidden implementation areas unless a later explicit spec changes scope:

- migrations, models, policies, product services, jobs, Filament resources/pages, Livewire components, views, Graph contracts, OperationRun services, UI action logic, production auth behavior.

### Phase 4 - Browser verification

Use Pest Browser per Pest 4 docs and existing repo browser tests:

- `visit()` to open each resolved fixture URL.
- `assertNoJavaScriptErrors()` and `assertNoConsoleLogs()` where page reaches the intended surface.
- Capture screenshots for reachable pages.
- If blocked, capture a blocked screenshot when the browser reaches a login/error page and document final URL/status.

Required screenshot names:

- `artifacts/screenshots/001-evidence-snapshot-view.png` or `001-evidence-snapshot-view-blocked.png`
- `artifacts/screenshots/002-required-permissions.png` or `002-required-permissions-blocked.png`
- `artifacts/screenshots/003-system-dashboard.png` or `003-system-dashboard-blocked.png`
- `artifacts/screenshots/004-system-operations.png` or `004-system-operations-blocked.png`
- `artifacts/screenshots/005-provider-connection-detail.png` or `005-provider-connection-detail-blocked.png`

Output: `artifacts/browser-verification-report.md`, `artifacts/screenshot-index.md`.

### Phase 5 - Validation and close-out

Record:

- Branch, HEAD, dirty status before/after implementation.
- Changed files and production impact.
- Commands run, test lane, browser result, screenshots.
- Known limitations and follow-up candidates.

Output: `artifacts/affected-files.md`, `artifacts/validation-report.md`, `artifacts/follow-up-recommendations.md`.

## Existing Repository Surfaces Likely Affected

- `apps/platform/routes/web.php`
- `apps/platform/app/Console/Commands/SeedReviewOutputBrowserFixture.php`
- `apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php` (read-only context unless fixture bug proves otherwise)
- `apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php` (read-only context)
- `apps/platform/app/Support/Links/RequiredPermissionsLinks.php` (read-only context)
- `apps/platform/app/Filament/Resources/ProviderConnectionResource.php` (read-only context)
- `apps/platform/app/Providers/Filament/SystemPanelProvider.php` (read-only context)
- `apps/platform/app/Filament/System/Pages/Ops/Runs.php` (read-only context)
- `apps/platform/app/Models/PlatformUser.php` (read-only context)
- `apps/platform/tests/Feature/Auth/AdminLocalSmokeLoginTest.php`
- `apps/platform/tests/Feature/Auth/SystemPanelAuthTest.php`
- `apps/platform/tests/Feature/Rbac/SystemPanelAccessBoundaryTest.php`
- `apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php`
- `apps/platform/tests/Feature/RequiredPermissions/*`
- `apps/platform/tests/Feature/ProviderConnections/*`
- `apps/platform/tests/Browser/*`

## Domain / Model Implications

- No new domain model is planned.
- Evidence snapshots, provider connections, managed environments, workspaces, users, and platform users are existing repo truth.
- Fixture creation must use existing factories/services and remain deterministic.
- No existing source-of-truth semantics are changed.

## UI / Filament Implications

- Livewire v4.0+ compliance is required and already satisfied by the project stack.
- Filament v5 code must remain v5-only.
- Panel provider registration remains in `apps/platform/bootstrap/providers.php`; no new panel provider is planned.
- EvidenceSnapshotResource global search is disabled and remains disabled.
- ProviderConnectionResource is treated as sensitive/provider-scoped and should not have global search enabled by this spec.
- Required Permissions and System pages are Filament pages, not globally searchable resources.
- No destructive product action is added or changed. Existing dangerous actions remain governed by current confirmation/authorization/audit rules.
- No Filament assets are added. `filament:assets` is not newly required by this spec unless later implementation registers assets, which is out of scope.

## Livewire Implications

- Browser tests may exercise Livewire-rendered Filament pages.
- No Livewire component behavior should be changed.
- If a fixture route is added, it must prepare session/auth state before the Livewire page renders.

## OperationRun / Monitoring Implications

- The spec does not create, update, or transition `OperationRun`.
- System Operations may display existing OperationRun data or an empty state only.
- No OperationRun notification, lifecycle, summary count, queue, or start UX behavior changes are allowed.

## RBAC / Policy Implications

- Admin surfaces must keep workspace/environment membership and capability checks.
- Non-members remain deny-as-not-found.
- Members missing capability remain forbidden where existing policy semantics require 403.
- System panel uses `platform` guard and `PlatformUser` capabilities.
- Any fixture route must have tests proving it is unavailable outside `local` and `testing`.
- Any fixture route must validate redirects and reject arbitrary external destinations.

## Audit / Logging / Evidence Implications

- Fixture routes must not log secrets, tokens, raw credential payloads, or raw Graph payloads.
- System panel normal login auditing remains existing behavior; a local/testing fixture route or Artisan fixture command must document whether it writes audit logs or why it intentionally does not.
- Browser reports and screenshots are spec-local audit evidence, not product evidence.

## Data / Migration Implications

- No migrations.
- No production data.
- No backfills.
- Fixture data may be created through factories, seed commands, or existing local/testing fixture commands.

## Test Strategy

- Feature tests:
  - admin smoke-login still sets workspace/environment context and debugbar suppression.
  - any new system smoke fixture authenticates only platform users, requires capabilities, validates redirects, and returns 404 outside local/testing.
  - any new or extended Artisan fixture command fails closed outside local/testing.
  - Evidence/Required Permissions/Provider fixture resolvers select only scoped records.
  - Provider Connection Detail fixture URLs carry explicit `environment_id` or record-derived managed-environment authority and do not rely on stale remembered environment state.
- Browser tests:
  - one bounded Spec 376 browser smoke covering the five target surfaces.
  - use `assertNoJavaScriptErrors()` and `assertNoConsoleLogs()` for reachable pages.
  - create screenshots or blocked evidence.
- Validation:
  - `git diff --check`
  - Pint dirty only if PHP files change
  - targeted Feature tests and browser command

## Rollout Considerations

- Local development and testing use Sail-first commands.
- Staging/production should see no fixture route availability if implementation is correct.
- No environment variables are required unless implementation reuses an existing fixture config pattern; any new env/config must default safe and be documented.
- No queue, scheduler, storage volume, or Dokploy runtime change is expected.

## Risk Controls

- **Auth fixture weakens security**: environment guard, route tests, platform/admin guard separation, redirect allowlist.
- **Fixture data brittle**: stable factory/config identifiers; no raw hardcoded local IDs without resolver.
- **Scope creep into UI fixes**: reports only; follow-up candidates for productization.
- **System panel auth separation**: use `PlatformUser` and `platform` guard only.
- **Timeouts persist**: classify `timeout-blocked`, document final URL/console state, and avoid speculative UI fixes.

## Implementation Phases

1. Preparation/source audit artifacts.
2. Fixture design and matrix.
3. Tests-first for fixture safety.
4. Minimal local/testing fixture implementation if needed.
5. Browser smoke and screenshots.
6. Reports, validation, and follow-up recommendations.

## Constitution Check

- **Inventory-first / snapshots-second**: no snapshot semantics change; only evidence fixture reachability.
- **Read/write separation**: no production write flow; fixture setup only local/testing.
- **Single Graph contract path**: no Graph calls are added.
- **Workspace/Tenant isolation**: central concern; must be proven in fixture tests.
- **RBAC/server truth**: fixture routes cannot become security boundary bypasses.
- **OperationRun truth**: unchanged.
- **UI-COV-001**: local/testing route impact is classified; existing product pages are audited only.
- **TEST-GOV-001**: browser and fixture test cost is explicit and opt-in.
- **BLOAT-001**: proportionality review exists because fixture support may add narrow support code.