TenantAtlas/specs/372-customer-auditor-surface-safety-pass/plan.md

Implementation Plan: Spec 372 - Customer/Auditor Surface Safety Pass v1

Branch: 372-customer-auditor-surface-safety-pass | Date: 2026-06-11 | Spec: specs/372-customer-auditor-surface-safety-pass/spec.md
Input: User-provided Spec 372 draft, Spec 368 Candidate C, Spec 370 surface contract/follow-up map, completed Spec 371 artifacts, and repo-verified surface paths.

Summary

Apply the existing surface information architecture contract to customer/auditor review, report, pack, and evidence surfaces. The implementation will make outcome, readiness, evidence basis, limitations, and one customer-safe next action dominant while demoting diagnostics, internal IDs, OperationRun internals, provider payloads, raw JSON, and troubleshooting language. Runtime work is constrained to existing Filament pages/resources/views and their tests; no backend truth, generator, renderer, disclosure policy, route, migration, portal, or OperationRun behavior is added.

Technical Context

Language/Version: PHP 8.4.15; Laravel 12; Filament v5; Livewire v4.0+
Primary Dependencies: Filament Resources/Pages/Infolists/Tables/Actions, Blade views, existing badge/status helpers, existing policy/UI enforcement helpers, existing review/evidence/report models and resources
Storage: PostgreSQL via existing models only; no schema changes
Testing: Pest 4 Feature/Livewire tests and bounded Browser smoke
Validation Lanes: confidence + browser + git diff --check; Pint dirty if PHP changes
Target Platform: TenantPilot Laravel monolith under apps/platform
Project Type: Web application, Filament admin panel
Performance Goals: No Graph/provider calls during render; page render stays DB-only and query-safe
Constraints: No migrations, new persisted truth, new routes, new auth flow, new report/export backend, new OperationRun lifecycle, or broad shell/navigation changes
Scale/Scope: Five existing surfaces, with Evidence Snapshot conditional on current fixture reachability

UI / Surface Guardrail Plan

• Guardrail scope: changed existing customer/auditor surfaces.
• Affected routes/pages/actions/states/navigation/panel/provider surfaces:
  • /admin/reviews/workspace
  • /admin/workspaces/{workspace}/environments/{environment}/environment-reviews/{record}
  • /admin/workspaces/{workspace}/environments/{environment}/review-packs/{record}
  • /admin/workspaces/{workspace}/environments/{environment}/stored-reports/{record}
  • /admin/workspaces/{workspace}/environments/{environment}/evidence/{record} if reachable
• No-impact class, if applicable: N/A.
• Native vs custom classification summary: mixed native Filament resources/pages plus existing Blade composition; use native/shared primitives first.
• Shared-family relevance: status messaging, evidence/report viewers, review-pack/download affordances, limitation copy, diagnostics disclosure, action hierarchy.
• State layers in scope: page/detail payloads, visible page-level environment_id filter, detail action state, diagnostics disclosure state.
• Audience modes in scope: customer/read-only, auditor, MSP operator-as-facilitator, support where authorized.
• Decision/diagnostic/raw hierarchy plan: outcome/readiness/evidence/limitations/action first; diagnostics second; raw/support detail third and collapsed or capability-gated.
• Raw/support gating plan: collapse, demote, or capability-gate raw/provider/internal/OperationRun detail.
• One-primary-action / duplicate-truth control: one first-viewport block owns readiness and next action per page; later sections add proof or detail only.
• Handling modes by drift class or surface:
  • customer/auditor default raw internals: hard-stop-candidate
  • repeated readiness/status as peer cards: review-mandatory
  • shared partial affecting out-of-scope pages: exception-required or stop/update spec
  • Evidence Snapshot blocked by fixture: document-in-feature + follow-up-spec
• Repository-signal treatment: review-mandatory for UI coverage docs; report-only when no route/archetype count changes.
• Special surface test profiles: customer-safe strategic review surface; artifact/evidence detail surface; browser proof required.
• Required tests or manual smoke: Feature/Livewire state/RBAC tests plus Browser smoke screenshots for reachable surfaces.
• Exception path and spread control: any shared helper change must list all consumer surfaces in artifacts/affected-files.md; if it materially changes out-of-scope pages, stop and update spec/plan before continuing.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• UI/Productization coverage decision: update relevant page reports for every material scoped UI change. Record no-count-change rationale only for route/design matrix counts that truly do not change.
• Coverage artifacts to update: likely page-reports/ui-006-customer-review-workspace.md, ui-040-environment-review-detail.md, ui-042-review-pack-detail.md, unresolved-pages.md, and possibly route/design matrix only if reachability/coverage status changes.
• No-impact rationale: N/A.
• Navigation / Filament provider-panel handling: no panel/provider registration changes; apps/platform/bootstrap/providers.php remains unchanged.
• Screenshot or page-report need: screenshots required for all reachable scoped pages; blocked screenshot/reason required for Evidence Snapshot if unreachable.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes.
• Systems touched:
  • apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
  • apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
  • apps/platform/app/Filament/Resources/EnvironmentReviewResource.php
  • apps/platform/app/Filament/Resources/ReviewPackResource.php
  • apps/platform/app/Filament/Resources/StoredReportResource.php
  • apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php if reachable/safely in scope
  • scoped resource view pages under apps/platform/app/Filament/Resources/*/Pages
  • existing tests under apps/platform/tests/Feature, apps/platform/tests/Browser
• Shared abstractions reused: existing badge catalog/rendering, policy/UI enforcement, resource URL helpers, Review Pack readiness/disclosure truth from Spec 347, OperationRun link helpers, customer review state patterns from Specs 342/344.
• New abstraction introduced? why?: none planned. A scoped derived helper may be introduced only if it removes duplicated copy/status logic across the selected surfaces and stays current-release, derived-only, and non-framework.
• Why the existing abstraction was sufficient or insufficient: repo truth sources and UI helpers already exist; the gap is hierarchy/copy/disclosure consistency.
• Bounded deviation / spread control: no deviation expected. If native Filament cannot express a necessary customer-safe state, use existing Blade composition with Filament visual language and document the exception.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no new start/completion/dedupe semantics; existing proof links only.
• Central contract reused: existing OperationRun link helpers and policies.
• Delegated UX behaviors: N/A for new starts; no queued toast, run-enqueued browser event, terminal notification, or queued DB notification changes.
• Surface-owned behavior kept local: label operation proof as secondary/provenance/diagnostics, not customer evidence truth.
• Queued DB-notification policy: N/A.
• Terminal notification path: unchanged.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: no.
• Provider-owned seams: none.
• Platform-core seams: review/evidence/report presentation language only.
• Neutral platform terms / contracts preserved: workspace, environment, review, evidence, review pack, stored report, limitations, accepted risk, diagnostics.
• Retained provider-specific semantics and why: only existing report/evidence content may contain provider facts when customer-safe; provider IDs/payloads stay out of default UI.
• Bounded extraction or follow-up path: Diagnostic Surface Separation / Provider Connection readiness productization if provider/debug surfaces still need work.

Constitution Check

GATE: PASS for preparation. Re-check before runtime implementation.

• Inventory-first: no inventory/source-of-truth changes.
• Read/write separation: feature is read-oriented UI productization; no new write/change function. Existing high-impact actions remain on current confirmation/authorization/audit paths.
• Graph contract path: no new Graph calls; no render-time Graph calls allowed.
• Deterministic capabilities: existing capabilities/policies remain authoritative.
• RBAC-UX: membership and entitlement checks remain server-side; non-member/cross-scope remains 404; missing capability remains existing 403/disabled/hidden behavior.
• Workspace isolation: workspace context remains the shell/context boundary; environment filter is explicit page filter only.
• Tenant isolation: environment-owned records remain workspace + environment scoped.
• Run observability: no new OperationRun type or lifecycle; existing operation proof links are secondary.
• Test governance: confidence + browser lanes named; no hidden heavy family.
• Proportionality: no new persisted truth, enum/status family, broad abstraction, taxonomy, route, or portal.
• Shared pattern first: reuse existing review/evidence/report/badge/link patterns before adding local helpers.
• Provider boundary: no provider seam or Microsoft-shaped platform-core spread.
• UI-COV-001: UI impact declared; page-report updates are required for materially changed scoped pages, with no-count-change rationale limited to unchanged route/design registries.
• DECIDE-AUD/OPSURF: customer-readable default content precedes diagnostics/raw/support evidence; no false calmness.
• Filament v5 / Livewire v4: required.
• Panel provider location: unchanged in apps/platform/bootstrap/providers.php.
• Global search: do not enable new global search. Existing resource global-search posture must be preserved unless spec/plan updated.
• Destructive actions: no new destructive/high-impact action; if an implementation discovers one is needed, stop and update spec/plan before adding Action::make(...)->action(...), ->requiresConfirmation(), authorization, audit, notification, and tests.
• Asset strategy: no new assets expected; if assets are registered, deployment must include cd apps/platform && php artisan filament:assets.

Test Governance Check

• Test purpose / classification by changed surface: Feature/Livewire for state/RBAC/rendered content; Browser for hierarchy/screenshots; Unit only if a pure derived helper is introduced.
• Affected validation lanes: confidence and browser.
• Why this lane mix is the narrowest sufficient proof: customer/auditor safety is partly semantic rendered UI; Browser proof is necessary but bounded.
• Narrowest proving command(s):
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec372
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec372CustomerAuditorSurfaceSafetySmokeTest.php --compact
  • targeted filters for CustomerReview, EnvironmentReview, ReviewPack, StoredReport, EvidenceSnapshot as files touched
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check
• Fixture / helper / factory / seed / context cost risks: reuse review-output browser fixture; no shared default fixture widening.
• Expensive defaults or shared helper growth introduced?: no.
• Heavy-family additions, promotions, or visibility changes: one explicit Browser smoke.
• Surface-class relief / special coverage rule: no standard-native relief; special customer/auditor safety checks required.
• Closing validation and reviewer handoff: verify no raw/internal language in defaults, limitations visible, diagnostics collapsed, one primary action, Evidence Snapshot conditional handling, and no out-of-scope refactor.
• Budget / baseline / trend follow-up: none expected.
• Review-stop questions: lane fit, breadth, hidden fixture cost, shared partial spread, false customer-ready claims.
• Escalation path: document-in-feature for contained UI tradeoffs; follow-up-spec for fixture/diagnostic structural gaps; reject-or-split if backend/portal/report-generator scope appears.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• Why no dedicated follow-up spec is needed: the selected surfaces are one coherent customer/auditor handoff path; diagnostics/provider/support surfaces are deferred separately.

Project Structure

Documentation (this feature)

specs/372-customer-auditor-surface-safety-pass/
├── spec.md
├── plan.md
├── tasks.md
├── checklists/
│   └── requirements.md
└── artifacts/
    ├── source-audit-summary.md
    ├── affected-files.md
    ├── customer-surface-contracts.md
    ├── before-after-screenshot-index.md
    ├── implementation-notes.md
    ├── browser-verification-report.md
    ├── customer-safety-checklist.md
    ├── validation-report.md
    └── screenshots/

Source Code (repository root)

apps/platform/app/Filament/Pages/Reviews/
apps/platform/app/Filament/Resources/
apps/platform/app/Filament/Resources/*/Pages/
apps/platform/resources/views/filament/pages/reviews/
apps/platform/resources/views/filament/resources/
apps/platform/resources/views/components/
apps/platform/tests/Feature/
apps/platform/tests/Browser/
docs/ui-ux-enterprise-audit/

Structure Decision: use existing Laravel/Filament monolith structure. No new base folders. Spec-local artifacts stay under specs/372-*; runtime changes stay scoped to existing platform paths if implemented later.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Multiple customer/auditor surfaces in one spec	They form one review/report/evidence handoff path and share the same safety contract	Repeating one-page specs would preserve cross-surface inconsistencies and duplicate review burden
Browser smoke required	Customer/auditor safety depends on rendered hierarchy and first-viewport language	Feature tests alone cannot prove density, collapsed diagnostics, and screenshots

Proportionality Review

• Current operator problem: customers/auditors still need a safer, calmer, evidence-first output path across existing surfaces.
• Existing structure is insufficient because: page-level productization has progressed unevenly; prior specs solved individual surfaces or output contracts, not the cross-surface default disclosure contract.
• Narrowest correct implementation: existing surfaces only, page-local or scoped derived helpers only, no backend truth changes.
• Ownership cost created: focused tests, one browser smoke, screenshots, spec-local contract/checklist artifacts.
• Alternative intentionally rejected: customer portal, report renderer rewrite, generic evidence/readiness framework, diagnostic surface rewrite, route/auth fixture repair inside this feature.
• Release truth: current-release customer trust and sellability hardening.

Implementation Phases

Phase 0 - Repo Truth And Pre-Implementation Gate

• Re-read Spec 368, 370, 371 inputs and related completed specs 342/344/347 as read-only context.
• Verify current branch, HEAD, dirty state, and existing specs/372-* artifacts.
• Produce source-audit-summary.md, affected-files.md, customer-surface-contracts.md, before-after-screenshot-index.md, and customer safety checklist baseline.
• Determine current reachability for Evidence Snapshot using existing fixture/harness only.

Phase 1 - Test And Browser Proof Design

• Add focused Feature/Livewire coverage for customer-safe default content, diagnostics absence/collapse, RBAC/context behavior, and no false-ready claims on touched surfaces.
• Add bounded Browser smoke with existing smoke-login/review-output fixture and screenshot capture for reachable pages.
• Include blocked Evidence Snapshot path handling if still unreachable.

Phase 2 - Customer Review Workspace Safety Pass

• Preserve Spec 342/344/347 outcomes.
• Reduce competing readiness/status/action density only where current runtime still shows it.
• Keep decision-needed findings, accepted risks, evidence/report pack, limitations, and one primary action visible.

Phase 3 - Environment Review Detail Safety Pass

• Recompose first viewport around outcome, review scope/period, evidence basis, limitations, and next action.
• Move technical metadata/source refs/operation proof to details/aside as appropriate.
• Preserve lifecycle truth without repeating it as peer summaries.

Phase 4 - Review Pack And Stored Report Artifact Pass

• Keep output/report readiness and disclosure truth first.
• Keep evidence basis and limitations visible.
• Demote storage, renderer, operation, and internal metadata.
• Preserve existing download/view authorization and high-impact action behavior.

Phase 5 - Evidence Snapshot Conditional Pass

• If reachable, apply evidence proof vs diagnostics separation and capture screenshots.
• If not reachable, document the blocked state, final URL/reason, and follow-up recommendation. Do not fix auth/routing broadly.

Phase 6 - UI Coverage, Validation, And Close-Out

• Update page-report coverage for materially changed scoped pages and document no-count-change rationale only for unchanged route/design registries.
• Update all spec-local artifacts with final results.
• Run targeted tests, browser smoke, Pint dirty if applicable, and git diff --check.
• Record final Livewire v4/provider/global-search/destructive-action/asset/deployment notes.

Risk Controls

• Stop before backend/report/generator/disclosure-policy/route/auth changes unless spec/plan are updated.
• Stop before touching completed operator surfaces from Spec 371.
• Prefer page-local changes; inspect shared partial consumers before edits.
• Treat missing Evidence Snapshot fixture as a documented blocker, not a reason for broad auth/routing work.
• Do not weaken existing policy/signed download/audit/destructive action behavior.

Rollout Considerations

• Migrations: none expected.
• Env vars: none expected.
• Queues/scheduler: none expected.
• Storage: none expected.
• Filament assets: none expected; if unexpectedly registered, include php artisan filament:assets.
• Staging/production: validate on Staging before Production because customer/auditor output surfaces are sellability/trust surfaces.