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:

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:

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:

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:

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.