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

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)

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)

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.