TenantAtlas/specs/407-full-browser-ux-runtime-audit/plan.md

# Implementation Plan: Spec 407 - Full Browser/UX Runtime Audit

**Branch**: `407-full-browser-ux-runtime-audit` | **Date**: 2026-06-24 | **Spec**: `specs/407-full-browser-ux-runtime-audit/spec.md`
**Input**: Feature specification from `specs/407-full-browser-ux-runtime-audit/spec.md`

## Summary

Prepare a read-only browser/runtime audit gate after Specs 400-406. The future audit execution must navigate existing TenantPilot admin, system, customer, evidence, restore, backup, provider, report, and lifecycle surfaces through the browser, record runtime/console/UX/authorization/customer-safe findings, and return `PASS`, `PASS WITH CONDITIONS`, or `FAIL` with a grouped remediation plan. It must not implement fixes or create tests.

## 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, Laravel Sail
**Storage**: PostgreSQL and private `exports` disk are inspected only; no schema/storage changes
**Testing / Audit Evidence**: Browser read-only walkthrough, existing Pest/browser proof where useful, read-only route/log/schema/code inspection
**Validation Lanes**: Browser/read-only audit; no new tests or lanes
**Target Platform**: Local/Sail development environment unless the operator explicitly provides staging access
**Project Type**: Laravel monolith in `apps/platform` plus separate website app not in scope unless visible TenantPilot product links require it
**Performance Goals**: N/A for load; record only visible runtime symptoms such as slow/broken pages, failed network calls, or excessive polling symptoms
**Constraints**: Read-only only; no application code, tests, migrations, seeders, factories, routes, policies, config, docs outside this spec package, completed spec rewrites, or intentional data changes
**Scale/Scope**: Whole existing application surface where actors/fixtures permit; omissions must be recorded

## Repository Surfaces Likely Inspected

Governance and standards:

```text
AGENTS.md
.specify/
docs/ai-coding-rules.md
docs/architecture-guidelines.md
docs/filament-guidelines.md
docs/security-guidelines.md
docs/testing-guidelines.md
docs/performance-guidelines.md
docs/product/roadmap.md
docs/product/spec-candidates.md
docs/product/standards/product-surface-contract.md
docs/ui-ux-enterprise-audit/
```

Spec lineage:

```text
specs/400-product-contract-spec-completeness-audit/
specs/401-high-risk-admin-action-proof-pack/
specs/402-resource-policy-authorization-proof-matrix/
specs/403-evidence-anchor-currentness-runtime-closure/
specs/404-management-report-pdf-staging-validation/
specs/405-json-to-jsonb-data-layer-hardening/
specs/406-governance-artifact-lifecycle-retention/
```

Application surfaces for read-only inspection:

```text
apps/platform/routes/
apps/platform/bootstrap/providers.php
apps/platform/app/Providers/
apps/platform/app/Filament/
apps/platform/app/Livewire/
apps/platform/resources/views/
apps/platform/app/Http/Controllers/
apps/platform/app/Models/
apps/platform/app/Policies/
apps/platform/app/Services/
apps/platform/app/Jobs/
apps/platform/app/Support/
apps/platform/config/
apps/platform/tests/
```

## Audit Method

1. Record branch, HEAD, dirty state, tracked/untracked files, and `git diff --check`.
2. Confirm output mode: response-only final report by default; spec-local saved report only if explicitly requested by the operator during execution.
3. Build route/surface inventory from routes, Filament panels/resources/pages/widgets, Livewire/Blade views, navigation, customer/report/download routes, and system/admin routes.
4. Identify available actors and fixtures from existing repo/environment sources: workspace admin, limited workspace user, system operator, customer reviewer, unauthorized user, and cross-workspace user. Record the actor/session source without exposing secrets; record missing sources as limitations.
5. Start the local browser target through existing dev/Sail setup if needed and safe. Use existing helpers/fixtures only; ordinary browser login/session state may be used and recorded, but no new session harness or fixture setup is introduced.
6. Walk required surfaces and record page purpose, actor, route, state, console/runtime/network result, UX issue, authorization issue, customer-safe issue, severity, and follow-up. Avoid load/performance testing and repeated polling beyond what is needed to observe visible state.
7. Execute critical journeys: admin readiness, provider readiness, baseline drift, evidence/proof, backup readiness, restore readiness, finding/governance triage, review pack/customer review, report/PDF, system operator, and unauthorized/cross-workspace blocked access.
8. Inspect high-impact/destructive actions only up to visibility, disabled state, confirmation, labeling, and direct authorization behavior. Do not complete irreversible actions.
9. Produce findings with severity/category/evidence and group remediation into the fewest coherent follow-ups.
10. Record final dirty state and confirm no implementation occurred.

## Output Strategy

- **Default**: final audit report in the assistant response only.
- **Optional**: a spec-local audit report under `specs/407-full-browser-ux-runtime-audit/` only when the operator explicitly asks for saved output during audit execution.
- **Forbidden by default**: generated docs outside this package, screenshots committed to docs, new fixtures, new browser tests, application files, completed-spec edits, or runtime changes.

## UI / Surface Guardrail Plan

- **Guardrail scope**: read-only audit of existing rendered surfaces.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: none changed; many inspected.
- **No-impact class**: audit-only; no rendered UI surface change.
- **Native vs custom classification summary**: N/A for changes; audit classifies existing surfaces where evidence supports it.
- **Shared-family relevance**: navigation, status/readiness, dashboards, inboxes, restore/backup action affordances, provider readiness, evidence/report viewers, OperationRun proof, customer output, downloads, and lifecycle states are audit targets only.
- **State layers in scope**: shell, page, detail, URL-query, session/context, and download route behavior are inspected but not changed.
- **Audience modes in scope**: customer/read-only, operator/MSP, support/platform, system admin, unauthorized/cross-workspace.
- **Decision/diagnostic/raw hierarchy plan**: inspect whether default visible content supports the first decision and demotes technical detail.
- **Raw/support gating plan**: inspect customer-safe defaults and capability-gated raw/support detail where available.
- **One-primary-action / duplicate-truth control**: inspect whether pages have one dominant next action and avoid repeated readiness/status truth.
- **Handling modes by drift class or surface**: report-only; structural P0/P1 gaps become follow-up-spec recommendations.
- **Repository-signal treatment**: report-only unless the audit discovers a blocker requiring immediate stop.
- **Special surface test profiles**: browser/read-only coverage; no new test profile created.
- **Required tests or manual smoke**: browser audit evidence and existing proof references; no new tests.
- **Exception path and spread control**: Product Surface exceptions discovered become findings, not runtime exceptions.
- **Active feature PR close-out entry**: final report includes Product Surface and no-implementation close-out fields.
- **UI/Productization coverage decision**: No UI surface impact.
- **Coverage artifacts to update**: none during preparation or audit unless the operator explicitly requests a saved audit artifact; findings may recommend later updates.
- **Screenshot/page-report need**: screenshots are optional audit evidence only; do not commit them unless explicitly requested.

## Product Surface Contract Plan

- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`.
- **No-legacy posture**: no compatibility changes; completed specs remain historical context.
- **Page archetype and budget plan**: classify inspected pages where possible and flag budget violations.
- **Technical Annex and deep-link demotion plan**: inspect whether OperationRun/raw evidence/IDs/source keys/payloads/logs are demoted from product defaults.
- **Canonical status vocabulary plan**: inspect visible readiness/state labels against canonical vocabulary and record exceptions.
- **Product Surface exceptions**: none in preparation; observed runtime exceptions become audit findings.
- **Browser verification plan**: required as the audit output.
- **Human Product Sanity plan**: final report sanity.
- **Visible complexity outcome target**: neutral runtime; report may recommend reduction.
- **Implementation report target**: final audit report response; optional spec-local saved report only on explicit request.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: Livewire 4.1.4 confirmed by Laravel Boost; no Livewire code change.
- **Panel provider registration location**: Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`; no provider registration change.
- **Global search posture**: no globally searchable resource is changed. The audit inspects rendered/global-search behavior and resource posture where relevant.
- **Destructive/high-impact action posture**: no action is added or changed. The audit inspects existing action confirmation/disabled/direct authorization behavior without completing destructive actions.
- **Asset strategy**: no assets, no `FilamentAsset::register()`, no new `filament:assets` deployment requirement.
- **Testing plan**: no tests are added or changed. Existing tests may be referenced as evidence.
- **Deployment impact**: none from this spec. The audit may record external staging/Dokploy proof gaps but does not change env vars, migrations, queues, scheduler, storage, reverse proxy, SSL, assets, or worker config.

## Domain / Model / Data Implications

No model, migration, enum, table, persisted artifact, service, job, policy, route, query, Graph contract, OperationRun type, audit event, or customer-output artifact is introduced or changed.

The audit may read models, policies, migrations, services, jobs, and tests to understand source-of-truth, ownership, scope, and expected behavior. Reading does not create domain truth.

Truth dimensions to keep separate in the report:

- execution truth: `OperationRun` status/outcome and runtime errors
- artifact truth: review packs, stored reports, evidence snapshots, generated PDFs/downloads
- backup/snapshot truth: immutable backup/snapshot state versus live provider state
- recovery/evidence truth: restore/backup proof and currentness boundaries
- operator next action: what the current actor can safely do next

## RBAC / Security / Audit Implications

- No authorization behavior changes.
- Audit representative admin/system/customer/workspace/environment boundaries.
- Treat UI visibility as non-security; if direct action/route behavior cannot be checked, mark proof missing.
- Non-member/wrong workspace/wrong environment should deny as not found where repo contracts require it.
- Members lacking capability should be denied or visibly disabled according to existing capability UX.
- Customer/read-only surfaces must not expose raw evidence, raw payloads, OperationRun internals, raw IDs, source keys, fingerprints, private URLs, system/admin links, or stack traces by default.
- Do not include secrets, tokens, raw credential payloads, sensitive provider payloads, customer data, private signed URLs, or stack traces in the report.

## OperationRun / Observability Implications

- No `OperationRun` is created by this spec.
- Existing OperationRun list/detail/proof links are audit targets.
- The audit must distinguish operation execution truth from artifact/currentness truth.
- The audit must flag default-visible OperationRun links or raw IDs on customer/product surfaces where the Product Surface Contract expects demotion.

## Test Strategy

- No new tests.
- Use existing tests/browser proof only as supporting evidence.
- Browser walkthrough is the primary validation lane.
- Suggested read-only commands:

```bash
git status --short --branch
git diff --name-only
git diff --check
cd apps/platform && ./vendor/bin/sail artisan route:list
rg "PanelProvider|Filament|Resource|Page|RelationManager|Navigation|globalSearch|canAccess|canView|canCreate|canEdit|canDelete" apps/platform/app apps/platform/resources apps/platform/routes apps/platform/tests
rg "Baseline|Restore|Backup|Provider|Evidence|OperationRun|Finding|Governance|ReviewPack|Report|Receipt|PDF|Artifact|Lifecycle|Customer" apps/platform/app apps/platform/resources apps/platform/routes apps/platform/tests specs docs
```

Do not run destructive commands, reset, clean, migrate, seed, create fixtures, create actor/session harnesses, or perform load/performance testing.

## Rollout / Deployment Considerations

No rollout or deployment change.

The final report must still answer:

- environment/base URL used
- actors used or unavailable
- local/Sail/staging status
- external renderer/provider/Dokploy conditions if observed or unavailable
- whether any recommendation affects env vars, migrations, queues, scheduler, storage, assets, or Dokploy in a later spec

## Risk Controls

- Stop if the working tree becomes unexpectedly dirty outside allowed audit artifacts.
- Stop before creating fixtures, users, test files, screenshots in tracked docs, or saved reports unless the operator approves.
- Stop before executing destructive or irreversible actions.
- Classify missing data carefully: missing fixture only, product empty-state issue, runtime defect, or product decision gap.
- Do not infer production/staging readiness from local browser proof.
- Do not rewrite completed specs.

## Implementation Phases

### Phase 1 - Preparation And Safety

Read active spec package, governance files, standards, related specs, and record baseline branch/dirty state. Confirm read-only boundaries and output mode.

### Phase 2 - Route And Surface Inventory

Build admin/system/customer/shared route and surface inventory from repo truth. Identify reachable surfaces and unavailable fixture/service dependencies.

### Phase 3 - Browser Walkthrough

Navigate existing pages as available actors. Record route/page, actor, visible state, console/runtime/network result, UX issue, authorization issue, customer-safe issue, and severity.

### Phase 4 - Critical Journey Matrix

Walk required journeys and record completion, confidence, blocking issues, and follow-up.

### Phase 5 - Findings And Readiness Decision

Classify findings, build runtime error log, authorization/boundary results, evidence/currentness/proof results, governance artifact lifecycle results, UX/productization results, readiness decision, and remediation plan.

### Phase 6 - Close-Out

Record commands, final dirty state, no-implementation proof, Product Surface close-out fields, assumptions, limitations, and recommended next step.

## Stop Conditions

- Destructive action would need execution to prove a finding.
- Required actor/fixture creation is needed.
- Browser setup requires changing runtime config or seed data.
- A product decision is needed to decide intended behavior.
- External staging/Dokploy proof is needed but unavailable.
- Unexpected dirty files appear outside allowed spec-local output.
- A completed historical spec would need editing.

## Preparation Gate Results

- **Candidate Selection Gate**: PASS. The operator directly supplied Spec 407, no matching spec package existed, roadmap/spec-candidate truth supports manual promotion only, Specs 400-406 are read-only lineage, and the slice is bounded to read-only browser audit/reporting.
- **Spec Readiness Gate**: PASS. `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md` define a bounded read-only audit with clear requirements, browser method, matrices, findings taxonomy, readiness decision, stop conditions, and no open preparation blocker.