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

Tasks: Spec 372 - Customer/Auditor Surface Safety Pass v1

Input: Design documents from specs/372-customer-auditor-surface-safety-pass/
Prerequisites: spec.md, plan.md, checklists/requirements.md, required Spec 368/370/371 input artifacts
Tests: Required. This is a runtime UI/productization change on customer/auditor surfaces, with Feature/Livewire coverage and bounded Browser smoke.

Implementation Notes For Task Completion

• T019-T021 were implemented in the shared focused file apps/platform/tests/Feature/Filament/Spec372CustomerAuditorSurfaceSafetyTest.php instead of separate per-surface files.
• T027 was satisfied by existing Blade composition plus payload/copy changes; no Blade edit was required.
• T055 was executed through ./vendor/bin/sail artisan test --compact tests/Browser/Spec372CustomerAuditorSurfaceSafetySmokeTest.php, which is the repository's working Sail harness for this Pest browser file.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in the smallest honest family, and the Browser addition is explicit.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• The declared surface test profile is explicit: customer-safe strategic review surface + artifact/evidence detail surfaces.
• Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.

Phase 1: Setup And Repo Truth Gate

Purpose: Confirm the current repo truth and prepare required Spec 372 artifacts before any runtime change.

• T001 Re-read specs/372-customer-auditor-surface-safety-pass/spec.md, plan.md, tasks.md, .specify/memory/constitution.md, docs/ai-coding-rules.md, docs/architecture-guidelines.md, docs/filament-guidelines.md, docs/security-guidelines.md, docs/testing-guidelines.md, and docs/performance-guidelines.md.
• T002 Confirm branch and dirty state with git status --short --branch, git diff --name-only, git diff --stat, and git rev-parse --short HEAD; record the result in specs/372-customer-auditor-surface-safety-pass/artifacts/validation-report.md.
• T003 Confirm completed context specs are read-only: specs/342-customer-review-workspace-final-consumption-productization, specs/344-customer-review-workspace-density-audience-polish, specs/347-review-pack-output-contract-readiness-semantics, specs/370-global-surface-information-architecture-contract, and specs/371-core-operator-view-surfaces-productization.
• T004 [P] Inspect Spec 368 customer/auditor inputs in specs/368-platform-ui-signal-to-noise-browser-audit/audit.md, page-scorecard.csv, findings.md, spec-candidates.md, artifacts/raw/browser-notes.md, and artifacts/screenshots/.
• T005 [P] Inspect Spec 370 inputs in specs/370-global-surface-information-architecture-contract/artifacts/surface-contract.md, surface-type-matrix.md, ui-bloat-patterns.md, page-assessment-checklist.md, copy-and-terminology-rules.md, and follow-up-spec-map.md.
• T006 [P] Inspect Spec 371 inputs in specs/371-core-operator-view-surfaces-productization/artifacts/implementation-notes.md, browser-verification-report.md, before-after-screenshot-index.md, page-contracts.md, and validation-report.md.
• T007 [P] Inspect current surface implementations in 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, and apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php.
• T008 [P] Inspect related tests under apps/platform/tests/Feature/Reviews, apps/platform/tests/Feature/Filament, apps/platform/tests/Feature/ReviewPack, apps/platform/tests/Feature/StoredReports, and apps/platform/tests/Browser.
• T009 Update specs/372-customer-auditor-surface-safety-pass/artifacts/source-audit-summary.md with Spec 368/370/371 inputs, before screenshots, reachability status, and verification labels.
• T010 Update specs/372-customer-auditor-surface-safety-pass/artifacts/affected-files.md with actual planned/touched files before runtime edits.
• T011 Update specs/372-customer-auditor-surface-safety-pass/artifacts/customer-surface-contracts.md with final page contracts for all scoped pages.
• T012 Update specs/372-customer-auditor-surface-safety-pass/artifacts/before-after-screenshot-index.md with all before screenshots and expected after/blocked screenshot names.
• T013 Confirm no migration, package, env var, queue, scheduler, storage, Graph, panel-provider, route, report-renderer, disclosure-policy, or Filament asset change is required; update spec.md and plan.md before coding if false.
• T014 Confirm Filament v5 / Livewire v4.0+ compliance and no Livewire v3 or Filament v3/v4 APIs.
• T015 Confirm panel provider registration remains apps/platform/bootstrap/providers.php.
• T016 Confirm no new global-search participation is introduced; preserve existing global-search posture for changed resources.

Phase 2: Tests And Browser Harness

Purpose: Add proving tests before or alongside implementation and keep browser proof bounded.

• T017 Add Feature/Livewire coverage for Customer Review Workspace customer-safe first viewport in apps/platform/tests/Feature/Filament/Spec372CustomerAuditorSurfaceSafetyTest.php.
• T018 Add Feature/Livewire coverage for Environment Review detail outcome/evidence/limitations hierarchy in apps/platform/tests/Feature/Filament/Spec372CustomerAuditorSurfaceSafetyTest.php or a narrower per-surface file.
• T019 [P] Add Feature/Livewire coverage for Review Pack detail readiness/evidence/limitations/download wording in apps/platform/tests/Feature/ReviewPack/Spec372ReviewPackCustomerSafetyTest.php if a separate file is clearer.
• T020 [P] Add Feature/Livewire coverage for Stored Report detail readiness/scope/evidence/limitations/default metadata demotion in apps/platform/tests/Feature/StoredReports/Spec372StoredReportCustomerSafetyTest.php if a separate file is clearer.
• T021 [P] Add conditional Feature/Livewire or HTTP coverage for Evidence Snapshot detail when reachable, or blocked reachability documentation assertions if not reachable, in apps/platform/tests/Feature/Filament/Spec372EvidenceSnapshotCustomerSafetyTest.php if a separate file is clearer.
• T022 Add RBAC/context coverage proving wrong workspace/environment access remains deny-as-not-found and missing capability does not expose download/diagnostic actions in apps/platform/tests/Feature/Filament/Spec372CustomerAuditorSurfaceSafetyTest.php or the narrower per-surface test files created by T019-T021.
• T023 Add no-render-Graph-call guard coverage in apps/platform/tests/Feature/Filament/Spec372CustomerAuditorSurfaceSafetyTest.php or the narrower per-surface test files where current tests do not already prove scoped page render paths are DB-only.
• T024 Add Browser smoke in apps/platform/tests/Browser/Spec372CustomerAuditorSurfaceSafetySmokeTest.php using the existing local smoke-login/review-output fixture.
• T025 Browser smoke must capture after screenshots under specs/372-customer-auditor-surface-safety-pass/artifacts/screenshots/ for every reachable scoped page and a blocked screenshot/reason for Evidence Snapshot if unreachable.

Phase 3: Customer Review Workspace (P1)

Goal: Preserve completed Spec 342/344/347 behavior while making the first viewport calmer and customer/auditor-safe.

Independent Test: Feature/Livewire and Browser checks prove outcome/readiness, decision-needed findings, accepted risks, evidence/report availability, limitations, one primary action, and no raw/internal diagnostics by default.

• T026 [US1] Update apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php only as needed to provide a single outcome/readiness/next-action payload without duplicating readiness truth.
• T027 [US1] Update apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php so the first viewport leads with customer-safe outcome, decisions/risks, evidence/report availability, limitations, and one primary action.
• T028 [US1] Demote or collapse secondary proof, operation proof, technical details, and support diagnostics in apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php.
• T029 [US1] Preserve visible decision-needed findings, accepted risks, evidence basis, review-pack/download state, and limitations in apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php and apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php.
• T030 [US1] Remove or group repeated readiness/status phrases and zero-card spam from the default Customer Review Workspace view in apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php.
• T031 [US1] Update relevant Customer Review Workspace tests in apps/platform/tests/Feature/Reviews, apps/platform/tests/Feature/Filament, and apps/platform/tests/Browser to assert semantics rather than stale copy, preserving all RBAC/state assertions and existing acknowledgement/create-next-review confirmation, authorization, and audit behavior.

Phase 4: Environment Review View (P1)

Goal: Make Environment Review detail read as a customer/auditor output, not an internal lifecycle record.

Independent Test: Detail page renders outcome, scope/period, evidence basis, decision-needed items, accepted risks where relevant, limitations, and one primary action before technical metadata.

• T032 [US2] Update apps/platform/app/Filament/Resources/EnvironmentReviewResource.php and/or its view page so acknowledgement/outcome/readiness is the first visible decision area.
• T033 [US2] Move technical review metadata, lifecycle repetition, source refs, exact non-critical timestamps, and OperationRun internals into sidebar/details/collapsed sections in apps/platform/app/Filament/Resources/EnvironmentReviewResource.php and its view page if one exists.
• T034 [US2] Keep evidence basis, review limitations, accepted-risk/finding context, and lifecycle truth visible without repeated peer summaries in apps/platform/app/Filament/Resources/EnvironmentReviewResource.php.
• T035 [US2] Ensure Environment Review detail uses customer/auditor language and avoids default troubleshooting/debug wording in apps/platform/app/Filament/Resources/EnvironmentReviewResource.php.
• T036 [US2] Update targeted Environment Review tests in apps/platform/tests/Feature/Filament or apps/platform/tests/Feature/Reviews to prove hierarchy, no raw/internal default content, and preserved authorization.
• T036A [US2] Preserve existing Environment Review refresh, publish, create-next, archive, and export action confirmation, authorization, audit, OperationRun UX, and capability behavior.

Phase 5: Review Pack And Stored Report Views (P1)

Goal: Keep artifact readiness, evidence basis, limitations, and download/view action clear while avoiding storage/debug framing.

Independent Test: Ready and limitations-bearing pack/report states render accurate output readiness and no false customer-ready/share-ready claims.

• T037 [US3] Update apps/platform/app/Filament/Resources/ReviewPackResource.php and/or its view page so pack readiness, included sections, evidence basis, limitations, and download/view state own the first viewport.
• T038 [US3] Preserve Review Pack generator, disclosure policy, download authorization, signed-route behavior, and existing high-impact action confirmation/audit behavior while editing apps/platform/app/Filament/Resources/ReviewPackResource.php.
• T039 [US3] Demote Review Pack renderer/storage metadata, OperationRun proof, raw IDs, and technical metadata into secondary/collapsed detail in apps/platform/app/Filament/Resources/ReviewPackResource.php.
• T040 [US3] Update apps/platform/app/Filament/Resources/StoredReportResource.php and/or its view page so report title/type, subject/scope, readiness/disclosure state, evidence basis, limitations, and download/view state own the first viewport.
• T041 [US3] Demote Stored Report storage/internal metadata, exact non-critical timestamps, raw IDs, and technical report internals into secondary/collapsed detail in apps/platform/app/Filament/Resources/StoredReportResource.php.
• T042 [US3] Update Review Pack and Stored Report tests in apps/platform/tests/Feature/ReviewPack, apps/platform/tests/Feature/StoredReports, and apps/platform/tests/Feature/Filament to assert state-aware labels, limitations visibility, preserved downloads, and no raw/internal default content.

Phase 6: Evidence Snapshot Conditional Handling (P2)

Goal: Productize Evidence Snapshot detail if reachable with existing fixtures, or document the blocked state without broad auth/routing repair.

Independent Test: Browser/HTTP proof shows either a customer/auditor-safe evidence detail or a documented blocked route/final URL/reason.

• T043 [US4] Use the existing smoke-login/review-output fixture in apps/platform/app/Console/Commands/SeedReviewOutputBrowserFixture.php and browser tests under apps/platform/tests/Browser to test Evidence Snapshot detail reachability; do not create a new auth flow in apps/platform.
• T044 [US4] If reachable, update apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php and/or its view page so subject, evidence type, captured-at, readiness, related review/report, limitations, and primary action appear before diagnostics.
• T045 [US4] If reachable, move raw provider object, internal IDs, OperationRun context, and diagnostics into collapsed/capability-gated technical details in apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php.
• T046 [US4] If not reachable, capture/document the blocked route, final URL/status, screenshot if possible, and follow-up Evidence Surface Browser Fixture Coverage v1 in artifacts/browser-verification-report.md and validation-report.md.
• T047 [US4] Update Evidence Snapshot tests under apps/platform/tests/Feature/Filament, apps/platform/tests/Feature/Findings, and apps/platform/tests/Feature/Workspaces only for semantics and reachability; preserve existing policy/global-search assertions.
• T047A [US4] Preserve existing Evidence Snapshot refresh, expire, and create-snapshot confirmation, authorization, audit, OperationRun UX, and customer-workspace-flow hiding/gating behavior.

Phase 7: UI Coverage, Artifacts, And Validation

Purpose: Complete the evidence trail and verify no out-of-scope implementation happened.

• T048 Update specs/372-customer-auditor-surface-safety-pass/artifacts/implementation-notes.md with design decisions, copy changes, action hierarchy changes, metadata demotion, and shared component impact.
• T049 Update specs/372-customer-auditor-surface-safety-pass/artifacts/browser-verification-report.md with URLs, fixture, screenshots, scores before/after when browser-verified, Evidence Snapshot reachability, remaining issues, and blocked pages.
• T050 Update specs/372-customer-auditor-surface-safety-pass/artifacts/customer-safety-checklist.md with pass/fail status for every scoped page.
• T051 Update specs/372-customer-auditor-surface-safety-pass/artifacts/validation-report.md with branch, HEAD, dirty state before/after, commands, tests, browser results, runtime files changed, out-of-scope files changed yes/no, limitations, and recommended next spec.
• T052 Update relevant docs/ui-ux-enterprise-audit/page-reports/... for every materially changed scoped page; update unresolved-pages.md, route-inventory.md, or design-coverage-matrix.md only when reachability, route inventory, archetype, or coverage status changes. Record no-count-change rationale only for unchanged registries.
• T053 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec372.
• T054 Run targeted existing regressions based on touched surfaces: CustomerReview, EnvironmentReview, ReviewPack, StoredReport, and EvidenceSnapshot filters as applicable.
• T055 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec372CustomerAuditorSurfaceSafetySmokeTest.php --compact if the browser smoke file exists.
• T056 Run cd apps/platform && ./vendor/bin/sail pint --dirty if PHP files changed.
• T057 Run git diff --check.
• T058 Confirm no migrations, seeders, packages, env vars, queues, scheduler, storage topology, Graph contracts/calls, panel providers, routes, report renderer, disclosure policy, customer portal, or legacy compatibility path were added.
• T059 Confirm no intentional changes to out-of-scope pages: OperationRun View, Backup Set View, Restore Run View, Operations Hub, Environment Dashboard, Baseline Profile View, Provider Connections, Environment Diagnostics, Required Permissions, System Panel.
• T060 Record final Livewire v4 compliance, provider registration location, global-search posture, destructive/high-impact action confirmation/authorization/audit status, asset strategy, tests, deployment impact, and Guardrail / Exception / Smoke Coverage in the implementation close-out response.

Dependencies

• Phase 1 must complete before runtime implementation.
• Phase 2 tests should be added before or alongside each surface change.
• Phase 3 can proceed independently of Phases 4-6 after setup.
• Phase 4 Review Pack and Stored Report work can run in parallel if separate files/tests are used.
• Phase 6 is conditional and must not block Phases 3-5 if Evidence Snapshot remains unreachable; it must still be documented.
• Phase 7 closes the feature and must run after all runtime changes.

Parallel Execution Examples

• T004, T005, T006, T007, and T008 can run in parallel during repo-truth inspection.
• T017, T018, T019, T020, and T021 can be split by surface after the shared test fixture strategy is known.
• T037-T039 and T040-T041 can run in parallel if Review Pack and Stored Report code paths do not share a modified helper.

Non-Goals / Stop Conditions

• Stop if implementation requires new domain truth, persistence, route/auth repair, report renderer changes, disclosure policy changes, Review Pack generator changes, or OperationRun lifecycle changes.
• Stop if a shared partial change materially alters out-of-scope operator/diagnostic/system pages without a spec/plan update.
• Stop if Evidence Snapshot reachability requires broad auth/routing repair; document and defer instead.