210 lines
15 KiB
Markdown
210 lines
15 KiB
Markdown
# Tasks: Cross-Resource Navigation & Drill-Down Cohesion (131)
|
|
|
|
**Input**: Design documents from `specs/131-cross-resource-navigation/` (`spec.md`, `plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`)
|
|
**Prerequisites**: `specs/131-cross-resource-navigation/plan.md` (required), `specs/131-cross-resource-navigation/spec.md` (required for user stories)
|
|
|
|
**Tests**: REQUIRED (Pest) for all runtime behavior changes in this repo.
|
|
**Operations**: No new `OperationRun` flow is introduced; this feature reuses existing operational records strictly as canonical destinations.
|
|
**RBAC**: Preserve workspace and tenant isolation, deny-as-not-found 404 for non-members, 403 for in-scope members missing target capability, and canonical capability-registry usage only.
|
|
**Filament UI**: This feature extends existing Filament resource and page surfaces only; keep inspect affordances explicit, visible row actions capped, and related context rendered through sectioned read-only layouts.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Reconfirm the exact route, resource, and policy seams before building the shared navigation layer.
|
|
|
|
- [X] T001 Review canonical operations route and helper seams in `routes/web.php`, `app/Support/OperationRunLinks.php`, and `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
- [X] T002 [P] Review in-scope resource list and detail seams in `app/Filament/Resources/FindingResource.php`, `app/Filament/Resources/BaselineSnapshotResource.php`, `app/Filament/Resources/PolicyVersionResource.php`, and `app/Filament/Resources/BackupSetResource.php`
|
|
- [X] T003 [P] Review existing authorization and context-preservation seams in `app/Policies/OperationRunPolicy.php`, `app/Policies/FindingPolicy.php`, and `app/Filament/Pages/Monitoring/Operations.php`
|
|
- [X] T004 [P] Review current navigation and evidence test coverage in `tests/Feature/Findings/FindingWorkflowViewActionsTest.php`, `tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php`, `tests/Feature/Operations/TenantlessOperationRunViewerTest.php`, and `tests/Feature/Filament/PolicyVersionBaselineEvidenceVisibilityTest.php`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Build the shared navigation abstraction and rendering seam that every user story depends on.
|
|
|
|
**⚠️ CRITICAL**: No user story work should begin until this phase is complete.
|
|
|
|
- [X] T005 Create shared navigation value objects in `app/Support/Navigation/NavigationMatrixRule.php`, `app/Support/Navigation/RelatedContextEntry.php`, and `app/Support/Navigation/UnavailableRelationState.php`
|
|
- [X] T006 Create the centralized navigation matrix and resolver in `app/Support/Navigation/CrossResourceNavigationMatrix.php`, `app/Support/Navigation/RelatedNavigationResolver.php`, and `app/Support/Navigation/RelatedActionLabelCatalog.php`
|
|
- [X] T007 Create canonical context preservation helpers in `app/Support/Navigation/CanonicalNavigationContext.php` and `app/Support/OperationRunLinks.php`
|
|
- [X] T008 [P] Create the reusable related-context rendering partial in `resources/views/filament/infolists/entries/related-context.blade.php`
|
|
- [X] T009 [P] Add unit coverage for matrix resolution, label vocabulary, and unavailable-state handling in `tests/Unit/Support/RelatedNavigationResolverTest.php` and `tests/Unit/Support/RelatedActionLabelCatalogTest.php`
|
|
- [X] T010 [P] Add unit coverage for canonical context preservation in `tests/Unit/Support/CanonicalNavigationContextTest.php`
|
|
|
|
**Checkpoint**: The repo has a single shared navigation-matrix and related-context abstraction that resource surfaces can consume consistently.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Trace a finding to its source (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Operators can move from a finding to its most important source evidence and run context without copying IDs or hitting a dead end.
|
|
|
|
**Independent Test**: Open a finding with related snapshot, policy, policy-version, and run context and verify that the list and detail surfaces expose actionable related navigation with correct 404/403-aware degradation.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [X] T011 [P] [US1] Add finding detail related-context coverage in `tests/Feature/Findings/FindingRelatedNavigationTest.php`
|
|
- [X] T012 [P] [US1] Extend finding list drill-down coverage in `tests/Feature/Findings/FindingWorkflowRowActionsTest.php` and `tests/Feature/Findings/FindingWorkflowViewActionsTest.php`
|
|
- [X] T013 [P] [US1] Add cross-resource authorization coverage for finding-linked destinations in `tests/Feature/Rbac/CrossResourceNavigationAuthorizationTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T014 [US1] Implement finding-specific matrix rules and resolver mappings in `app/Support/Navigation/CrossResourceNavigationMatrix.php` and `app/Support/Navigation/RelatedNavigationResolver.php`
|
|
- [X] T015 [US1] Add a structured related-context section to finding detail in `app/Filament/Resources/FindingResource.php` and `resources/views/filament/infolists/entries/related-context.blade.php`
|
|
- [X] T016 [US1] Add canonical run and source-evidence drill-down actions to the findings list in `app/Filament/Resources/FindingResource.php`
|
|
- [X] T017 [US1] Wire finding unavailable-state rendering and secondary identifier fallbacks in `app/Filament/Resources/FindingResource.php` and `app/Support/Navigation/UnavailableRelationState.php`
|
|
|
|
**Checkpoint**: User Story 1 is complete when findings no longer strand operators on raw evidence IDs and always offer the most useful next investigation step when authorized.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Move between policy history and snapshot evidence (Priority: P1)
|
|
|
|
**Goal**: Operators can move coherently between policies, policy versions, baseline snapshots, baseline profiles, and related findings without reconstructing lineage manually.
|
|
|
|
**Independent Test**: Open a policy version and a baseline snapshot, then verify the pages and relevant list surfaces expose parent policy, profile, snapshot, and finding drill-downs with consistent labels and graceful unavailable states.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [X] T018 [P] [US2] Add policy-version related-navigation coverage in `tests/Feature/Filament/PolicyVersionRelatedNavigationTest.php`
|
|
- [X] T019 [P] [US2] Add baseline-snapshot related-context coverage in `tests/Feature/Filament/BaselineSnapshotRelatedContextTest.php`
|
|
- [X] T020 [P] [US2] Extend existing policy and snapshot evidence coverage in `tests/Feature/Filament/PolicyVersionBaselineEvidenceVisibilityTest.php` and `tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T021 [US2] Implement policy, policy-version, snapshot, and profile matrix rules in `app/Support/Navigation/CrossResourceNavigationMatrix.php` and `app/Support/Navigation/RelatedNavigationResolver.php`
|
|
- [X] T022 [US2] Add parent-policy and snapshot drill-down behavior to policy-version list and detail surfaces in `app/Filament/Resources/PolicyVersionResource.php`
|
|
- [X] T023 [US2] Add profile, finding, run, and policy-version related context to baseline snapshots in `app/Filament/Resources/BaselineSnapshotResource.php` and `resources/views/filament/infolists/entries/related-context.blade.php`
|
|
- [X] T024 [US2] Align upstream and child navigation affordances on policy and baseline-profile surfaces in `app/Filament/Resources/PolicyResource.php`, `app/Filament/Resources/PolicyResource/RelationManagers/VersionsRelationManager.php`, and `app/Filament/Resources/BaselineProfileResource.php`
|
|
|
|
**Checkpoint**: User Story 2 is complete when policy history and snapshot evidence behave like one connected governance workflow instead of separate CRUD views.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Preserve context on canonical operations and backup/run flows (Priority: P2)
|
|
|
|
**Goal**: Tenant-context entry points and backup/run flows open canonical operations destinations without losing tenant meaning or forcing operators to backtrack through browser history.
|
|
|
|
**Independent Test**: Launch canonical operations from a tenant-context page and a backup-related page, then verify the destination route remains canonical, tenant context stays visible, and related domain objects remain reachable from the operations surfaces.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [X] T025 [P] [US3] Add canonical operations related-navigation coverage in `tests/Feature/Monitoring/OperationsRelatedNavigationTest.php`
|
|
- [X] T026 [P] [US3] Extend tenantless run viewer coverage for tenant-context preservation plus breadcrumb and back-link lineage in `tests/Feature/Operations/TenantlessOperationRunViewerTest.php` and `tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php`
|
|
- [X] T027 [P] [US3] Add backup-set to run navigation coverage in `tests/Feature/Filament/BackupSetRelatedNavigationTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T028 [US3] Expand canonical context-preservation behavior plus explicit breadcrumb and back-link lineage for operations list and detail pages in `app/Support/Navigation/CanonicalNavigationContext.php`, `app/Filament/Pages/Monitoring/Operations.php`, and `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
- [X] T029 [US3] Refactor all in-scope `View run` links to canonical helpers in `app/Filament/Resources/FindingResource.php`, `app/Filament/Resources/BaselineSnapshotResource.php`, `app/Filament/Resources/BackupSetResource.php`, and `app/Filament/Pages/BaselineCompareLanding.php`
|
|
- [X] T030 [US3] Add backup-set and target-resource related drill-downs to canonical run surfaces in `app/Support/OperationRunLinks.php` and `app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T031 [US3] Align backup-set detail and row actions with canonical run navigation and unavailable-state handling in `app/Filament/Resources/BackupSetResource.php` and `app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php`
|
|
|
|
**Checkpoint**: User Story 3 is complete when canonical operations pages preserve tenant meaning, backup/run flows work in both directions, and operators can return through explicit contextual navigation instead of history guesswork.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final regression protection, consistency cleanup, and verification across all stories.
|
|
|
|
- [X] T032 [P] Audit and remove remaining raw ID-only and non-canonical relation renderings in `app/Filament/Resources/FindingResource.php`, `app/Filament/Resources/PolicyVersionResource.php`, `app/Filament/Resources/BaselineSnapshotResource.php`, `app/Filament/Resources/BackupSetResource.php`, and `app/Support/OperationRunLinks.php`
|
|
- [X] T033 [P] Add regression coverage for shared label vocabulary and unavailable-state behavior in `tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php`, `tests/Feature/Rbac/CrossResourceNavigationAuthorizationTest.php`, and `tests/Feature/Findings/FindingRelatedNavigationTest.php`
|
|
- [X] T034 Run focused Pest verification from `specs/131-cross-resource-navigation/quickstart.md`
|
|
- [X] T035 Run formatting for changed files with `vendor/bin/sail bin pint --dirty --format agent`
|
|
- [ ] T036 Validate the manual QA scenarios in `specs/131-cross-resource-navigation/quickstart.md`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies; can start immediately.
|
|
- **Foundational (Phase 2)**: Depends on Setup; blocks all user stories.
|
|
- **User Story 1 (Phase 3)**: Depends on Foundational completion.
|
|
- **User Story 2 (Phase 4)**: Depends on Foundational completion and can proceed independently of US1 once the shared navigation layer exists.
|
|
- **User Story 3 (Phase 5)**: Depends on Foundational completion and benefits from US1/US2 because the same resolver and label vocabulary will already be in place.
|
|
- **Polish (Phase 6)**: Depends on all desired user stories being complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: First MVP slice; no dependency on other user stories.
|
|
- **User Story 2 (P1)**: Independent of US1 after Foundational, though it reuses the same support layer and shared partial.
|
|
- **User Story 3 (P2)**: Independent after Foundational, but gains efficiency once US1 and US2 establish the canonical shared navigation pattern across resource pages.
|
|
|
|
### Within Each User Story
|
|
|
|
- Tests should be added before or alongside implementation and must fail before the story is considered complete.
|
|
- Navigation-matrix rules and resolver mappings should land before UI surface wiring.
|
|
- Detail-page related context should be complete before list-level row actions are treated as stable for that story.
|
|
- Authorization-aware unavailable states should be implemented before final regression verification.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- Setup review tasks `T002`, `T003`, and `T004` can run in parallel.
|
|
- In Foundational, `T008`, `T009`, and `T010` can run in parallel after the support-layer file layout is agreed.
|
|
- In US1, `T011`, `T012`, and `T013` can run in parallel.
|
|
- In US2, `T018`, `T019`, and `T020` can run in parallel.
|
|
- In US3, `T025`, `T026`, and `T027` can run in parallel.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Launch US1 test work in parallel:
|
|
T011 tests/Feature/Findings/FindingRelatedNavigationTest.php
|
|
T012 tests/Feature/Findings/FindingWorkflowRowActionsTest.php + tests/Feature/Findings/FindingWorkflowViewActionsTest.php
|
|
T013 tests/Feature/Rbac/CrossResourceNavigationAuthorizationTest.php
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Launch US2 test work in parallel:
|
|
T018 tests/Feature/Filament/PolicyVersionRelatedNavigationTest.php
|
|
T019 tests/Feature/Filament/BaselineSnapshotRelatedContextTest.php
|
|
T020 tests/Feature/Filament/PolicyVersionBaselineEvidenceVisibilityTest.php + tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Launch US3 test work in parallel:
|
|
T025 tests/Feature/Monitoring/OperationsRelatedNavigationTest.php
|
|
T026 tests/Feature/Operations/TenantlessOperationRunViewerTest.php + tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php
|
|
T027 tests/Feature/Filament/BackupSetRelatedNavigationTest.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. Validate findings-to-source navigation independently before expanding to the broader governance graph.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Ship US1 to eliminate the highest-value investigation dead ends on findings.
|
|
2. Add US2 to connect policy history and snapshot evidence coherently.
|
|
3. Add US3 to finish canonical operations context preservation and backup/run cohesion.
|
|
|
|
### Suggested MVP Scope
|
|
|
|
- MVP = Phases 1 through 3, then run the focused finding-navigation and authorization tests from `specs/131-cross-resource-navigation/quickstart.md`.
|
|
|
|
---
|
|
|
|
## Format Validation
|
|
|
|
- Every task follows the checklist format `- [ ] T### [P?] [US?] Description with file path`.
|
|
- Setup, Foundational, and Polish phases intentionally omit story labels.
|
|
- User story phases use `[US1]`, `[US2]`, and `[US3]` labels.
|
|
- Parallel markers are used only where tasks can proceed independently without conflicting incomplete prerequisites.
|