TenantAtlas/specs/377-post-productization-browser-reaudit-closeout-gate/plan.md

Implementation Plan: Spec 377 - Post-Productization Browser Re-Audit and Closeout Gate v1

Branch: 377-post-productization-browser-reaudit-closeout-gate | Date: 2026-06-13 | Spec: specs/377-post-productization-browser-reaudit-closeout-gate/spec.md Input: Feature specification from /specs/377-post-productization-browser-reaudit-closeout-gate/spec.md

Summary

Prepare and later execute a read-mostly browser closeout audit for the UI Signal-to-Noise / Productization program. The implementation must summarize Specs 368 and 370-376, browser-audit the required existing surfaces, capture screenshots, create scorecards and comparison artifacts, document Spec 375 guard status and Spec 376 fixture coverage, record remaining findings, and make a final closed, closed-with-follow-up, or open decision. No application runtime code is in scope.

Technical Context

Language/Version: PHP 8.4.15 / Laravel 12.52 / Filament 5.2.1 / Livewire 4.1.4, for repo context only. Primary Dependencies: Existing Laravel/Filament app, existing browser/auth fixtures, existing Spec 375 guard or equivalent tests. No new dependency. Storage: Spec-local Markdown, CSV, and screenshot artifacts only. No database changes. Testing: Browser verification/manual smoke, existing targeted Pest browser smokes if cheap and available, git diff --check, Spec 375 guard in warn mode if available. Validation Lanes: browser, heavy-governance/reporting, shell validation. Target Platform: Local Sail-first development environment; browser viewport 1440x1000 minimum. Project Type: Laravel monolith plus spec artifacts. Performance Goals: Keep audit bounded to the required surfaces; no broad route crawl or full visual regression suite. Constraints: No runtime refactor, no new fixtures/routes/auth flows, no completed-spec history rewrites, no application file changes unless the spec/plan are updated first for an explicitly bounded harness correction. Scale/Scope: 18 named surfaces plus program-level checks across Specs 370-376.

UI / Surface Guardrail Plan

• Guardrail scope: workflow-only guardrail evaluation / audit-only.
• Affected routes/pages/actions/states/navigation/panel/provider surfaces: Existing surfaces are audited only: Environment Dashboard, Operations Hub, OperationRun View, Backup Set View, Restore Run View, Baseline Profile View, Customer Review Workspace, Environment Review View, Review Pack View, Stored Report View, Evidence Snapshot View, Provider Connections List, Provider Connection Detail, Environment Diagnostics / Repair Diagnostics, Support Diagnostics Modal, Required Permissions, System Dashboard, System Operations.
• No-impact class, if applicable: audit-only spec artifacts.
• Native vs custom classification summary: consume prior classifications from Specs 368, 370, and docs/ui-ux-enterprise-audit/; do not reclassify runtime behavior unless reporting observed drift.
• Shared-family relevance: reports/evidence/diagnostics surfaces are observed only.
• State layers in scope: shell/page/detail state observed during browser audit; no ownership changes.
• Audience modes in scope: operator-MSP, customer/read-only, support-platform/system where fixtures allow.
• Decision/diagnostic/raw hierarchy plan: score each reachable surface for decision-first and metadata/diagnostics separation.
• Raw/support gating plan: record violations as findings; do not fix in this spec.
• One-primary-action / duplicate-truth control: score and record findings against Spec 368/370 criteria.
• Handling modes by drift class or surface: report-only for observed issues; follow-up-spec for confirmed structural gaps; open/blocked decision when closeout gates fail.
• Repository-signal treatment: report-only unless a missing predecessor artifact blocks a full closeout decision.
• Special surface test profiles: browser closeout audit; manual smoke; existing browser smoke tests if available.
• Required tests or manual smoke: browser open and screenshot for each reachable surface; exact blocked reason for others; Spec 375 guard check.
• Exception path and spread control: no runtime exceptions. Any implementation need to touch runtime code is a stop condition until spec/plan are updated.
• Active feature PR close-out entry: Smoke Coverage / Guardrail / Fixture Coverage.
• UI/Productization coverage decision: No UI surface impact; audit artifacts only.
• Coverage artifacts to update: none by default. Do not update docs/ui-ux-enterprise-audit/ in this spec unless this plan is explicitly changed.
• No-impact rationale: The spec observes existing UI and writes evidence under specs/377-*; it does not change reachable product surfaces.
• Navigation / Filament provider-panel handling: observe /admin and /system behavior only.
• Screenshot or page-report need: yes, screenshots under this spec package; no docs UI page-report updates.

Shared Pattern & System Fit

• Cross-cutting feature marker: no runtime cross-cutting change.
• Systems touched: Spec artifacts, browser harness usage, existing guard command/test.
• Shared abstractions reused: Existing browser fixture patterns from Specs 371-376; Spec 368 score model; Spec 370 contract; Spec 375 guard; Spec 376 fixture matrix.
• New abstraction introduced? why?: none.
• Why the existing abstraction was sufficient or insufficient: Existing artifacts already define the audit model; this spec composes them into closeout evidence.
• Bounded deviation / spread control: none.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no.
• Central contract reused: N/A.
• Delegated UX behaviors: N/A.
• Surface-owned behavior kept local: N/A.
• Queued DB-notification policy: N/A.
• Terminal notification path: N/A.
• Exception path: none.

The OperationRun detail page is a browser-audit target only.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: no runtime seam change.
• Provider-owned seams: Existing Provider Connections and Required Permissions surfaces are audited only.
• Platform-core seams: Existing System Dashboard and System Operations surfaces are audited only.
• Neutral platform terms / contracts preserved: no vocabulary changes.
• Retained provider-specific semantics and why: N/A.
• Bounded extraction or follow-up path: record follow-up-spec only if evidence shows provider/platform boundary confusion remains.

Constitution Check

GATE: Must pass before implementation.

• Inventory-first: PASS. No inventory/backups/snapshots are changed.
• Read/write separation: PASS. Read-mostly browser audit only; no write/change behavior.
• Graph contract path: PASS. No Graph calls are added. Browser rendering must not be made to call Graph through new code.
• Deterministic capabilities: PASS. No capability derivation changes.
• RBAC-UX: PASS. Existing auth and policies remain authoritative; blocked access is documented, not bypassed.
• Workspace isolation: PASS. Existing workspace/environment/tenant scoping is observed only.
• Tenant isolation: PASS. No query or access code changes.
• Run observability: PASS. No new remote, queued, scheduled, or long-running operation.
• OperationRun start UX: PASS. No OperationRun creation or start UX.
• Test governance: PASS. Browser/heavy-governance cost is explicit and bounded to closeout; no fast-lane drift.
• Proportionality: PASS. Spec-local artifacts are the narrowest durable closeout evidence.
• No premature abstraction: PASS. No new runtime abstraction or framework.
• Persisted truth: PASS. No database/persisted runtime truth.
• Behavioral state: PASS. Report-only closeout labels; no runtime states.
• UI semantics: PASS. Existing score semantics are reused from Spec 368; no new UI framework.
• Shared pattern first: PASS. Existing browser/guard/fixture patterns are reused.
• Provider boundary: PASS. No boundary changes.
• V1 explicitness / few layers: PASS. Direct audit artifacts.
• Spec discipline / bloat check: PASS. Proportionality review is present and scope is bounded.
• Badge semantics: PASS. No badge changes.
• Filament-native UI: PASS. No Filament UI changes. Livewire v4.0+ compliance remains satisfied by installed Livewire 4.1.4.
• UI/Productization coverage: PASS. No UI surface impact is checked with rationale; screenshots are spec-local audit evidence.
• Filament Action Surface Contract: PASS / N/A. No Resource, RelationManager, Page, or action changes.

Test Governance Check

• Test purpose / classification by changed surface: Browser and Heavy-Governance/reporting for audited surfaces; N/A for runtime changes.
• Affected validation lanes: browser; heavy-governance/reporting; shell validation.
• Why this lane mix is the narrowest sufficient proof: The feature is a closeout audit; screenshots, scorecards, guard status, and fixture status are the proof.
• Narrowest proving command(s): git diff --check; Spec 375 guard in warn mode or equivalent; browser verification of required surfaces; targeted existing browser smoke filters only if available and cheap.
• Fixture / helper / factory / seed / context cost risks: Existing browser fixtures may be expensive or unstable; do not expand defaults.
• Expensive defaults or shared helper growth introduced?: no.
• Heavy-family additions, promotions, or visibility changes: none beyond this explicit closeout audit.
• Surface-class relief / special coverage rule: N/A - audit-only.
• Closing validation and reviewer handoff: Reviewers should verify no runtime files changed, all required artifacts exist, blocked states are exact, and final decision follows the decision rules.
• Budget / baseline / trend follow-up: none unless follow-up roadmap proposes guard CI expansion.
• Review-stop questions: Did any runtime file change? Were completed specs modified? Were blocked pages scored? Did any P0/P1 get hidden as polish?
• Escalation path: document-in-feature for limitations; follow-up-spec for remaining productization/fixture/guard gaps.
• Active feature PR close-out entry: Smoke Coverage / Guardrail / Fixture Coverage.
• Why no dedicated follow-up spec is needed: Follow-ups are created only if the audit finds remaining gaps.

Project Structure

Documentation (this feature)

specs/377-post-productization-browser-reaudit-closeout-gate/
├── spec.md
├── plan.md
├── tasks.md
├── checklists/
│   └── requirements.md
└── artifacts/
    ├── source-program-summary.md
    ├── surface-re-audit-scorecard.csv
    ├── before-after-score-comparison.csv
    ├── screenshot-index.md
    ├── closeout-decision.md
    ├── remaining-findings.md
    ├── guard-status-report.md
    ├── fixture-coverage-status.md
    ├── browser-verification-report.md
    ├── validation-report.md
    ├── follow-up-roadmap.md
    └── screenshots/

Source Code (repository root)

No source code changes are planned.

Structure Decision: The only created/updated files should live under specs/377-post-productization-browser-reaudit-closeout-gate/.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Browser/heavy-governance audit cost	The closeout decision requires current UI evidence, screenshots, and blocked-state proof.	A repo-only summary would not prove whether the productized UI is actually quieter and reachable.
Many surfaces in one audit	The program-level closeout spans the surfaces touched by Specs 368 and 370-376.	Splitting the closeout into multiple specs would defer the actual program decision and hide cross-surface regressions.

Proportionality Review

• Current operator problem: The productization program lacks a final evidence-backed closeout decision.
• Existing structure is insufficient because: Individual specs prove individual slices; they do not produce one final after-audit scorecard and decision.
• Narrowest correct implementation: Spec-local audit files and screenshots only.
• Ownership cost created: One-time browser audit and review of artifacts.
• Alternative intentionally rejected: More productization fixes before measuring closeout readiness.
• Release truth: Current-release truth.

Implementation Phases

Phase 1 - Repo safety and source readiness

Reconfirm branch/status, create artifact directories, and summarize predecessor artifacts without editing completed specs.

Phase 2 - Browser audit setup

Identify exact app URL, auth/fixture path, and required browser routes. Record any unavailable harness state before scoring.

Phase 3 - Surface browser re-audit

Open each required surface at 1440x1000, capture screenshots or blocked screenshots, and record reachability/limitations.

Phase 4 - Scorecards and program checks

Score reachable pages, compare against Spec 368 where source scores exist, run/check Spec 375 guard, and summarize Spec 376 fixture coverage.

Phase 5 - Closeout decision and follow-up roadmap

Write remaining findings, closeout decision, follow-up roadmap, browser verification report, and validation report.

Phase 6 - Final validation

Run git diff --check, confirm runtime files changed yes/no, and ensure all required artifacts exist.

Deployment / Ops Considerations

• Staging/Production: No deployment impact unless a later implementation deviates and changes runtime code.
• Migrations: none.
• Environment variables: none.
• Queues/workers/scheduler: none.
• Storage/volumes: spec screenshots are repository artifacts only.
• Dokploy: no release-specific action.
• Filament assets: no registered assets; filament:assets is not required by this spec.

Filament v5 Output Contract

• Livewire v4.0+ compliance: The project uses Livewire 4.1.4; this spec changes no Livewire code.
• Provider registration location: Existing Laravel 12 panel providers remain in apps/platform/bootstrap/providers.php; this spec changes no providers.
• Global search: No Resource global-search behavior changes.
• Destructive actions: No destructive or high-impact actions are added or changed.
• Asset strategy: No new assets. No deploy-time filament:assets requirement from this spec.
• Testing plan: Browser verification/reporting only; no Livewire/Filament action tests unless runtime scope is explicitly changed first.