# 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)

```text
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)

```text
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.