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

# 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.

- [X] T001 Create the Spec 192 guard entry point in `apps/platform/tests/Feature/Guards/Spec192RecordPageHeaderDisciplineGuardTest.php`
- [X] 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`
- [X] 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.

- [X] T004 Encode the Spec 192 surface inventory, classifications, and explicit `ViewTenant` exception metadata in `apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php`
- [X] 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`
- [X] 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

- [X] 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`
- [X] 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`
- [X] 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

- [X] T010 [US1] Refactor state-sensitive primary-action selection and grouped secondaries in `apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php`
- [X] 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`
- [X] 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`
- [X] T013 [US1] Refactor tenant review header hierarchy to promote only one lifecycle primary action in `apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php`
- [X] 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`
- [X] 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

- [X] 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`
- [X] 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

- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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

- [X] 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`
- [X] 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

- [X] T026 [US3] Group non-primary baseline profile actions into deliberate secondary and admin buckets in `apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php`
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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
- [X] 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

- [X] 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`
- [X] 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

- [X] 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`
- [X] 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`
- [X] 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.

- [X] 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`
- [X] 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`
- [X] 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`
- [X] T040 [P] Extend `apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php` with no-regression coverage for the compliant reference set named in Spec 192
- [X] 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`
- [X] 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`
- [X] T043 [P] Run the focused verification commands documented in `specs/192-record-header-discipline/quickstart.md`
- [X] 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

```bash
# 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

```bash
# 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.