ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
72ddc18743
TenantAtlas/specs/192-record-header-discipline/tasks.md
Ahmed Darrazi 72ddc18743 feat: implement spec 192 header discipline 
- land the spec 192 resource, guard, browser smoke, and documentation changes
- add unhandled rejection request correlation for 419 diagnostics
- disable panel-wide database notification polling and cover it with focused tests
2026-04-11 23:09:42 +02:00

24 KiB
Raw Blame History

Tasks: Record Page Header Discipline & Contextual Navigation

Input: Design documents from /specs/192-record-header-discipline/
Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md, contracts/record-header-discipline.logical.openapi.yaml

Tests: Tests are REQUIRED. Extend the existing guard layer, focused Pest feature coverage, and browser smoke coverage for the affected Filament pages. Operations: This feature reuses existing action semantics only. No new OperationRun type, summary-count contract, or notification channel should be introduced. RBAC: Existing workspace and tenant authorization semantics remain authoritative. Tasks must preserve non-member 404, member-without-capability 403, central capability registry usage, and per-action UiEnforcement. Filament v5 / Livewire v4: All touched surfaces remain inside the existing Filament v5 + Livewire v4 stack. Provider Registration: No panel or provider changes are planned; Laravel 11+ provider registration remains in bootstrap/providers.php. Global Search: Touched resources already have their current View/Edit coverage and search settings; no new globally searchable resource is introduced. Destructive Actions: Existing destructive or governance-changing actions must remain ->requiresConfirmation() and authorization-gated after regrouping. Asset Strategy: No new asset registration is planned; existing deployment handling of cd apps/platform && php artisan filament:assets remains unchanged.

Organization: Tasks are grouped by user story so each story can be implemented and verified independently, while acknowledging that some stories touch the same page files and are therefore safer to land sequentially.

Phase 1: Setup (Acceptance Seams)

Purpose: Create the focused guard, feature, and browser test entry points used by the implementation work.

  • T001 Create the Spec 192 guard entry point in apps/platform/tests/Feature/Guards/Spec192RecordPageHeaderDisciplineGuardTest.php
  • T002 [P] Create the focused page-test entry points in apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php, apps/platform/tests/Feature/Filament/TenantReviewHeaderDisciplineTest.php, and apps/platform/tests/Feature/Filament/EditTenantHeaderDisciplineTest.php
  • T003 [P] Create the browser smoke entry point and compliant-reference baseline cases in apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php

Checkpoint: Focused verification entry points exist for guard, page-level, and browser-level work.

Phase 2: Foundational (Blocking Regression Contract)

Purpose: Encode the surface inventory, classification, and explicit exception model before touching page behavior.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

  • T004 Encode the Spec 192 surface inventory, classifications, and explicit ViewTenant exception metadata in apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php
  • T005 [P] Extend the record-page header-discipline validation rules for standard pages and the workflow-heavy special type in apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceValidator.php
  • T006 [P] Add foundational guard assertions for classified surfaces, explicit exceptions, and compliant references in apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php, apps/platform/tests/Feature/Guards/ActionSurfaceValidatorTest.php, and apps/platform/tests/Feature/Guards/Spec192RecordPageHeaderDisciplineGuardTest.php

Checkpoint: The repo can fail CI when a standard record page regresses into multiple competing primaries or when a special-type exception is left undocumented.

Phase 3: User Story 1 - See One Next Step On Standard Record Pages (Priority: P1) 🎯 MVP

Goal: Standard record/detail/edit pages expose one clear visible next step instead of a flat row of competing peer actions.

Independent Test: Open each remediation-required standard page and verify that it renders at most one visible primary header action while preserving existing authorization and action semantics.

Tests for User Story 1

  • T007 [P] [US1] Extend state-sensitive primary-action assertions for baseline profile detail in apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php and apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php
  • T008 [P] [US1] Add one-primary-action assertions for evidence snapshot and finding exception detail in apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php and apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php
  • T009 [P] [US1] Add one-primary-action assertions for tenant review and tenant edit surfaces in apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, apps/platform/tests/Feature/Filament/TenantReviewHeaderDisciplineTest.php, and apps/platform/tests/Feature/Filament/EditTenantHeaderDisciplineTest.php

Implementation for User Story 1

  • T010 [US1] Refactor state-sensitive primary-action selection and grouped secondaries in apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php
  • T011 [US1] Refactor evidence snapshot header hierarchy so only one visible next-step action remains in apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
  • T012 [US1] Refactor finding exception header hierarchy so renewal can be primary and revocation stays separated in apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php
  • T013 [US1] Refactor tenant review header hierarchy to promote only one lifecycle primary action in apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
  • T014 [US1] Refactor the tenant edit header so it stops competing with the form primary affordance in apps/platform/app/Filament/Resources/TenantResource/Pages/EditTenant.php
  • T015 [US1] Run focused primary-action verification in apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php, apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php, apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php, apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, apps/platform/tests/Feature/Filament/TenantReviewHeaderDisciplineTest.php, and apps/platform/tests/Feature/Filament/EditTenantHeaderDisciplineTest.php

Checkpoint: The five remediation-required standard pages expose no more than one visible primary header action.

Phase 4: User Story 2 - Follow Contextual Navigation Near The Relevant Content (Priority: P1)

Goal: Pure navigation leaves the flat primary header lane and appears nearer to the summary, related context, or grouped secondary actions it belongs to.

Independent Test: Open remediated pages with related destinations and verify that navigation is no longer presented as an equal-weight primary peer to the main mutation.

Tests for User Story 2

  • T016 [P] [US2] Add contextual-navigation assertions for baseline profile and evidence snapshot detail in apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php, apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, and apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php
  • T017 [P] [US2] Add contextual-navigation assertions for finding exception, tenant review, and tenant edit surfaces in apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php, apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, apps/platform/tests/Feature/Filament/TenantReviewHeaderDisciplineTest.php, and apps/platform/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php

Implementation for User Story 2

  • T018 [US2] Move active snapshot and compare-matrix navigation into contextual baseline-profile sections in apps/platform/app/Filament/Resources/BaselineProfileResource.php and apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php
  • T019 [US2] Move operation and review-pack navigation into evidence snapshot summary or related-context sections in apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php and apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
  • T020 [US2] Move finding and approval-queue navigation into finding-exception related-context placement in apps/platform/app/Filament/Resources/FindingExceptionResource.php and apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php
  • T021 [US2] Move operation, executive-pack, and evidence navigation into tenant-review contextual summary surfaces in apps/platform/app/Filament/Resources/TenantReviewResource.php, apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php, and apps/platform/resources/views/filament/infolists/entries/tenant-review-summary.blade.php
  • T022 [US2] Move tenant edit view and onboarding links into contextual tenant-meta placement outside the header in apps/platform/app/Filament/Resources/TenantResource.php and apps/platform/app/Filament/Resources/TenantResource/Pages/EditTenant.php
  • T023 [US2] Run focused contextual-navigation verification in apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php, apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php, apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, apps/platform/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php, and apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php

Checkpoint: Related navigation has left the flat primary header lane on the remediated standard pages.

Phase 5: User Story 3 - Keep Rare And Dangerous Actions Available Without Clutter (Priority: P2)

Goal: Rare administrative actions and destructive or governance-sensitive actions remain available without visually competing with routine work.

Independent Test: Open pages with grouped secondaries or danger actions and verify that rare actions live in grouped structures while danger stays visibly separated and confirmation-gated.

Tests for User Story 3

  • T024 [P] [US3] Extend grouped-secondary and danger-separation assertions for baseline profile, tenant review, and tenant edit in apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php, apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, apps/platform/tests/Feature/Rbac/EditTenantArchiveUiEnforcementTest.php, and apps/platform/tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php
  • T025 [P] [US3] Add grouped-secondary and danger assertions for evidence snapshot, finding exception, provider connection, and finding detail in apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php, apps/platform/tests/Feature/ProviderConnections/ProviderConnectionHealthCheckStartSurfaceTest.php, apps/platform/tests/Feature/ProviderConnections/DisabledActionsTooltipTest.php, apps/platform/tests/Feature/Filament/FindingViewRbacEvidenceTest.php, and apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php

Implementation for User Story 3

  • T026 [US3] Group non-primary baseline profile actions into deliberate secondary and admin buckets in apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php
  • T027 [US3] Separate lifecycle danger from safe secondaries on evidence snapshot and finding exception detail in apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php and apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php
  • T028 [US3] Group tenant review lifecycle and export actions while keeping archive in a danger bucket in apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
  • T029 [US3] Keep tenant edit lifecycle actions secondary and aligned with tenant lifecycle naming in apps/platform/app/Filament/Resources/TenantResource/Pages/EditTenant.php and apps/platform/app/Filament/Resources/TenantResource.php
  • T030 [US3] Audit provider connection and finding detail headers for real minor-alignment issues in apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/ViewProviderConnection.php and apps/platform/app/Filament/Resources/FindingResource/Pages/ViewFinding.php, and only apply cleanup if the audit proves current header noise
  • T031 [US3] Run focused grouped-secondary and danger verification in apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php, apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, apps/platform/tests/Feature/Rbac/EditTenantArchiveUiEnforcementTest.php, apps/platform/tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php, apps/platform/tests/Feature/ProviderConnections/ProviderConnectionHealthCheckStartSurfaceTest.php, apps/platform/tests/Feature/ProviderConnections/DisabledActionsTooltipTest.php, apps/platform/tests/Feature/Filament/FindingViewRbacEvidenceTest.php, and apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php

Checkpoint: Rare and dangerous actions remain available, but no longer clutter standard record-page headers.

Phase 6: User Story 4 - Treat Workflow-Heavy Pages As Explicit Exceptions (Priority: P3)

Goal: Workflow-heavy pages remain disciplined through explicit exception handling instead of silent non-conformance.

Independent Test: Review ViewTenant and verify that it is explicitly marked as a special type, internally ordered, and not silently exempted from the record-page rule.

Tests for User Story 4

  • T032 [P] [US4] Extend workflow-heavy exception assertions for tenant detail in apps/platform/tests/Feature/Filament/TenantViewHeaderUiEnforcementTest.php, apps/platform/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php, and apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php
  • T033 [P] [US4] Extend guard assertions so ViewTenant requires an explicit special-type reason in apps/platform/tests/Feature/Guards/Spec192RecordPageHeaderDisciplineGuardTest.php and apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php

Implementation for User Story 4

  • T034 [US4] Move pure tenant-detail navigation into contextual placement outside the header and reorder grouped header actions into explicit external-link, verification/setup, and lifecycle buckets in apps/platform/app/Filament/Resources/TenantResource/Pages/ViewTenant.php
  • T035 [US4] Encode the workflow-heavy special-type reason and max-primary-action rule for tenant detail in apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php and apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceValidator.php
  • T036 [US4] Run focused special-type verification in apps/platform/tests/Feature/Filament/TenantViewHeaderUiEnforcementTest.php, apps/platform/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php, apps/platform/tests/Feature/Guards/Spec192RecordPageHeaderDisciplineGuardTest.php, apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php, and apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php

Checkpoint: The workflow-heavy exception is explicit, tested, and structurally disciplined.

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Confirm compliant references, align operator copy, and run the focused verification pack.

  • T037 [P] Audit and explicitly confirm compliant reference pages remain no-op in apps/platform/app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php, apps/platform/app/Filament/Resources/BackupSetResource/Pages/ViewBackupSet.php, apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php, apps/platform/app/Filament/Resources/AlertDestinationResource/Pages/ViewAlertDestination.php, apps/platform/app/Filament/Resources/PolicyVersionResource/Pages/ViewPolicyVersion.php, and apps/platform/app/Filament/Resources/Workspaces/Pages/ViewWorkspace.php
  • T038 [P] Align Verb + Object labels and grouped-action copy in 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, and apps/platform/app/Filament/Resources/FindingResource/Pages/ViewFinding.php
  • T039 [P] Add or update compliant-reference and no-regression assertions in apps/platform/tests/Feature/Guards/Spec192RecordPageHeaderDisciplineGuardTest.php and apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php
  • T040 [P] Extend apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php with no-regression coverage for the compliant reference set named in Spec 192
  • T041 [P] Add explicit no-body-layout-expansion assertions for the remediated and reference views in apps/platform/tests/Feature/Guards/Spec192RecordPageHeaderDisciplineGuardTest.php and apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php
  • T042 [P] Add explicit no-governance-friction-expansion assertions that regrouping preserves confirmation depth and action semantics in apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php, apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, and apps/platform/tests/Feature/Rbac/EditTenantArchiveUiEnforcementTest.php
  • T043 [P] Run the focused verification commands documented in specs/192-record-header-discipline/quickstart.md
  • T044 [P] Run formatting on touched Filament page and guard files from apps/platform/ via ./vendor/bin/sail bin pint --dirty --format agent

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies; can start immediately.
  • Foundational (Phase 2): Depends on Setup completion; blocks all user-story work.
  • User Story 1 (Phase 3): Depends on Foundational completion and is the MVP slice.
  • User Story 2 (Phase 4): Depends on Foundational completion. It is independently testable, but it touches several of the same page files as US1, so it is safer to land after US1 unless work is split carefully.
  • User Story 3 (Phase 5): Depends on Foundational completion. It reuses the same page files as US1 and US2, so it is also safest after the primary and contextual hierarchy work is stable.
  • User Story 4 (Phase 6): Depends on Foundational completion and should land after the standard-page rule is clear, because it documents the explicit exception to that rule.
  • Polish (Phase 7): Depends on all desired story phases being complete.

User Story Dependencies

  • US1: Independent after Phase 2 and should be delivered first as the MVP.
  • US2: Independent after Phase 2 from a behavior standpoint, but shares files with US1 and should usually follow it in the same branch.
  • US3: Independent after Phase 2 from a behavior standpoint, but depends on the stabilized header hierarchy from US1 and US2 for low-risk implementation.
  • US4: Independent after Phase 2 and focused on the explicit special-type exception for tenant detail.

Within Each User Story

  • Story-level tests should be written and made to fail before the implementation tasks for that story.
  • Page-level behavior changes should preserve current authorization, confirmation, notification, and audit semantics.
  • Each story should be verified through its focused test files before moving on.

Parallel Opportunities

  • T002 and T003 can run in parallel during Setup.
  • T005 and T006 can run in parallel once the inventory in T004 exists.
  • Within each story, the test tasks marked [P] can run in parallel because they touch separate files.
  • US1, US2, and US3 share several of the same page classes, so their implementation tasks are not good parallel candidates even though the stories are independently testable.
  • US4 can proceed in parallel with late US3 polish if one contributor is focused only on ViewTenant, the guard layer, and the smoke suite.

Parallel Example: User Story 1

# Launch the focused header-hierarchy tests together:
Task: "Extend state-sensitive primary-action assertions for baseline profile detail in apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php and apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php"
Task: "Add one-primary-action assertions for evidence snapshot and finding exception detail in apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php and apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php"
Task: "Add one-primary-action assertions for tenant review and tenant edit surfaces in apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, apps/platform/tests/Feature/Filament/TenantReviewHeaderDisciplineTest.php, and apps/platform/tests/Feature/Filament/EditTenantHeaderDisciplineTest.php"

Parallel Example: User Story 4

# Split the explicit exception work across tests and implementation:
Task: "Extend workflow-heavy exception assertions for tenant detail in apps/platform/tests/Feature/Filament/TenantViewHeaderUiEnforcementTest.php, apps/platform/tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php, and apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php"
Task: "Move pure tenant-detail navigation into contextual placement outside the header and reorder grouped header actions into explicit external-link, verification/setup, and lifecycle buckets in apps/platform/app/Filament/Resources/TenantResource/Pages/ViewTenant.php"

Implementation Strategy

MVP First (User Story 1 Only)

  1. Complete Phase 1: Setup.
  2. Complete Phase 2: Foundational.
  3. Complete Phase 3: User Story 1.
  4. STOP and VALIDATE: Confirm the five remediation-required standard pages expose one clear next step.

Incremental Delivery

  1. Deliver US1 to remove competing primary actions.
  2. Deliver US2 to move navigation closer to the content it belongs to.
  3. Deliver US3 to calm rare and dangerous actions without hiding them.
  4. Deliver US4 to make the workflow-heavy tenant detail exception explicit and disciplined.
  5. Finish with compliant-reference confirmation, vocabulary cleanup, validation, and formatting.

Validation Rule

  1. Do not mark a story complete until its focused verification task passes.
  2. Preserve existing 404 vs 403 behavior, confirmation requirements, and OperationRun semantics throughout implementation.
  3. Treat the compliant-reference set as a regression baseline, not as a cosmetic rewrite target.

Notes

  • [P] tasks touch different files and can be executed in parallel.
  • User-story labels map directly to the prioritized stories in spec.md.
  • This feature deliberately prefers existing Filament action builders and guard infrastructure over introducing a new header-action framework.