From b3e6dfdb7c4148ae315e4b92d0e669c88b530866 Mon Sep 17 00:00:00 2001 From: Ahmed Darrazi Date: Wed, 24 Jun 2026 14:25:49 +0200 Subject: [PATCH] spec: add full browser UX runtime audit spec --- .../checklists/requirements.md | 91 +++++ .../407-full-browser-ux-runtime-audit/plan.md | 246 ++++++++++++ .../407-full-browser-ux-runtime-audit/spec.md | 377 ++++++++++++++++++ .../tasks.md | 153 +++++++ 4 files changed, 867 insertions(+) create mode 100644 specs/407-full-browser-ux-runtime-audit/checklists/requirements.md create mode 100644 specs/407-full-browser-ux-runtime-audit/plan.md create mode 100644 specs/407-full-browser-ux-runtime-audit/spec.md create mode 100644 specs/407-full-browser-ux-runtime-audit/tasks.md diff --git a/specs/407-full-browser-ux-runtime-audit/checklists/requirements.md b/specs/407-full-browser-ux-runtime-audit/checklists/requirements.md new file mode 100644 index 00000000..c0efbddc --- /dev/null +++ b/specs/407-full-browser-ux-runtime-audit/checklists/requirements.md @@ -0,0 +1,91 @@ +# Requirements Checklist: Spec 407 - Full Browser/UX Runtime Audit + +**Feature**: `specs/407-full-browser-ux-runtime-audit/` +**Review date**: 2026-06-24 +**Scope**: Preparation artifact quality only. No application implementation performed. + +## Candidate Selection Gate + +- [x] The selected candidate was directly provided by the operator as Spec 407. +- [x] `docs/product/spec-candidates.md` was reviewed and reports no safe automatic next-best-prep target. +- [x] The candidate aligns with the supplied after-Specs-400-406 browser/runtime gate. +- [x] The roadmap supports a broad readiness gate before pilot/customer-facing claims. +- [x] Specs 400-406 are treated as read-only lineage. +- [x] Spec 403 `PASS`, Spec 404/405 `PASS WITH CONDITIONS`, and Spec 406 `PASS WITH CONDITIONS` are carried forward honestly. +- [x] No existing `specs/407-full-browser-ux-runtime-audit/` package existed before preparation. +- [x] Existing branch `407-msp-mittelstand-use-case-pages` is recorded as unrelated. +- [x] The smallest slice is a read-only browser/runtime audit and final readiness report. +- [x] Close alternatives are deferred instead of hidden inside this package. +- [x] Candidate Selection Gate result: PASS as a direct operator-promoted follow-through candidate. + +## Spec Completeness + +- [x] Problem statement is clear and product-oriented. +- [x] Business/product value is explicit. +- [x] Primary users/operators are named. +- [x] Scope fields cover routes/surfaces, ownership, RBAC, and leakage checks. +- [x] Functional requirements are testable. +- [x] Non-functional requirements cover security, reliability, auditability, performance, product safety, and test governance. +- [x] User stories include independent tests and acceptance criteria. +- [x] Edge cases are documented. +- [x] Out-of-scope boundaries forbid fixes, runtime changes, tests, fixtures, destructive actions, saved docs by default, and completed-spec rewrites. +- [x] Success criteria are measurable. +- [x] Assumptions, risks, and open questions are explicit. + +## Constitution And Proportionality + +- [x] Spec Candidate Check is filled out. +- [x] Approval class is exactly one class: Core Enterprise. +- [x] Score is recorded and above the minimum threshold. +- [x] Proportionality Review is completed. +- [x] The report/matrix/severity outputs are explicitly report-only and not runtime truth. +- [x] No persisted entity, table, enum, status family, abstraction, UI framework, or product taxonomy is approved. +- [x] The spec requires stopping before implementation or product-decision invention. +- [x] Completed historical specs are preserved as read-only context. + +## Product Surface Contract + +- [x] `docs/product/standards/product-surface-contract.md` is referenced. +- [x] No-legacy posture is recorded. +- [x] UI Surface Impact is `No UI surface impact` with rationale. +- [x] Product Surface Impact is completed as audit-only. +- [x] Page archetypes, surface budgets, deep-link demotion, and canonical vocabulary are audit criteria. +- [x] Browser proof is required as the audit output. +- [x] Human Product Sanity is required for the final report. +- [x] Product Surface exceptions are `none` for preparation. +- [x] Final report close-out fields are required. + +## Plan Completeness + +- [x] Plan identifies PHP/Laravel/Filament/Livewire/Pest/PostgreSQL/Sail context. +- [x] Plan names existing runtime surfaces likely inspected. +- [x] Plan distinguishes read-only browser audit from runtime implementation. +- [x] Plan includes UI/Product Surface, Filament/Livewire/deployment, RBAC, audit, evidence/currentness, OperationRun, lifecycle, and test-governance posture. +- [x] Plan defines audit method, output strategy, stop conditions, phases, and risk controls. +- [x] Plan carries Spec 404/405 and Spec 406 conditions forward. +- [x] Plan does not contradict repository architecture or current code truth. + +## Task Completeness + +- [x] Tasks are ordered by safety, inventory, browser walkthrough, journey matrix, findings, summaries, readiness decision, and close-out. +- [x] Tasks are small and verifiable. +- [x] Tasks include dirty-state checks before/after. +- [x] Tasks include actor/fixture availability checks. +- [x] Tasks include required surface and journey coverage. +- [x] Tasks include severity/category finding classification. +- [x] Tasks include Product Surface and Filament output-contract close-out fields. +- [x] Tasks include explicit non-goals preventing implementation and mutation. +- [x] Tasks include final validation commands and no-implementation proof. + +## Open Questions And Readiness + +- [x] No open question blocks starting the audit; unavailable actors, fixtures, services, or routes are recorded as limitations. +- [x] Saved audit artifact policy is explicit: response-only by default, spec-local file only by operator request. +- [x] Spec Readiness Gate result: PASS for implementation preparation. + +## Review Outcome + +- [x] Review outcome class: `acceptable-special-case` for a broad but read-only customer-readiness browser audit gate. +- [x] Workflow outcome: `keep`. +- [x] Final note location: future Spec 407 final audit report. +- [x] No application implementation was performed during preparation. diff --git a/specs/407-full-browser-ux-runtime-audit/plan.md b/specs/407-full-browser-ux-runtime-audit/plan.md new file mode 100644 index 00000000..d29b7a93 --- /dev/null +++ b/specs/407-full-browser-ux-runtime-audit/plan.md @@ -0,0 +1,246 @@ +# 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. diff --git a/specs/407-full-browser-ux-runtime-audit/spec.md b/specs/407-full-browser-ux-runtime-audit/spec.md new file mode 100644 index 00000000..d12a93b5 --- /dev/null +++ b/specs/407-full-browser-ux-runtime-audit/spec.md @@ -0,0 +1,377 @@ +# Feature Specification: Spec 407 - Full Browser/UX Runtime Audit + +**Feature Branch**: `407-full-browser-ux-runtime-audit` +**Created**: 2026-06-24 +**Status**: Draft / Ready for implementation preparation review +**Type**: Read-only browser audit / UX runtime audit / customer-readiness gate +**Input**: User-provided "Spec 407 - Full Browser/UX Runtime Audit" draft from `/Users/ahmeddarrazi/.codex/attachments/7a246551-6eb9-4829-b6bf-e527f805f39e/pasted-text.txt`, Specs 400-406 lineage, `docs/product/spec-candidates.md`, `docs/product/roadmap.md`, and the Product Surface Contract. + +## Candidate Selection Context + +- **Selected candidate**: Spec 407 - Full Browser/UX Runtime Audit. +- **Source location**: Direct user-provided Spec 407 draft in the current request. +- **Why selected**: `docs/product/spec-candidates.md` states that no safe automatic next-best-prep target remains, but the operator supplied a concrete manual candidate. Spec 407 is the direct broad browser/runtime gate after Specs 400-406 and answers whether TenantPilot behaves coherently enough for controlled pilot, customer-facing hardening, or targeted remediation. +- **Why close alternatives were deferred**: + - `management-report-pdf-staging-runtime-validation` is already represented by Specs 404 and 380; remaining external Dokploy/staging proof is a condition to carry into the audit, not a new prep target here. + - `governance-artifact-lifecycle-retention-runtime` is now Spec 406 and is completed as `PASS WITH CONDITIONS`; its residual product decisions are audit context, not hidden Spec 407 implementation scope. + - `provider-readiness-onboarding-productization`, `cross-domain-indicator-runtime-follow-through`, `manual-system-panel-browser-fixture-or-audit-procedure`, and `first-governed-ai-runtime-consumer` remain manual-promotion items and are not the supplied after-406 gate. + - Reopening completed Specs 400-406 is forbidden; their close-out, validation, browser evidence, smoke history, and task markers are historical context only. +- **Roadmap relationship**: Supports the current productization and moat priorities by turning the recent trust/productization hardening block into a decision-quality readiness answer before pilot or customer-facing claims advance. +- **Completed-spec guardrail result**: + - Specs 400-406 exist and are read-only lineage. Specs 401-406 contain implementation reports, validation results, browser/smoke evidence, or completed task markers; none may be rewritten, normalized, unchecked, or stripped. + - Spec 403 is `PASS` for evidence/currentness closure in its touched scope. + - Specs 404 and 405 are `PASS WITH CONDITIONS` because external staging/Dokploy validation remains unavailable. + - Spec 406 is `PASS WITH CONDITIONS` because legal hold, export-before-delete, broad purge, cross-family deletion governance, and Spec 404/405 external conditions remain product/release decisions. + - No `specs/407-full-browser-ux-runtime-audit/` package existed before this preparation. An unrelated branch named `407-msp-mittelstand-use-case-pages` exists but has no matching Spec 407 audit package. +- **Smallest viable implementation slice**: Execute a read-only browser/runtime audit of existing TenantPilot surfaces, using available fixtures and actors only; produce a decision-quality report with coverage matrix, journey matrix, classified findings, readiness decision, and grouped remediation plan. Do not fix issues, create tests, alter data intentionally, or create a saved report unless the operator explicitly asks during execution. +- **Feature description for Spec Kit**: Audit TenantPilot end-to-end through the browser after Specs 400-406 to determine whether the application is ready for controlled pilot, customer-facing hardening, sales/demo use, production deployment claims, or targeted remediation, while preserving a strict read-only boundary. + +## Spec Candidate Check *(mandatory - SPEC-GATE-001)* + +- **Problem**: TenantPilot has completed a trust/productization hardening block, but no current whole-app browser/runtime audit proves that admin, system, customer, evidence, restore, backup, report, and lifecycle surfaces behave coherently together. +- **Today's failure**: The product could appear specification-complete while still hiding runtime errors, misleading readiness/currentness claims, unsafe action presentation, broken downloads, navigation ambiguity, or customer/internal boundary issues that only emerge in browser use. +- **User-visible improvement**: The operator gets one evidence-backed readiness answer: `PASS`, `PASS WITH CONDITIONS`, or `FAIL`, plus a prioritized remediation plan grouped into the fewest coherent follow-up specs. +- **Smallest enterprise-capable version**: A read-only browser audit using available actors and fixtures, plus route/surface inventory, critical journey walkthroughs, runtime/console checks, authorization boundary checks, evidence/currentness checks, lifecycle/download checks, coverage matrix, journey matrix, findings, and readiness decision. +- **Explicit non-goals**: No fixes, refactors, UI redesign, copy cleanup, tests, migrations, seeders, fixtures, new surfaces, docs outside this package, route changes, policy changes, database writes beyond unavoidable login/session state, destructive actions, customer-output release, or speculative product decisions. +- **Permanent complexity imported**: One Spec Kit package and a future audit report. Severity labels, matrices, and readiness decisions are report-only audit outputs, not runtime truth, persisted state, status families, or product frameworks. +- **Why now**: Spec 406 explicitly recommends a full browser/UX runtime audit after its gate. Specs 400-406 closed or bounded adjacent trust risks, so the next responsible step is broad runtime evidence before pilot/customer claims. +- **Why not local**: A local smoke test or one-page check cannot answer whether cross-surface navigation, authorization, customer-safe output, evidence truth, report/download behavior, and lifecycle claims hold together end-to-end. +- **Approval class**: Core Enterprise. +- **Red flags triggered**: Broad surface coverage and audit matrix. Defense: the slice is read-only, report-only, forbids application/runtime changes, and groups findings instead of creating one spec per issue. +- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 12/12** +- **Decision**: approve as a bounded read-only browser/runtime readiness gate. + +## Problem Statement + +Spec 407 answers: + +```text +After Specs 400-406, is TenantPilot ready to proceed toward controlled pilot, customer-facing hardening, sales/demo use, production deployment claims, or targeted remediation? +``` + +The answer must be based on browser/runtime evidence, not assumptions. The audit inspects visible product quality, runtime stability, UX consistency, authorization boundaries, workflow clarity, evidence/currentness truth, report/download behavior, and governance artifact lifecycle behavior. + +## Product / Business Value + +- Prevents false readiness confidence after several successful but bounded hardening specs. +- Identifies customer/pilot blockers before external users encounter them. +- Distinguishes runtime defects, productization defects, proof gaps, product decision gaps, and already-known deferred items. +- Produces a small remediation map instead of one issue/spec per observation. +- Gives the next implementation block a concrete go/no-go signal. + +## Primary Users / Operators + +- Product owner deciding whether controlled pilot or customer-facing hardening may proceed. +- Workspace admins and limited users whose workflows depend on clear workspace/environment, provider, backup, restore, evidence, report, and governance states. +- System operators validating `/system` separation and operational clarity. +- Customer reviewers consuming released review/report outputs. +- Engineering reviewers and implementation agents using the audit report to scope the next remediation loop. + +## Spec Scope Fields *(mandatory)* + +- **Scope**: canonical-view / read-only browser audit / customer-readiness gate. +- **Primary Routes / Surfaces**: Existing `/admin`, `/system`, customer/review/report/download surfaces, and visible routes discovered from route list, Filament panels/resources/pages/widgets, Livewire/Blade views, and navigation. No route is added or changed. +- **Data Ownership**: No ownership changes. The audit classifies existing workspace-owned, managed-environment-owned, customer-output, OperationRun, evidence, report, audit, and platform-owned records only as observed/read. +- **RBAC**: No authorization behavior changes. The audit checks workspace membership, managed-environment entitlement, platform-plane separation, customer-reviewer boundaries, direct URL behavior, global search/navigation exposure, 404 vs 403 semantics, and destructive/high-impact action affordances. + +For canonical or mixed-scope surfaces: + +- **Default filter behavior when environment context is active**: Existing route-owned workspace/environment scope and explicit `environment_id` filters remain repo truth. The audit must flag any hidden context drift or stale context behavior it observes. +- **Explicit entitlement checks preventing cross-tenant leakage**: Representative direct URL, navigation, global search, download/export, and customer-review access checks must be performed where fixtures permit. Missing fixtures are recorded as missing audit conditions, not invented proof. + +## No Legacy / No Backward Compatibility Constraint *(mandatory)* + +TenantPilot is pre-production for this audit. + +- **Compatibility posture**: read-only assessment of current canonical behavior. +- **Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?**: no new compatibility behavior is introduced. +- **Why clean assessment is safe now**: The audit does not mutate runtime behavior. It may recommend clean follow-up remediation, but it must not implement compatibility shims or rewrite completed specs. + +## UI Surface Impact *(mandatory - UI-COV-001)* + +Does this spec add, remove, rename, or materially change any reachable UI surface? + +- [x] No UI surface impact +- [ ] Existing page changed +- [ ] New page/route added +- [ ] Navigation changed +- [ ] Filament panel/provider surface changed +- [ ] New modal/drawer/wizard/action added +- [ ] New table/form/state added +- [ ] Customer-facing surface changed +- [ ] Dangerous action changed +- [ ] Status/evidence/review presentation changed +- [ ] Workspace/environment context presentation changed + +## UI/Productization Coverage + +N/A - no reachable UI surface impact. + +- **No-impact rationale**: Spec 407 prepares and later executes a read-only browser/runtime audit. It may navigate existing UI, inspect routes, read browser console/network state, and record findings, but it must not change rendered pages, navigation, Filament panels/resources/pages/widgets, Livewire components, Blade views, CSS, JavaScript, actions, tables, forms, routes, tests, or customer-facing output. + +## Product Surface Impact + +Reference: `docs/product/standards/product-surface-contract.md`. + +- **Product Surface Contract applies?**: yes as the audit standard; no rendered product surface is changed. +- **Page archetype**: N/A for this spec package. The audit must classify inspected pages as Dashboard, Receipt, Decision, Inbox, Wizard, Report, Search/Index, Technical Annex, Settings, or System Admin where evidence supports it. +- **Primary user question**: "Does TenantPilot behave like a coherent, customer-ready enterprise SaaS when used end-to-end in the browser?" +- **Primary action**: Produce a readiness decision and bounded remediation recommendation. +- **Surface budget result**: N/A for preparation. The audit flags budget/deep-link/default-detail violations as findings. +- **Technical Annex / deep-link demotion**: The audit checks whether OperationRun links, raw evidence IDs, payloads, source keys, detectors, fingerprints, technical logs, and internal proof stay demoted from customer/product defaults. +- **Canonical status vocabulary**: The audit checks visible states against Ready, Needs attention, Blocked, Running, Failed, Expired, Not configured, Unknown, Historical, Superseded, and severity labels Critical, High, Medium, Low, Info. +- **Visible complexity impact**: neutral at runtime. The future report may recommend reductions, but must not perform them. +- **Product Surface exceptions**: none for preparation. Observed exceptions become findings or follow-up recommendations. + +## Browser Verification Plan *(mandatory)* + +- **Browser proof required?**: yes for Spec 407 execution because browser/runtime evidence is the product of this audit, even though no rendered UI changes are made. +- **No-browser rationale**: N/A. +- **Focused path when required**: full existing application surface as available, including login/auth, admin shell, system shell, workspace/environment context, dashboard/readiness, baseline compare, restore readiness, backup flows, provider readiness, evidence, OperationRun proof, findings/governance inbox, review packs, customer review workspace, report/PDF downloads, governance artifact lifecycle states, users/membership/access-scope surfaces if present, navigation, breadcrumbs, tables, filters, search, and global search. +- **Primary interaction to execute**: read-only navigation, filtering, searching, opening details, inspecting disabled/confirmation states without completing destructive actions, and attempting representative unauthorized/cross-workspace access where safe. +- **Console, Livewire, Filament, network, and 500-error checks**: required. +- **Full-suite failure triage**: unrelated failures may be documented only when focused browser evidence supports the classification. + +## Human Product Sanity Check *(mandatory)* + +- **Required?**: yes as final audit report sanity. +- **No-human-sanity rationale**: N/A. +- **Reviewer questions**: Does the audit answer pilot/customer readiness? Are P0/P1 findings concrete? Are critical journeys covered or clearly blocked? Are technical details/customer boundaries evaluated? Are recommendations bounded and non-speculative? +- **Planned result location**: final Spec 407 audit report in the assistant response, or spec-local report only if the operator explicitly requests saved output during audit execution. + +## Product Surface Merge Gate Checklist *(mandatory)* + +- [x] No-legacy posture or approved exception recorded. +- [x] Product Surface Impact is completed as audit-only with no rendered surface change. +- [x] Browser proof is required as the audit output. +- [x] Human Product Sanity is planned as final-report sanity. +- [x] Product Surface exceptions are `none` for preparation. +- [x] Final report must state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, and explicit no-implementation status. + +## Cross-Cutting / Shared Pattern Reuse + +- **Cross-cutting feature?**: yes, as a read-only audit across visible product surfaces and shared interaction families. +- **Interaction class(es)**: navigation, global search, status/readiness messaging, dashboards, inboxes, reports/downloads, evidence/report viewers, OperationRun proof, restore/backup actions, provider readiness, customer output, and destructive/high-impact action affordances are inspected only. +- **Systems touched**: Spec artifacts only. Runtime systems are read-only targets. +- **Existing pattern(s) to extend**: Product Surface Contract, UI audit route inventory/design coverage/page reports, Filament v5 guidelines, OperationRun UX contract, RBAC/UiEnforcement conventions, customer-output gates, and existing browser harnesses. +- **Shared contract / presenter / builder / renderer to reuse**: N/A - no runtime code. +- **Why the existing shared path is sufficient or insufficient**: Existing contracts define the evaluation lens. The audit determines whether rendered behavior follows them. +- **Allowed deviation and why**: none. +- **Consistency impact**: Findings must use stable severity, category, route, actor, evidence, and remediation-group language. +- **Review focus**: Confirm the audit remains read-only and does not silently become implementation, fixture creation, product design, or broad refactoring. + +## OperationRun UX Impact + +- **Touches OperationRun start/completion/link UX?**: no runtime change. OperationRun surfaces and proof links are audited only. +- **Shared OperationRun UX contract/layer reused**: N/A. +- **Delegated start/completion UX behaviors**: N/A. +- **Local surface-owned behavior that remains**: N/A. +- **Queued DB-notification policy**: N/A. +- **Terminal notification path**: N/A. +- **Exception required?**: none. + +## Provider Boundary / Platform Core Check + +- **Shared provider/platform boundary touched?**: no runtime seam change. Provider readiness, provider-specific diagnostics, managed-environment context, and Microsoft/Graph terminology are inspected only. +- **Boundary classification**: audit target only. +- **Seams affected**: provider connection setup/readiness, required permissions, freshness, tenant/environment context, reports, evidence, and customer-safe output may be inspected. +- **Neutral platform terms preserved or introduced**: no new runtime terms; audit language uses workspace, managed environment, provider, connection, evidence, report, operation, artifact, and customer output. +- **Provider-specific semantics retained and why**: existing Microsoft/Intune semantics remain repo truth where provider-owned. +- **Why this does not deepen provider coupling accidentally**: no code, UI labels, persistence, routes, or vocabulary are changed. +- **Follow-up path**: provider-boundary issues become bounded findings or follow-up specs only if evidence-backed. + +## UI / Surface Guardrail Impact + +N/A - no operator-facing surface change. The audit inspects existing operator, customer, and system surfaces and reports findings only. + +## Decision-First Surface Role + +N/A - no surface changed. The audit classifies inspected surfaces by decision role where possible and flags ambiguity. + +## Audience-Aware Disclosure + +N/A - no disclosure changed. The audit inspects customer/read-only, operator diagnostic, and support/raw evidence layers. + +## UI/UX Surface Classification + +N/A - no surface changed. The audit may report classification gaps. + +## Operator Surface Contract + +N/A - no new or materially changed operator-facing page. The audit checks whether existing pages have clear operator purpose, primary question, next action, technical detail demotion, and audience boundaries. + +## Proportionality Review *(mandatory when structural complexity is introduced)* + +- **New source of truth?**: no runtime source of truth. The audit report is review evidence only. +- **New persisted entity/table/artifact?**: no application entity/table. A saved audit artifact is allowed only under the active spec directory if the operator explicitly requests it during execution. +- **New abstraction?**: no runtime abstraction. +- **New enum/state/reason family?**: no runtime status family. Severity and readiness labels are report-only. +- **New cross-domain UI framework/taxonomy?**: no runtime framework. Existing Product Surface and UI audit vocabulary is reused. +- **Current operator problem**: Pilot/customer readiness cannot be judged from bounded implementation reports alone. +- **Existing structure is insufficient because**: Specs 400-406 prove slices or conditions, but no current artifact records whole-app browser/runtime readiness after those changes. +- **Narrowest correct implementation**: route/surface inventory, read-only browser walkthrough, critical journey matrix, classified findings, readiness decision, and grouped remediation plan. +- **Ownership cost**: one audit execution and future review of its findings. No recurring runtime maintenance. +- **Alternative intentionally rejected**: immediate remediation or creating new specs before browser evidence exists. +- **Release truth**: current-release customer/pilot readiness gate. + +## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)* + +- **Test purpose / classification**: Browser audit / manual or automated browser evidence. No application test files are added or changed. +- **Validation lane(s)**: Browser/read-only audit plus read-only route/artisan/log inspection where safe. +- **Why this classification and these lanes are sufficient**: The spec does not change runtime behavior; the value is browser evidence and decision reporting. +- **New or expanded test families**: none in prep. If future execution needs fixture or test creation, stop and update the spec or ask the operator. +- **Fixture/helper/factory/seed/context cost**: none added. Existing fixtures/actors only. +- **Browser scope**: broad application walkthrough with documented omissions where actors, fixtures, or environment services are unavailable. +- **Deployment impact**: none from preparation or audit. The audit may record deployment/readiness conditions but does not change env vars, migrations, queues, scheduler, storage, assets, reverse proxy, or Dokploy config. + +## Functional Requirements + +- **FR-407-001**: The audit MUST be read-only and MUST NOT intentionally mutate application data, files, tests, code, schema, routes, config, docs outside this spec package, or completed specs. +- **FR-407-002**: The audit MUST record branch, HEAD, dirty state, changed tracked files, untracked files, and `git diff --check` before and after browser work. +- **FR-407-003**: The audit MUST inventory routes, Filament panels, resources, pages, widgets, Livewire components, navigation groups, customer/review routes, system/admin routes, and download/export routes sufficiently to explain coverage. +- **FR-407-004**: The audit MUST cover admin panel shell, system panel shell, workspace/environment context, dashboard/readiness, baseline compare, restore readiness, backups, provider readiness, evidence, OperationRun proof, findings/governance inbox, review packs/customer review workspace, reports/PDF downloads, governance artifact lifecycle, membership/access-scope surfaces if present, navigation, breadcrumbs, tables, filters, and search where reachable. +- **FR-407-005**: The audit MUST use available actor perspectives: workspace admin, limited workspace user, system operator, customer reviewer, unauthorized user, and cross-workspace user where fixtures permit. It MUST identify the existing source for each actor/session used without exposing secrets, and record missing actor sources as limitations. +- **FR-407-006**: If an actor, fixture, route, or service is unavailable, the audit MUST record it as `BLOCKED`, `NOT TESTED`, or `NOT APPLICABLE` with reason, not as proof. +- **FR-407-007**: The audit MUST NOT complete destructive or irreversible actions. It may inspect visibility, disabled state, confirmation presence, copy, authorization boundaries, and direct access behavior without execution. +- **FR-407-008**: The audit MUST record browser console errors, Livewire/Filament errors, HTTP 500/404/403 surprises, network failures, asset failures, modal/action failures, table/filter/search failures, PDF/download failures, and file-not-found symptoms. +- **FR-407-009**: P0/P1 findings MUST include surface, route/page, actor, observed behavior, expected contract, severity, why it matters, evidence reference, and recommended resolution type. +- **FR-407-010**: Findings MUST be classified by severity P0/P1/P2/P3 and by category: runtime defect, UX/productization defect, authorization defect, customer-safe boundary defect, evidence/currentness defect, lifecycle defect, navigation/IA defect, empty/error-state defect, copy/terminology defect, test/proof gap, product decision gap, known deferred item, or duplicate/already covered. +- **FR-407-011**: The audit MUST include a Browser Coverage Matrix with surface, actor, route/page, state tested, result, runtime errors, UX issues, authorization issues, customer-safe issues, severity, and follow-up. +- **FR-407-012**: The audit MUST include a Journey Matrix for admin readiness review, provider readiness review, baseline drift review, evidence/proof review, backup readiness review, restore readiness review, finding/governance triage, review pack/customer review, report/PDF review, system operator review, and unauthorized/cross-workspace blocked access. +- **FR-407-013**: The audit MUST include readiness decisions for controlled pilot, customer-facing hardening, sales/demo use, broader customer claims, production deployment, and next implementation block. +- **FR-407-014**: The audit MUST carry forward Spec 404/405 staging/Dokploy conditions and Spec 406 lifecycle/product-decision conditions honestly; it MUST NOT claim production/staging readiness unless browser/runtime evidence proves it. +- **FR-407-015**: The remediation plan MUST group findings into the fewest coherent follow-up specs or decisions. It MUST NOT create one spec per minor observation. +- **FR-407-016**: The audit MUST distinguish missing fixture/test-data conditions from product empty-state defects and runtime defects. +- **FR-407-017**: The audit MUST verify customer/read-only surfaces do not expose internal-only data, raw payloads, OperationRun internals, raw IDs, source keys, fingerprints, stack traces, private URLs, or system/admin links by default. +- **FR-407-018**: The audit MUST verify evidence/currentness/report/lifecycle claims are not over-stated when data is stale, expired, partial, failed, missing, deleted, or unavailable. +- **FR-407-019**: The audit MUST verify representative authorization boundaries for admin/system/customer planes, workspace isolation, environment isolation, direct URLs, navigation/global search, and download/export access where fixtures permit. +- **FR-407-020**: The audit MUST preserve completed historical specs and their implementation reports, validation results, task completion markers, smoke results, screenshots, and review language. + +## Non-Functional Requirements + +- **Security**: Do not record secrets, tokens, raw credential payloads, sensitive provider payloads, private signed URLs, customer data, or stack traces in the final report. +- **Reliability**: Audit conclusions must be evidence-backed and must distinguish observed failures from unavailable fixtures/services. +- **Performance**: Browser inspection must avoid load/performance testing and avoid repeated polling beyond what is needed to observe the visible state. +- **Auditability**: Every P0/P1 finding must be reproducible enough for the next implementation agent to locate the route/surface and expected contract. +- **Product Safety**: The audit must not decide missing product questions silently; it must mark them as product decision gaps. +- **Test Governance**: No new test lane, fixture family, browser harness, seed, factory, or session harness is added by this spec. Ordinary browser login/session state from the existing environment may be used and recorded. + +## User Stories And Independent Tests + +### User Story 1 - Product owner receives a readiness decision (Priority: P1) + +As the product owner, I need a browser-evidence-backed `PASS`, `PASS WITH CONDITIONS`, or `FAIL` result so I can decide whether to proceed to controlled pilot, customer-facing hardening, or remediation. + +**Independent Test**: The final report includes Candidate Gate Result, Browser Coverage Matrix, Journey Matrix, Findings, Readiness Decision, Remediation Plan, commands run, dirty state, and recommended next action. + +### User Story 2 - Operator workflows are walked end-to-end (Priority: P1) + +As a workspace operator, I need critical admin workflows inspected through the browser so hidden Livewire/Filament/runtime, navigation, state, or action-safety issues are visible before pilot. + +**Independent Test**: The Journey Matrix records completion/confidence for readiness, provider, baseline, evidence, backup, restore, finding/governance, review/report, and customer output journeys. + +### User Story 3 - Customer and boundary safety are verified (Priority: P1) + +As a customer reviewer or limited actor, I need customer-safe and unauthorized paths checked so the app does not leak internal data or cross-workspace/system/admin context. + +**Independent Test**: The audit records representative customer-review, unauthorized, cross-workspace, system/admin, navigation/global search, and download/export boundary results or explains missing fixture blockers. + +### User Story 4 - Findings become bounded remediation work (Priority: P2) + +As the next implementation agent, I need findings grouped by product risk and root cause so remediation can be implemented in small follow-up specs instead of a broad rewrite. + +**Independent Test**: The Remediation Plan groups P0/P1 and related P2 findings into coherent follow-ups and explicitly marks isolated minor issues, known deferred items, and duplicates that should not become specs. + +## Required Audit Report Structure + +The final report MUST include these sections: + +- A. Candidate Gate Result +- B. Scope and Environment +- C. Dirty State +- D. Executive Summary +- E. Browser Coverage Matrix +- F. Journey Matrix +- G. Findings +- H. Runtime Error Log +- I. Authorization / Boundary Results +- J. Evidence / Currentness / Proof Results +- K. Governance Artifact Lifecycle Results +- L. UX / Productization Results +- M. Readiness Decision +- N. Remediation Plan +- O. Validation / Audit Commands +- P. Recommended Next Step + +## Severity Rules + +- **P0 - Blocker**: unsafe, misleading, or unusable for pilot, including unauthorized restricted data access, customer-facing internal leakage, unsafe destructive execution, false currentness/evidence/customer-safe claims, cross-workspace exposure, download authorization bypass, critical page 500s, or deleted/missing artifact downloadable as valid proof. +- **P1 - High**: controlled pilot or customer-hardening should not proceed without resolution or explicit exclusion, including critical runtime errors, high-risk misleading state, broken critical journey, major navigation ambiguity, missing critical browser proof, or important proof link failures. +- **P2 - Medium**: productization issues to address before broader rollout, including inconsistent terminology, confusing lower-risk empty states, non-critical action placement, or internal-only proof links that are not harmful. +- **P3 - Low**: minor polish such as low-risk copy, spacing, or dev-only naming. + +## Acceptance Criteria + +- **AC-407-001**: Audit was read-only and no application implementation occurred. +- **AC-407-002**: Dirty state before/after is recorded. +- **AC-407-003**: Admin panel, system panel, customer/review path where available, workspace/environment context, provider, baseline, restore, backup, evidence, OperationRun, findings, governance, review pack, report/PDF, and artifact lifecycle surfaces are covered or explicitly marked unavailable. +- **AC-407-004**: At least one unauthorized/cross-workspace boundary path is audited where fixtures permit. +- **AC-407-005**: Runtime/console/Livewire/Filament errors are recorded. +- **AC-407-006**: Browser Coverage Matrix and Journey Matrix are included. +- **AC-407-007**: Findings are classified by severity and defect category. +- **AC-407-008**: Readiness Decision table is included. +- **AC-407-009**: Remediation Plan groups findings into the fewest coherent follow-ups. +- **AC-407-010**: The report clearly states whether TenantPilot can proceed to controlled pilot, customer-facing hardening, sales/demo use, broader customer claims, production deployment, and the next implementation block. + +## Success Criteria + +- **SC-407-001**: The operator can decide whether to proceed to pilot/customer hardening or remediation without asking the implementation agent to infer missing readiness facts. +- **SC-407-002**: No hidden P0/P1 customer-readiness risk remains unclassified in the audited coverage. +- **SC-407-003**: All limitations are explicit, including missing actors, missing fixtures, unavailable services, external staging/Dokploy gaps, and not-tested surfaces. +- **SC-407-004**: Follow-up work is grouped into a small, coherent remediation path. + +## Edge Cases + +- Actor accounts or fixtures are unavailable. +- A route exists but has no data. +- A page depends on external provider state or renderer services unavailable in local/dev. +- A destructive action can be inspected only up to confirmation. +- Browser environment cannot authenticate as a specific role. +- A page returns 404/403 intentionally for isolation. +- Existing Spec 404/405 external staging conditions cannot be resolved in local browser audit. +- Existing Spec 406 product-decision residuals appear as visible states. + +## Out Of Scope + +- Fixes, refactors, UI redesign, copywriting, tests, migrations, seeders, factories, routes, Filament resources, Livewire components, policies, commands, views, config, docs outside this spec package, lock files, generated assets, database schema, new fixtures, new pages, new customer outputs, new provider integrations, new report templates, governance lifecycle behavior changes, commercial lifecycle, billing, legal/compliance review, penetration testing, and load/performance testing beyond visible runtime symptoms. + +## Assumptions + +- The browser audit runs against a local/dev or explicitly approved non-production environment. +- Existing seed/demo/test actors and fixtures are sufficient for representative coverage, but gaps are recorded if not. +- Specs 404/405 external conditions and Spec 406 lifecycle residuals are audit inputs, not automatic blockers unless visible/runtime evidence makes them pilot blockers. +- Saved report output is response-only unless the operator explicitly asks for a spec-local audit artifact. + +## Risks + +- Missing fixtures could reduce actor or journey confidence. +- Browser auth/setup may block system or customer perspectives. +- Broad coverage could become noisy; P0/P1 findings must stay evidence-backed and P2/P3 observations must be grouped. +- External staging/Dokploy validation may remain unavailable and must not be converted into false production readiness. + +## Open Questions + +- None blocking preparation. During audit execution, record unavailable actors, fixtures, services, or routes as limitations instead of inventing proof. + +## Follow-up Spec Candidates + +Follow-up specs must be created only after the audit report identifies evidence-backed findings. Potential groups include: + +- Authorization/boundary remediation. +- Customer-safe output remediation. +- Evidence/currentness remediation. +- Critical runtime crash remediation. +- Navigation/surface reduction remediation. +- Report/PDF remediation. +- Governance lifecycle remediation. +- UX/productization polish. diff --git a/specs/407-full-browser-ux-runtime-audit/tasks.md b/specs/407-full-browser-ux-runtime-audit/tasks.md new file mode 100644 index 00000000..539898d9 --- /dev/null +++ b/specs/407-full-browser-ux-runtime-audit/tasks.md @@ -0,0 +1,153 @@ +# Tasks: Spec 407 - Full Browser/UX Runtime Audit + +**Input**: `specs/407-full-browser-ux-runtime-audit/spec.md`, `plan.md`, `checklists/requirements.md`, user-provided Spec 407 draft, Specs 400-406 lineage, Product Surface Contract, current roadmap/spec-candidates, and repo truth. + +**Tests**: No application tests are required or allowed by default. This spec performs a read-only browser/runtime audit and produces a final report. Existing tests may be referenced as evidence. New tests, fixtures, seeders, factories, migrations, runtime files, or docs outside this spec package are out of scope. + +## Test Governance Checklist + +- [ ] Lane assignment is `Browser / read-only audit`; no runtime or test change. +- [ ] No new Pest, fixture, seed, factory, DB, workspace, tenant, provider, session, or browser harness setup is introduced; ordinary browser login/session state from the existing environment may be used and recorded. +- [ ] Existing browser/dev environment and actors are used where available. +- [ ] Planned validation commands are read-only and do not pull in unrelated suite cost. +- [ ] Browser proof is the audit output, not proof of changed UI. +- [ ] Dirty state before/after is recorded. +- [ ] Any saved report artifact is created only under this spec directory and only if the operator explicitly asks for saved output. +- [ ] Findings are grouped into bounded remediation recommendations rather than implemented. + +## Phase 1: Preparation And Safety + +**Purpose**: Establish repo truth and prove the audit can run without implementation. + +- [ ] T001 Read `specs/407-full-browser-ux-runtime-audit/spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md`. +- [ ] T002 Re-read `AGENTS.md`, `.specify/memory/constitution.md`, `.specify/README.md`, `docs/ai-coding-rules.md`, relevant `docs/*-guidelines.md`, and `docs/product/standards/product-surface-contract.md`. +- [ ] T003 Re-read Specs 400-406 as read-only lineage and record their gate results and caveats without editing them. +- [ ] T004 Record current branch, HEAD, dirty state, tracked files, untracked files, and `git diff --check` before audit execution. +- [ ] T005 Confirm output mode: response-only report by default; spec-local saved report only if the operator explicitly requests it during execution. +- [ ] T006 Confirm no application code, tests, migrations, routes, config, policies, models, services, jobs, Filament resources/pages/widgets, Livewire components, Blade views, CSS, JavaScript, seeders, factories, lock files, generated assets, docs outside this package, or completed specs will be edited. +- [ ] T007 Confirm the target browser environment/base URL and whether Sail/dev server/browser session is already available; start only the necessary existing dev services if safe and required. +- [ ] T008 Identify available actors and existing actor/session sources without exposing secrets: workspace admin, limited workspace user, system operator, customer reviewer, unauthorized user, and cross-workspace user; record unavailable actors or missing actor sources as limitations. + +## Phase 2: Route And Surface Inventory + +**Purpose**: Build a coverage inventory from repo truth, not assumptions. + +- [ ] T009 Run read-only route/panel inventory commands, including route list and targeted `rg` searches for panels, resources, pages, relation managers, navigation, global search, policies, and customer/download routes. +- [ ] T010 Classify discovered surfaces as Admin, System, Customer, Shared/Internal, or Unknown/Ambiguous. +- [ ] T011 Inventory login/auth entry points, admin panel shell, system panel shell, workspace selection/context, environment selection/context, navigation groups, breadcrumbs, and global search posture. +- [ ] T012 Inventory dashboard/readiness, baseline compare, restore preview/readiness, backup schedules/sets/runs, provider setup/detail/readiness/freshness/permissions, evidence overview/detail/anchors, OperationRun list/detail/proof, findings/governance inbox, review packs, customer review workspace, reports/PDF, artifact lifecycle, membership/access-scope, and operational pages. +- [ ] T013 Record surfaces that are unreachable, blocked by missing fixtures, blocked by auth, blocked by external services, or intentionally not applicable. +- [ ] T014 Record existing browser/screenshot/test artifacts that can support or limit coverage claims. + +## Phase 3: Browser Walkthrough + +**Purpose**: Inspect rendered behavior safely across actor perspectives. + +- [ ] T015 Open the target application in the browser and record base URL, environment, browser name/version if available, and test data assumptions. +- [ ] T016 Audit login/auth entry behavior without exposing credentials. +- [ ] T017 Audit admin shell, navigation, page titles, breadcrumbs, workspace/environment context, empty/wrong context behavior, sidebar clarity, global search, and direct route behavior. +- [ ] T018 Audit system panel access, system dashboard/pages, system-only navigation, platform capability behavior, admin-user blocking, and cross-plane separation. +- [ ] T019 Audit workspace/environment switching, stale context, filters/table scoping, direct URL cross-workspace behavior, empty/no-environment state, and action target context. +- [ ] T020 Audit provider setup/detail/readiness, permission state, freshness, failed/partial/stale state, provider actions, and raw data exposure. +- [ ] T021 Audit baseline compare landing, drift summary, comparison matrix, evidence links, readiness labels, findings links, OperationRun proof links, and empty/stale snapshot states. +- [ ] T022 Audit restore preview/readiness safely up to confirmation/disabled state, including expired/stale/conflict/partial/failure states, action guard behavior, and proof links. +- [ ] T023 Audit backup schedules/sets/runs/detail, backup action guards, failure/partial/blocked states, evidence/audit links, and table/list action consistency. +- [ ] T024 Audit evidence overview/detail/anchors, current/stale/missing/failed/partial labels, customer-safe evidence output, and cross-workspace anchor access. +- [ ] T025 Audit OperationRun list/detail/proof, failed/cancelled/success states, customer-safe visibility, admin/system boundaries, and proof links. +- [ ] T026 Audit findings list/detail, risk states, governance inbox, exception/reference fields, evidence links, lifecycle states, ownership/next-step clarity, and customer-safe boundaries. +- [ ] T027 Audit review packs, released/current state, customer reviewer view, download/export links, archived/expired/held/deleted/missing artifact states where visible, and customer-safe data boundaries, including absence by default of raw payloads, OperationRun internals, raw IDs, source keys, fingerprints, stack traces, private URLs, and system/admin links. +- [ ] T028 Audit report receipt, management report/PDF state, failed/unavailable report state, customer-safe content, direct download authorization, stale/currentness labels, and broken PDF links. +- [ ] T029 Audit governance artifact lifecycle states including released, archived, expired, held, deleted/missing-file, download/export visibility, and lifecycle state labels where present. +- [ ] T030 Audit responsive/visual sanity at desktop and one narrower viewport where feasible, including modals, table overflow, long labels, status badges, warning banners, PDF/report links, actions, and empty/error states. +- [ ] T031 Record browser console, Livewire, Filament, network, HTTP, asset, modal/action, table/filter/search, PDF/download, and file-not-found symptoms as they occur, while avoiding load/performance testing and repeated polling beyond visible-state observation. + +## Phase 4: Critical Journey Matrix + +**Purpose**: Convert walkthrough coverage into journey-level readiness evidence. + +- [ ] T032 Complete Admin readiness review journey. +- [ ] T033 Complete Provider readiness review journey. +- [ ] T034 Complete Baseline drift review journey. +- [ ] T035 Complete Evidence/proof review journey. +- [ ] T036 Complete Backup readiness review journey. +- [ ] T037 Complete Restore readiness review journey without destructive execution. +- [ ] T038 Complete Finding/governance triage journey. +- [ ] T039 Complete Review pack/customer review journey. +- [ ] T040 Complete Report/PDF review journey. +- [ ] T041 Complete System operator review journey. +- [ ] T042 Complete Unauthorized/cross-workspace blocked access journey. +- [ ] T043 For each journey, record actor, start, end, completion, blocking issue, confidence, and follow-up. + +## Phase 5: Findings And Matrices + +**Purpose**: Turn observations into evidence-backed decisions. + +- [ ] T044 Populate Browser Coverage Matrix with surface, actor, route/page, state tested, result, runtime errors, UX issues, authorization issues, customer-safe issues, severity, and follow-up. +- [ ] T045 Populate Runtime Error Log with route/page, actor, action, error type, symptom, severity, and follow-up. +- [ ] T046 Create Findings sections for P0, P1, P2, and P3 using the required finding fields. +- [ ] T047 Classify each finding by category: runtime defect, UX/productization defect, authorization defect, customer-safe boundary defect, evidence/currentness defect, lifecycle defect, navigation/IA defect, empty/error-state defect, copy/terminology defect, test/proof gap, product decision gap, known deferred item, or duplicate/already covered. +- [ ] T048 Ensure every P0/P1 finding cites concrete browser evidence and repo/spec contract evidence where available. +- [ ] T049 Distinguish missing fixture/service conditions from product empty-state issues and runtime defects. +- [ ] T050 Verify findings do not include secrets, tokens, raw credential payloads, sensitive provider payloads, private signed URLs, customer data, or stack traces. + +## Phase 6: Boundary, Evidence, Lifecycle, And UX Summaries + +**Purpose**: Produce the required decision-quality summaries. + +- [ ] T051 Summarize Authorization / Boundary Results for admin panel, system panel, customer review, workspace isolation, environment isolation, direct URL checks, global search/navigation exposure, and download/export access. +- [ ] T052 Summarize Evidence / Currentness / Proof Results for evidence overview, evidence anchors, OperationRun proof, baseline evidence, restore/backup proof, review pack proof, report/PDF proof, customer-safe proof, and internal-detail demotion. +- [ ] T053 Summarize Governance Artifact Lifecycle Results for released, archived/expired, held, deleted/missing-file, export/download, and customer-safe lifecycle behavior. +- [ ] T054 Summarize UX / Productization Results for navigation clarity, page purpose clarity, empty states, failure/stale/partial states, terminology consistency, customer-facing polish, technical/internal leakage, and CTA/action clarity. +- [ ] T055 Carry forward Spec 404/405 external staging/Dokploy conditions and Spec 406 lifecycle/product-decision residuals honestly in the relevant summaries. + +## Phase 7: Readiness Decision And Remediation Plan + +**Purpose**: Decide what should happen next without implementing it. + +- [ ] T056 Set Candidate Gate Result to `PASS`, `PASS WITH CONDITIONS`, or `FAIL` according to the Spec 407 gate rules. +- [ ] T057 Answer readiness questions for controlled pilot, customer-facing hardening, sales/demo use, broader customer claims, production deployment, and next implementation block as Yes, No, or Conditional with short reasons. +- [ ] T058 Group findings into the fewest coherent follow-up specs or product decisions, such as authorization/boundary remediation, customer-safe output remediation, evidence/currentness remediation, runtime crash remediation, navigation/surface reduction remediation, report/PDF remediation, governance lifecycle remediation, or UX/productization polish. +- [ ] T059 Identify findings that should not become specs, known deferred items, and duplicate/already covered issues. +- [ ] T060 Provide one recommended next action based on the gate result. + +## Phase 8: Final Report And Close-Out + +**Purpose**: Deliver the audit result and prove no implementation occurred. + +- [ ] T061 Write the final audit report with sections A through P required by `spec.md`. +- [ ] T062 If no saved artifact was explicitly requested, keep the report in the final response only. +- [ ] T063 If a saved artifact was explicitly requested, create only the approved spec-local report path and record it in dirty-state close-out. +- [ ] T064 Run final read-only dirty-state checks and record branch, HEAD, tracked changes, untracked files, and `git diff --check`. +- [ ] T065 If unexpected files changed, stop and report exact paths, likely cause, and whether the audit remains trustworthy. +- [ ] T066 Confirm no application runtime code, tests, migrations, config, routes, views, policies, models, services, jobs, Filament resources/pages/widgets, Livewire components, Blade views, CSS, JavaScript, seeders, factories, lock files, generated assets, docs outside this package, or completed specs were modified. +- [ ] T067 Confirm final response states Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, browser result, tests/commands, deployment impact, visible complexity outcome, completed-spec rewrite assertion, and explicit no-implementation status. + +## Non-Goals Checklist + +- [ ] NT001 Do not implement fixes, refactors, UI redesign, copy cleanup, policy changes, route changes, or runtime hardening. +- [ ] NT002 Do not add or update tests, migrations, seeders, factories, fixtures, browser harnesses, or support helpers. +- [ ] NT003 Do not create users, mutate business data, execute destructive actions, release customer artifacts, send emails, trigger provider writes, or change billing/commercial/account settings. +- [ ] NT004 Do not rewrite completed specs, remove validation evidence, normalize completed task markers, or strip close-out language. +- [ ] NT005 Do not create docs outside this spec package or saved audit artifacts unless explicitly requested. +- [ ] NT006 Do not invent product decisions, statuses, role rules, readiness logic, customer-output categories, evidence types, lifecycle semantics, or navigation structures. +- [ ] NT007 Do not turn every finding into a new spec. +- [ ] NT008 Do not claim production/staging/Dokploy readiness from local-only browser proof. + +## Dependencies And Execution Order + +- Phase 1 must complete before browser work. +- Phase 2 inventory must complete before claiming coverage completeness. +- Phase 3 and Phase 4 can interleave by actor, but findings must reference exact route/page/actor/state. +- Phase 5 findings feed Phase 6 summaries. +- Phase 6 summaries feed Phase 7 readiness and remediation decisions. +- Phase 8 must record dirty state and no-implementation proof before final response. + +## Parallel Execution Examples + +- T011 through T014 can be performed in parallel by separate read-only file inspections. +- T020 through T029 can be split by domain surface if multiple reviewers are available, as long as all observations feed one final report. +- T051 through T054 can be drafted in parallel after findings are classified. + +## Recommended Implementation Strategy + +Run the audit like a release readiness gate, not a bug-fix session. Prioritize critical journeys and customer/boundary safety first, keep P0/P1 findings concrete, group lower-severity issues by root cause, and stop if proving behavior would require mutation, fixture creation, or a product decision.