TenantAtlas/specs/192-record-header-discipline/quickstart.md

Quickstart: Record Page Header Discipline & Contextual Navigation

Goal

Bring the in-scope record/detail/edit surfaces under one bounded header-action discipline: one clear next step on standard pages, contextual navigation near related content and outside the header, grouped secondary actions for non-navigation actions, separated danger, and one explicit workflow-heavy exception.

Implementation Sequence

1. Confirm the in-scope inventory in code.

   • Map each in-scope page class to the Spec 192 classification.
   • Confirm which pages are remediation-required, minor-alignment only, compliant reference, or workflow-heavy special type.

2. Remediate the standard pages first.

   • Refactor ViewBaselineProfile to expose only one visible primary action based on snapshot readiness.
   • Refactor ViewEvidenceSnapshot so run and review-pack navigation move to contextual placement outside the header and Expire snapshot remains separated.
   • Refactor ViewFindingException so navigation moves to contextual placement outside the header, Renew exception may remain primary, and Revoke exception stays isolated.
   • Refactor ViewTenantReview so only one lifecycle action is primary, navigation becomes contextual outside the header, and infrequent lifecycle actions stay grouped.
   • Refactor EditTenant so the header stops competing with the edit task and view/onboarding links move into contextual tenant-meta placement.

3. Tighten the explicit exception and minor-alignment pages.

   • Audit ViewTenant as the workflow-heavy special type and order its grouped actions deliberately.
   • Review ViewProviderConnection and ViewFinding for minor alignment only, and change them only if the audit proves real header noise.
   • Confirm that ViewBaselineSnapshot, ViewBackupSet, ViewReviewPack, ViewAlertDestination, ViewPolicyVersion, and ViewWorkspace remain valid references.

4. Add regression protection.

   • Extend the existing action-surface guard or exemption mapping with Spec 192 expectations.
   • Add focused Livewire/Pest page tests for remediated surfaces.
   • Add one browser smoke suite covering the remediated pages, the explicit special-type exception, and a no-regression baseline over the compliant reference set.
   • Add explicit regression checks that this feature does not force Spec 133 body-layout rollout and does not expand confirmation depth, reason capture, or provider-dispatch semantics.

5. Run focused verification.

   • Run the guard tests, the remediated page tests, the browser smoke suite, and formatting through Sail.

Suggested Source Files

• apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php
• apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
• apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php
• apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
• apps/platform/app/Filament/Resources/TenantResource/Pages/EditTenant.php
• apps/platform/app/Filament/Resources/TenantResource/Pages/ViewTenant.php
• apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/ViewProviderConnection.php
• apps/platform/app/Filament/Resources/FindingResource/Pages/ViewFinding.php
• apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceValidator.php
• apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php

Suggested Test Files

• apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php
• apps/platform/tests/Feature/Guards/ActionSurfaceValidatorTest.php
• apps/platform/tests/Feature/Guards/FilamentTableStandardsGuardTest.php
• apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php
• apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php
• apps/platform/tests/Feature/Filament/TenantViewHeaderUiEnforcementTest.php
• apps/platform/tests/Browser/Spec174EvidenceFreshnessPublicationTrustSmokeTest.php
• apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php
• apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php

Minimum Verification Commands

Run all commands through Sail from apps/platform.

cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceValidatorTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantViewHeaderUiEnforcementTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Manual Acceptance Checklist

1. Open each remediated standard page and confirm the header shows at most one visible primary action.
2. Confirm pure navigation is no longer presented as an equal-weight peer to the primary mutation on remediated pages and now lives in contextual placement outside the header.
3. Confirm rare administrative actions live in a grouped secondary structure instead of a flat peer row.
4. Confirm destructive or governance-sensitive actions remain visually separated and keep confirmation.
5. Confirm the tenant edit page still reads as an edit surface first.
6. Confirm the tenant admin resource view stays grouped and ordered as an explicit workflow-heavy exception.
7. Confirm compliant reference pages do not regress or receive unnecessary cosmetic churn.
8. Confirm browser smoke checks show no JavaScript errors on the remediated pages, the workflow-heavy exception page, and the compliant reference baseline pages.

Deployment Notes

• No migration is expected.
• No new provider registration is expected; Laravel 11+ provider registration remains in bootstrap/providers.php.
• No new asset registration is expected. Existing deploy handling of cd apps/platform && php artisan filament:assets remains sufficient.