# Implementation Plan: Record Page Header Discipline & Contextual Navigation **Branch**: `192-record-header-discipline` | **Date**: 2026-04-11 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/192-record-header-discipline/spec.md` **Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/192-record-header-discipline/spec.md` **Note**: This plan keeps the work inside the existing Filament v5 / Livewire v4 resource pages, existing related-navigation helpers, and the existing action-surface guard infrastructure. It explicitly avoids introducing a new header-action framework. ## Summary Codify one bounded header-discipline contract for classic record/detail/edit pages in the admin panel. Reuse existing Filament header actions, `ActionGroup`, `UiEnforcement`, and `RelatedNavigationResolver` patterns to inventory all in-scope surfaces, remediate the five standard pages that currently have noisy headers, preserve already-clean reference pages, explicitly document `ViewTenant` as a workflow-heavy special type, and extend the existing action-surface and browser regression layers so new header sprawl does not re-enter the repo. ## Technical Context **Language/Version**: PHP 8.4.15 **Primary Dependencies**: Laravel 12, Filament v5, Livewire v4, Pest v4, Tailwind CSS v4, existing `UiEnforcement`, `RelatedNavigationResolver`, `ActionSurfaceValidator`, and page-local Filament action builders **Storage**: PostgreSQL through existing workspace-owned and tenant-owned resource models; no schema change planned **Testing**: Pest feature tests, existing guard tests, and browser smoke tests run through Laravel Sail **Target Platform**: Laravel monolith web application under `apps/platform`, with workspace/admin routes under `/admin`, tenant-context routes under `/admin/t/{tenant}/...`, and no panel expansion planned **Project Type**: web application **Performance Goals**: Preserve the 5-second scan rule on record pages, keep all affected pages DB-only at render time, avoid new polling or asset work, and prevent header cleanup from adding extra query churn or remote calls **Constraints**: No new action framework, no new persistence, no route or panel changes, no authorization-plane changes, no new status language, no silent special-type exemptions, and no expansion of Spec 133 body-composition requirements beyond current scope **Scale/Scope**: 14 in-scope record/detail/edit surfaces, 5 remediation-required standard pages, 1 explicit workflow-heavy special-type exception, 2 minor-alignment audits, 6 compliant/no-op reference pages, and focused guard plus feature plus browser regression coverage ## Constitution Check *GATE: Passed before Phase 0 research. Re-checked after Phase 1 design and still passing.* | Principle | Pre-Research | Post-Design | Notes | |-----------|--------------|-------------|-------| | Inventory-first / snapshots-second | PASS | PASS | The feature does not alter inventory or snapshot truth; it only reorganizes page headers. | | Read/write separation | PASS | PASS | Existing mutations keep their current confirmation, audit, and test behavior. No new writes are introduced. | | Graph contract path | N/A | N/A | No new Microsoft Graph call path or contract-registry change is planned. | | Deterministic capabilities | PASS | PASS | Capability checks remain in canonical registries and `UiEnforcement`; regrouping actions does not change entitlement logic. | | Workspace + tenant isolation | PASS | PASS | Existing route scopes and related-navigation availability rules remain authoritative. | | RBAC-UX authorization semantics | PASS | PASS | Non-members remain `404`, in-scope capability denial remains `403`, and server-side authorization stays unchanged. | | Run observability / Ops-UX | PASS | PASS | Underlying long-running actions such as capture, compare, refresh, and verification keep their existing `OperationRun` semantics. | | Data minimization | PASS | PASS | No new persistence, caches, or header-state artifacts are introduced. | | Proportionality / anti-bloat | PASS | PASS | The work stays inside existing pages and guard infrastructure instead of creating a new framework. | | UI semantics / few layers | PASS | PASS | The feature relies on direct action placement and classification rather than a new presenter or semantic layer. | | Filament-native UI | PASS | PASS | Native Filament header actions and `ActionGroup` remain the implementation path. | | Surface taxonomy / HDR-001 | PASS | PASS | The plan explicitly classifies every in-scope page and documents the one workflow-heavy special type. | | Filament v5 / Livewire v4 compliance | PASS | PASS | All touched pages remain inside the existing Filament v5 + Livewire v4 stack. | | Provider registration location | PASS | PASS | No provider change is needed; Laravel 11+ provider registration remains in `bootstrap/providers.php`. | | Global search hard rule | PASS | PASS | No new globally searchable resource is introduced; touched resources already have View/Edit pages where needed. | | Destructive action safety | PASS | PASS | Existing destructive or governance-changing actions keep `->requiresConfirmation()` and stay authorization-gated. | | Asset strategy | PASS | PASS | No new assets or lazy-load registrations are needed; existing deploy handling of `cd apps/platform && php artisan filament:assets` remains unchanged. | ## Filament-Specific Compliance Notes - **Livewire v4.0+ compliance**: The plan remains on Filament v5 + Livewire v4 and introduces no legacy or mixed-version API usage. - **Provider registration location**: No panel or provider changes are required; Laravel 11+ panel providers remain registered in `bootstrap/providers.php`. - **Global search**: The feature does not add a new globally searchable resource. Touched resources continue to satisfy the Filament hard rule because they already have View and/or Edit pages; search behavior is otherwise unchanged. - **Destructive actions**: `Expire snapshot`, `Revoke exception`, `Archive review`, tenant lifecycle actions, backup lifecycle actions, and provider credential danger actions remain routed through `Action::make(...)->action(...)` with `->requiresConfirmation()` and existing authorization. - **Asset strategy**: No new global or on-demand asset registration is planned. Existing deployment handling of `cd apps/platform && php artisan filament:assets` remains sufficient. - **Testing plan**: Extend the existing action-surface guard layer, add focused Livewire/Pest tests for the remediated pages and the explicit special type, and add a browser smoke suite that proves visible hierarchy on remediated headers. ## Phase 0 Research Research outcomes are captured in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/192-record-header-discipline/research.md`. Key decisions: - Reuse existing page-local action builders, `UiEnforcement`, `ActionGroup`, and `RelatedNavigationResolver` instead of introducing a header-action framework. - Move pure navigation to contextual placement outside the header instead of equal-weight header placement. - Treat `ViewTenant` as an explicit workflow-heavy special-type exception rather than a standard record page. - Preserve already-clean pages as reference patterns instead of cosmetically normalizing them. - Build regression protection on top of the existing `ActionSurfaceValidator`, focused page tests, and browser smoke patterns. ## Phase 1 Design Design artifacts are created under `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/192-record-header-discipline/`: - `research.md`: decisions and rejected alternatives for bounded header discipline - `data-model.md`: derived header-surface inventory, render contract, and regression expectation models - `contracts/record-header-discipline.logical.openapi.yaml`: internal logical contract for standard-page headers, the special-type exception, and regression expectations - `quickstart.md`: implementation and verification sequence for the feature Design highlights: - Keep all classification and render rules derived, not persisted. - Represent each in-scope surface through one explicit inventory entry and one explicit regression expectation. - Keep state-sensitive primary-action decisions local to the existing pages rather than moving them into a shared runtime resolver. - Treat `ViewTenant` as the only explicit special type and require an exception reason in the regression layer. - Extend the existing guard system rather than creating a new validation framework. ## Phase 1 — Agent Context Update Planned command: - `.specify/scripts/bash/update-agent-context.sh copilot` This feature does not introduce a new technology stack, but the required agent-context refresh still runs to keep the planning workflow complete. ## Project Structure ### Documentation (this feature) ```text specs/192-record-header-discipline/ ├── plan.md ├── research.md ├── data-model.md ├── quickstart.md ├── spec.md ├── contracts/ │ └── record-header-discipline.logical.openapi.yaml └── checklists/ └── requirements.md ``` ### Source Code (repository root) ```text apps/platform/ ├── app/ │ ├── Filament/ │ │ └── Resources/ │ │ ├── BaselineProfileResource.php # MODIFY │ │ ├── BaselineProfileResource/ │ │ │ └── Pages/ │ │ │ └── ViewBaselineProfile.php # MODIFY │ │ ├── EvidenceSnapshotResource.php # MODIFY │ │ ├── EvidenceSnapshotResource/ │ │ │ └── Pages/ │ │ │ └── ViewEvidenceSnapshot.php # MODIFY │ │ ├── FindingExceptionResource.php # MODIFY │ │ ├── FindingExceptionResource/ │ │ │ └── Pages/ │ │ │ └── ViewFindingException.php # MODIFY │ │ ├── TenantReviewResource.php # MODIFY │ │ ├── TenantReviewResource/ │ │ │ └── Pages/ │ │ │ └── ViewTenantReview.php # MODIFY │ │ ├── TenantResource.php # MODIFY │ │ ├── TenantResource/ │ │ │ └── Pages/ │ │ │ ├── EditTenant.php # MODIFY │ │ │ └── ViewTenant.php # MODIFY (special type ordering only) │ │ ├── ProviderConnectionResource/ │ │ │ └── Pages/ │ │ │ └── ViewProviderConnection.php # AUDIT / possible minor alignment │ │ ├── FindingResource/ │ │ │ └── Pages/ │ │ │ └── ViewFinding.php # AUDIT / possible minor alignment │ │ ├── BackupSetResource/ │ │ │ └── Pages/ │ │ │ └── ViewBackupSet.php # REFERENCE only │ │ ├── BaselineSnapshotResource/ │ │ │ └── Pages/ │ │ │ └── ViewBaselineSnapshot.php # REFERENCE only │ │ ├── ReviewPackResource/ │ │ │ └── Pages/ │ │ │ └── ViewReviewPack.php # REFERENCE only │ │ ├── AlertDestinationResource/ │ │ │ └── Pages/ │ │ │ └── ViewAlertDestination.php # REFERENCE only │ │ ├── PolicyVersionResource/ │ │ │ └── Pages/ │ │ │ └── ViewPolicyVersion.php # REFERENCE only │ │ └── Workspaces/ │ │ └── Pages/ │ │ └── ViewWorkspace.php # REFERENCE only │ ├── Support/ │ │ ├── Navigation/ │ │ │ └── RelatedNavigationResolver.php # REUSE │ │ ├── Rbac/ │ │ │ └── UiEnforcement.php # REUSE │ │ └── Ui/ │ │ └── ActionSurface/ │ │ ├── ActionSurfaceValidator.php # MODIFY │ │ ├── ActionSurfaceExemptions.php # MODIFY │ │ ├── ActionSurfaceProfileDefinition.php # POSSIBLE MODIFY │ │ └── Enums/ │ │ └── ActionSurfaceProfile.php # POSSIBLE MODIFY ├── resources/ │ └── views/ │ └── filament/ │ └── infolists/ │ └── entries/ │ └── tenant-review-summary.blade.php # MODIFY └── tests/ ├── Feature/ │ ├── Guards/ │ │ ├── ActionSurfaceContractTest.php # MODIFY │ │ ├── ActionSurfaceValidatorTest.php # MODIFY │ │ └── Spec192RecordPageHeaderDisciplineGuardTest.php # NEW │ └── Filament/ │ ├── BaselineProfileCaptureStartSurfaceTest.php # MODIFY or REUSE │ ├── BaselineProfileCompareStartSurfaceTest.php # MODIFY or REUSE │ ├── TenantViewHeaderUiEnforcementTest.php # MODIFY or REUSE │ ├── FindingExceptionHeaderDisciplineTest.php # NEW │ ├── TenantReviewHeaderDisciplineTest.php # NEW │ └── EditTenantHeaderDisciplineTest.php # NEW └── Browser/ ├── Spec174EvidenceFreshnessPublicationTrustSmokeTest.php # REUSE for patterns ├── Spec190BaselineCompareMatrixSmokeTest.php # REUSE for patterns └── Spec192RecordPageHeaderDisciplineSmokeTest.php # NEW ``` Additional reused test files referenced in `tasks.md`, such as `EvidenceSnapshotResourceTest.php`, `TenantReviewUiContractTest.php`, and RBAC regression suites, remain in scope even when they are not repeated in the summary tree above. **Structure Decision**: Keep the work entirely inside the existing Laravel/Filament monolith under `apps/platform`. Modify only the affected resource classes, page classes, the tenant-review contextual Blade partial, the existing action-surface validation layer, and focused tests. Do not create a new support framework beyond the minimum needed to extend the existing guard patterns. ## Complexity Tracking | Violation | Why Needed | Simpler Alternative Rejected Because | |-----------|------------|-------------------------------------| | Cross-page header taxonomy and explicit exception catalog (BLOAT-001 trigger) | The feature must distinguish standard record pages, reference pages, minor-alignment pages, and the single workflow-heavy exception in a way CI can validate. | Pure page-local cleanup would reduce immediate noise but would not prevent future drift or document why `ViewTenant` is intentionally different. | ## Proportionality Review - **Current operator problem**: Several classic record/detail/edit pages still present navigation, routine mutations, and danger as flat peers, slowing interpretation and weakening action hierarchy. - **Existing structure is insufficient because**: The constitution now carries HDR-001, but the repo lacks a concrete inventory, a bounded classification model, and a regression hook that can distinguish standard pages from an allowed special type. - **Narrowest correct implementation**: Keep all changes inside existing page classes and the existing action-surface validation layer, classify only the explicitly named pages, remediate only the pages that need it, and document exactly one special-type exception. - **Ownership cost created**: A small amount of guard configuration, a few focused page tests, one smoke suite, and ongoing review discipline for future record pages. - **Alternative intentionally rejected**: A new header-action framework, resolver, or interface layer was rejected because the current repo already has enough primitives to implement the discipline directly. - **Release truth**: current-release operator clarity and action-surface discipline ## Implementation Strategy ### Phase A — Codify the inventory and the regression contract Goal: turn the spec inventory into an enforceable project-level contract without introducing a new framework. Changes: - Extend the existing action-surface validation and exemption layer with Spec 192 surface expectations. - Encode the explicit workflow-heavy exception for `ViewTenant`. - Record which pages are remediation-required, which are audit-only, and which are compliant references. Tests: - Add `Spec192RecordPageHeaderDisciplineGuardTest.php`. - Extend `ActionSurfaceContractTest.php` and `ActionSurfaceValidatorTest.php` with Spec 192 expectations. ### Phase B — Remediate the highest-noise standard record pages Goal: implement the clearest header-discipline wins first on the pages with the most obvious peer-action sprawl. Changes: - Refactor `ViewBaselineProfile` to expose one state-sensitive primary action and move navigation plus secondary actions out of the flat primary lane. - Refactor `ViewTenantReview` so only one lifecycle action stays primary and the rest become grouped or contextual. - Keep all existing action semantics, notifications, `OperationRun` links, confirmations, and authorization unchanged. Tests: - Reuse or extend existing baseline profile feature tests. - Add runtime assertions for visible primary action count, grouped secondary placement, and preserved authorization behavior. ### Phase C — Remediate the remaining standard record and edit surfaces Goal: finish the standard-page cleanup with lower-complexity but still important record surfaces. Changes: - Refactor `ViewEvidenceSnapshot` to keep one central next step and separate lifecycle danger from related navigation. - Refactor `ViewFindingException` so navigation becomes secondary while governance lifecycle remains clear. - Refactor `EditTenant` so the header no longer competes with the edit task. Tests: - Add focused feature tests for `EvidenceSnapshot`, `FindingException`, and `EditTenant`. - Preserve existing capability gating and confirmation behavior in all assertions. ### Phase D — Tighten the explicit exception and audit-only pages Goal: make the special type explicit and ensure audit-only pages stay calm. Changes: - Move pure navigation on `ViewTenant` into contextual placement outside the header and reorder grouped header actions by explicit buckets: external links, verification, setup, and lifecycle. - Audit `ViewProviderConnection` and `ViewFinding` for minor alignment only and change them only if they still present real header-noise issues. - Confirm `ViewBaselineSnapshot`, `ViewBackupSet`, `ViewReviewPack`, `ViewAlertDestination`, `ViewPolicyVersion`, and `ViewWorkspace` remain compliant references. Tests: - Extend `TenantViewHeaderUiEnforcementTest.php` or add a dedicated special-type feature test. - Cover the explicit exception reason in the guard layer. ### Phase E — Browser verification and final regression protection Goal: prove the new hierarchy in a real browser and keep CI from accepting future header sprawl. Changes: - Add `Spec192RecordPageHeaderDisciplineSmokeTest.php` covering the remediated pages, the workflow-heavy exception, and a no-regression baseline over the compliant reference set. - Ensure the guard layer fails on multiple competing primaries, missing grouped secondary structure where required, or silent exceptions. - Re-run formatting and the focused Sail test pack. Tests: - Browser smoke coverage for visible hierarchy and no JavaScript errors. - Focused guard and page-level tests for each remediated or exceptional surface. ## Risk Assessment | Risk | Impact | Likelihood | Mitigation | |------|--------|------------|------------| | Cleanup grows into a new action framework | Medium | Low | Keep all changes inside existing page classes and the current action-surface guard layer. | | `More` groups become junk drawers | Medium | Medium | Treat internal order as part of the contract and test it on the special-type and remediated pages. | | State-driven primary action is chosen incorrectly | High | Medium | Add focused runtime assertions for BaselineProfile and TenantReview state transitions. | | `ViewTenant` silently bypasses the standard-page rule | Medium | Medium | Encode the special-type exception in the guard layer with an explicit reason and browser coverage. | | Reference pages get unnecessary churn | Medium | Low | Keep a documented compliant-reference set and use it as a regression baseline. | ## Test Strategy - Extend `ActionSurfaceContractTest.php` and `ActionSurfaceValidatorTest.php` so Spec 192 becomes an explicit CI-enforced rule rather than a manual review note. - Add `Spec192RecordPageHeaderDisciplineGuardTest.php` to validate remediation-required pages, the explicit special type, and any whitelisted references. - Reuse existing baseline profile tests where possible and add focused feature tests for `EvidenceSnapshot`, `FindingException`, `TenantReview`, and `EditTenant` where no dedicated header-discipline tests exist yet. - Extend `TenantViewHeaderUiEnforcementTest.php` or add a dedicated special-type test so grouped ordering and exception semantics stay covered. - Add `Spec192RecordPageHeaderDisciplineSmokeTest.php` using the existing browser-smoke infrastructure and fixture traits already used by Spec 174 and Spec 190, including a no-regression pass over the compliant reference set. - Add explicit regression assertions that this feature does not force Spec 133 body-layout rollout and does not expand confirmation depth, reason capture, or provider-dispatch semantics. - Run the focused Sail verification commands from `quickstart.md`, then run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`. ## Constitution Check (Post-Design) Re-check result: PASS. - Livewire v4.0+ compliance remains intact because all touched surfaces stay inside the existing Filament v5 + Livewire v4 stack. - Provider registration remains unchanged in `bootstrap/providers.php`. - No new globally searchable resource is introduced; touched resources already have View and/or Edit pages where relevant. - Destructive actions remain confirmation-gated and authorization-gated. - No new asset strategy is required; deploy handling of `cd apps/platform && php artisan filament:assets` remains unchanged. - The testing plan covers the remediated standard pages, the explicit workflow-heavy exception, and the project-level regression guard for future record-page header drift.