TenantAtlas/specs/397-receipt-page-reduction/plan.md

Implementation Plan: Spec 397 - Receipt Page Reduction Pass v1

Branch: 397-receipt-page-reduction
Spec: specs/397-receipt-page-reduction/spec.md
Created: 2026-06-22
Status: Prepared for implementation
Preparation scope: Plan only. No application code changed.

Summary

Reduce existing /admin receipt-style detail surfaces so they answer one product receipt question by default: what happened, when, which scope it covered, whether it can be trusted, and the one next action. The implementation must demote raw technical evidence, OperationRun proof, raw IDs, source keys, detector output, payloads, renderer metadata, internal artifact paths, and long tables into deliberate authorized internal/audit detail.

This is a Product Surface Contract runtime-reduction pass, not a new readiness adapter, report engine, receipt engine, or technical-annex framework.

Technical Context

Language/Version: PHP 8.4.15
Framework: Laravel 12.52.0
UI: Filament 5.2.1, Livewire 4.1.4
Database: PostgreSQL via Sail
Testing: Pest 4.3.1 / PHPUnit 12.5.4, focused Feature/Filament and Browser lanes
Panel provider location: Laravel 12 providers are registered in apps/platform/bootstrap/providers.php; no provider registration change is expected.
Assets: No new Filament assets expected. If implementation registers assets, deployment must include cd apps/platform && php artisan filament:assets.
Runtime constraints: No Graph calls during render, no new queue behavior, no migrations, no new persisted truth, no new package dependencies.

Constitution Check

Pre-Implementation Gate

• Inventory-first, snapshots-second: Pass. Receipt pages summarize existing observed/artifact truth; no new source of truth is introduced.
• Read/write separation by default: Pass. The spec is mostly read-only UI reduction. Any touched destructive/high-impact action must retain confirmation, authorization, audit, and tests.
• Single Contract Path to Graph: Pass. No Graph work is in scope.
• Proportionality First / No Premature Abstraction: Pass with constraint. Do not add a broad Receipt or Technical Annex framework. Use existing Filament/shared primitives and small local helpers only when they reduce concrete duplication.
• No New Persisted Truth Without Source-of-Truth Need: Pass. No migrations/tables/columns.
• No New State Without Behavioral Consequence: Pass. Reuse Product Surface Contract vocabulary as display mapping; do not add a new enum/status family.
• UI Semantics Must Not Become Their Own Framework: Pass. The goal is visible complexity reduction, not a semantic layer.
• Product Surface Contract Gate (PSC-001): Applies. Spec names page archetype, surface budgets, technical demotion, canonical status vocabulary, browser proof, human sanity, no-legacy posture, and exceptions.
• Workspace/Tenant Isolation: Pass if existing policies/resource scoping are preserved and technical details enforce the same entitlement checks.
• OperationRun standards: Pass if OperationRun proof is demoted without changing OperationRun lifecycle or notifications.
• Test Governance: Pass if tests stay in narrow Feature/Filament and Browser lanes and any helper/fixture cost is explicit.

Post-Design Gate

Prepared artifacts keep the scope bounded to existing receipt-style surfaces and forbid implementation until tasks validate repo-specific file paths, policies, actions, and browser fixtures.

Existing Repository Surfaces Likely Affected

Implementation must verify exact current code before editing. Likely affected surfaces:

Filament Resources / Pages

• apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php
• apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
• apps/platform/app/Filament/Resources/BaselineSnapshotResource.php
• apps/platform/app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php
• apps/platform/app/Filament/Resources/RestoreRunResource.php
• apps/platform/app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php
• apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunDetailPresenter.php
• apps/platform/app/Filament/Resources/ReviewPackResource.php
• apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php
• apps/platform/app/Filament/Resources/StoredReportResource.php
• apps/platform/app/Filament/Resources/StoredReportResource/Pages/ViewStoredReport.php

Blade / Infolist / Report Views

• apps/platform/resources/views/filament/infolists/entries/evidence-dimension-summary.blade.php
• apps/platform/resources/views/filament/infolists/entries/evidence-gap-subjects.blade.php
• apps/platform/resources/views/filament/infolists/entries/baseline-snapshot-summary-table.blade.php
• apps/platform/resources/views/filament/infolists/entries/baseline-snapshot-technical-detail.blade.php
• apps/platform/resources/views/filament/infolists/entries/baseline-snapshot-groups.blade.php
• apps/platform/resources/views/filament/infolists/entries/restore-results.blade.php
• apps/platform/resources/views/filament/infolists/entries/restore-preview.blade.php
• apps/platform/resources/views/filament/infolists/entries/review-pack-output-guidance.blade.php
• apps/platform/resources/views/review-packs/rendered-report.blade.php
• Restore proof/detail partials under apps/platform/resources/views/filament/forms/components/partials/ and apps/platform/resources/views/filament/forms/components/restore-run-*.blade.php if they are reused by the detail page.

Shared Support / Status Paths

• apps/platform/app/Support/Badges/BadgeCatalog.php
• apps/platform/app/Support/Badges/BadgeDomain.php
• Baseline, restore, evidence, review-pack, and stored-report badge/domain mapping classes under apps/platform/app/Support/Badges/.
• Existing Review Pack output gate/guidance classes under apps/platform/app/Support/ReviewPacks/.
• Existing reference/link resolvers under apps/platform/app/Support/References/ if default links need demotion.

Existing Tests To Inspect / Extend

• apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php
• apps/platform/tests/Feature/Filament/BaselineSnapshot*Test.php
• apps/platform/tests/Feature/Filament/Spec335RestoreRunDetailProductizationTest.php
• apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php
• apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackOutputContractTest.php
• apps/platform/tests/Feature/ReviewPack/Spec392CustomerOutputRouteGateTest.php
• apps/platform/tests/Feature/StoredReports/StoredReportDetailPresentationTest.php
• apps/platform/tests/Browser/Spec335RestoreRunDetailProductizationSmokeTest.php
• apps/platform/tests/Browser/Spec337EvidenceReviewPackProductFlowSmokeTest.php
• apps/platform/tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php
• apps/platform/tests/Browser/Spec277StoredReportsSurfaceSmokeTest.php

Technical Approach

1. Inventory current receipt default surfaces
   Capture the default-visible sections, actions, top-level statuses, raw technical links, and long tables on the target pages. Record the exact files/components that render each default-visible issue.

2. Reduce one page family at a time
   Start with Evidence Snapshot and Baseline Snapshot because they have the clearest receipt overload and browser evidence from Spec 377. Then address Restore Run, Review Pack receipt sections, and Stored Report receipt metadata.

3. Use existing product/status paths first
   Prefer existing BadgeCatalog mappings, Review Pack output guidance, RestoreRunDetailPresenter, Filament infolists/sections, and existing policy/UI-enforcement helpers. Add only local helpers when repeated page-level logic cannot stay readable.

4. Demote, do not delete, audit depth
   Move raw/internal details into collapsed sections, secondary action groups, existing internal detail sections, or separate authorized audit paths. Customer/read-only defaults must not expose internal detail.

5. Enforce receipt budgets
   Each touched page must have one primary user question, one primary action, max two secondary actions by default, no default OperationRun/evidence/source-key/detector/payload links, and max eight default rows before show-more/pagination/internal detail.

6. Preserve safety semantics
   Destructive/high-impact actions remain confirmation-protected and authorization-checked. Demoting links must not weaken access checks.

Domain / Model Implications

• No new model, migration, table, column, persisted status, enum family, or lifecycle state.
• Existing records remain authoritative:
  • Evidence: EvidenceSnapshot and related items/reports.
  • Baseline: BaselineSnapshot and BaselineSnapshotItem.
  • Restore: RestoreRun plus existing OperationRun association.
  • Review/report: ReviewPack, StoredReport, rendered-report profile/disclosure truth.
• Receipt status and next action are derived display behavior from existing record state and authorization, not new stored truth.

UI / Filament Implications

• Filament v5 / Livewire v4.1.4 compliance is mandatory.
• Use native Filament components, infolists, sections, action groups, and existing shared primitives before local Blade/CSS.
• Avoid publishing Filament internal views.
• Keep global search safe:
  • If any touched resource is globally searchable, it must retain a safe View/Edit page and $recordTitleAttribute.
  • If the receipt page cannot be safely linked for search results, global search must remain disabled.
• Tables need meaningful empty states and capped/default-limited rows where product-facing.
• URL-only actions remain navigation-only. Any mutating/destructive action must use ->action(...), ->requiresConfirmation(), authorization, audit where mutating, and tests.

Livewire Implications

• Resource pages are Livewire components in tests.
• Avoid chatty server-driven reactivity. Receipt reduction should be mostly static presentation from already-loaded records.
• Do not perform Graph or remote work during render.
• Browser proof must catch Livewire/Filament runtime errors on the focused paths.

OperationRun / Monitoring Implications

• No new OperationRun type, lifecycle transition, notification, or queue behavior.
• OperationRun remains execution truth.
• Product receipt default pages must not expose OperationRun proof links as primary/default content.
• If a page still needs operation proof, expose it through secondary/internal/audit detail for authorized users.

RBAC / Policy Implications

• Existing policies and resource scoping remain authoritative.
• Technical/internal detail must use existing entitlement checks and capabilities.
• Non-members remain deny-as-not-found.
• Members lacking capability receive 403 after scope is established.
• UI visibility/disabled state is not authorization.
• Any touched destructive/high-impact action must retain UiEnforcement / WorkspaceUiEnforcement or equivalent existing pattern plus server-side authorization.

Audit / Evidence Implications

• Existing audit logs remain the audit trail.
• No new audit action is required for hiding/demoting UI detail.
• Any touched mutating/destructive action must preserve or improve audit logging.
• Product receipt summaries must not imply that an artifact is customer-safe, current, or recoverable unless existing truth supports that claim.

Data / Migration Implications

• No migration is planned.
• No env var, queue worker, scheduler, or storage change is planned.
• No JSON/JSONB schema change is planned.
• If implementation discovers a data shape gap requiring persistence, stop and update spec/plan before continuing.

Product Surface Contract Plan

• No-legacy posture: canonical replacement. Old overloaded receipt defaults are not preserved.
• Page archetype: Receipt Page, with Review Pack/Stored Report Report Page boundary explicitly checked before editing.
• Surface budgets: one primary question, one primary action, no raw technical default links, max eight table rows by default.
• Technical Annex/deep-link demotion: OperationRun, raw evidence, IDs, source keys, detectors, payloads, renderer metadata, and internal artifact paths are secondary/internal.
• Canonical status vocabulary: Product Surface states only for top-level receipt status.
• Product Surface exceptions: none planned. Any exception stops implementation until this plan/spec is updated.
• Browser proof: required because rendered UI changes are expected. Evidence Snapshot, Baseline Snapshot, Restore Run, and every changed Review Pack or Stored Report receipt surface must be covered.
• Human Product Sanity: required.
• Coverage registry: update docs/ui-ux-enterprise-audit/route-inventory.md and docs/ui-ux-enterprise-audit/design-coverage-matrix.md for each target surface whose default rendered UI changes. Other registry files are not required unless implementation changes archetype, expands default content, or cannot classify a touched page.
• Implementation report: required in specs/397-receipt-page-reduction/implementation-report.md during implementation, not during this preparation step.

Test Strategy

Planned Test Purpose / Classification

• Unit: Only for pure derived status/action/table-cap helper logic if such helpers are introduced.
• Feature / Filament / Livewire: Primary lane for page default-visible sections, action hierarchy, authorization/technical detail gating, and destructive action preservation.
• Browser: Focused receipt smoke across representative target pages because rendered UI reduction is the product outcome.
• Heavy-governance: Not expected.
• PostgreSQL: Not expected unless implementation unexpectedly touches migrations/query plans.

Minimal Validation Commands

Implementation should choose exact filters after discovering affected tests. Expected shape:

cd apps/platform && ./vendor/bin/sail artisan test --filter=EvidenceSnapshotResourceTest
cd apps/platform && ./vendor/bin/sail artisan test --filter=BaselineSnapshot
cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec335RestoreRunDetailProductizationTest
cd apps/platform && ./vendor/bin/sail artisan test --filter=ReviewPackResourceTest
cd apps/platform && ./vendor/bin/sail artisan test --filter=StoredReportDetailPresentationTest
cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec397ReceiptPageReductionSmokeTest
cd apps/platform && ./vendor/bin/sail pint --test
git diff --check

If existing browser tests are extended instead of adding Spec397ReceiptPageReductionSmokeTest, the implementation report must name the exact browser files and paths.

Rollout / Deployment Considerations

• Staging: Required validation gate before production for rendered UI changes.
• Production: No schema/env/queue/scheduler/storage change expected.
• Migrations: None.
• Env vars: None.
• Queues/workers: None.
• Storage/volumes: None.
• Assets: No new assets expected. If assets are registered, include cd apps/platform && php artisan filament:assets in deployment.
• Feature flags: Not expected. No compatibility toggle for old receipt layouts.

Implementation Phases

Phase 1 - Discovery And Baseline Proof

Verify current default-visible receipt content and identify exact render files/actions for each target page. Record raw technical/default-visible issues and current tests/browser fixtures.

Phase 2 - Evidence Snapshot Receipt Reduction

Reduce Evidence Snapshot default view, demote technical evidence/source/detector/detail blocks, preserve authorized internal detail, and update focused tests.

Phase 3 - Baseline Snapshot Receipt Reduction

Reduce Baseline Snapshot default view, cap or demote governed-subject/coverage/payload/fidelity detail, preserve authorized internal detail, and update focused tests.

Phase 4 - Restore / Review Pack / Stored Report Receipt Reduction

Demote OperationRun proof/raw payload/internal artifact links from Restore Run, Review Pack receipt sections, and Stored Report receipt metadata. Preserve report content behavior where the page is truly a Report Page rather than a receipt.

Phase 5 - Browser Proof, Human Sanity, Close-Out

Run focused browser proof for every changed receipt surface, capture screenshots or textual browser evidence, perform human product sanity, update coverage registry artifacts, update implementation report, and record Product Surface exceptions or none.

Stop Conditions

Stop implementation and update spec/plan before continuing if:

• A new table, migration, persisted receipt state, enum/status family, registry, resolver, presenter framework, or Technical Annex framework appears necessary.
• A Product Surface exception is needed.
• The implementation would change report generation, evidence generation, baseline capture, restore execution, queue behavior, or Graph calls.
• A customer-safe path requires new authorization semantics.
• Browser proof requires broad fixture infrastructure beyond a focused Spec 397 path.

Implementation Report Requirements

During implementation, create specs/397-receipt-page-reduction/implementation-report.md with:

• Active spec and selected slice.
• Branch, HEAD, and dirty state.
• Files changed.
• Runtime UI files changed: yes.
• UI impact and Product Surface exceptions or none.
• Browser proof with routes, interactions, console/network result, and screenshots or equivalent evidence.
• Human Product Sanity result.
• Visible complexity outcome.
• No-legacy confirmation.
• Completed-spec rewrite assertion.
• Livewire v4 compliance.
• Provider registration location: apps/platform/bootstrap/providers.php, unchanged unless implementation proves otherwise.
• Global search posture for each changed resource.
• Destructive/high-impact actions touched and confirmation/authorization/audit handling.
• Asset strategy and whether filament:assets is required.
• Tests/checks run and results.
• Deployment impact for env vars, migrations, queues, scheduler, storage, and assets.
• Unrelated failures and follow-up candidates.