ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
30fe562ba2
TenantAtlas/specs/131-cross-resource-navigation/tasks.md
Ahmed Darrazi 94084a11e2 feat: add cross-resource navigation cohesion
2026-03-10 17:05:07 +01:00

15 KiB
Raw Blame History

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.

  • T001 Review canonical operations route and helper seams in routes/web.php, app/Support/OperationRunLinks.php, and app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
  • 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
  • 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
  • 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.

  • T005 Create shared navigation value objects in app/Support/Navigation/NavigationMatrixRule.php, app/Support/Navigation/RelatedContextEntry.php, and app/Support/Navigation/UnavailableRelationState.php
  • 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
  • T007 Create canonical context preservation helpers in app/Support/Navigation/CanonicalNavigationContext.php and app/Support/OperationRunLinks.php
  • T008 [P] Create the reusable related-context rendering partial in resources/views/filament/infolists/entries/related-context.blade.php
  • 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
  • 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

  • T011 [P] [US1] Add finding detail related-context coverage in tests/Feature/Findings/FindingRelatedNavigationTest.php
  • T012 [P] [US1] Extend finding list drill-down coverage in tests/Feature/Findings/FindingWorkflowRowActionsTest.php and tests/Feature/Findings/FindingWorkflowViewActionsTest.php
  • T013 [P] [US1] Add cross-resource authorization coverage for finding-linked destinations in tests/Feature/Rbac/CrossResourceNavigationAuthorizationTest.php

Implementation for User Story 1

  • T014 [US1] Implement finding-specific matrix rules and resolver mappings in app/Support/Navigation/CrossResourceNavigationMatrix.php and app/Support/Navigation/RelatedNavigationResolver.php
  • 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
  • T016 [US1] Add canonical run and source-evidence drill-down actions to the findings list in app/Filament/Resources/FindingResource.php
  • 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

  • T018 [P] [US2] Add policy-version related-navigation coverage in tests/Feature/Filament/PolicyVersionRelatedNavigationTest.php
  • T019 [P] [US2] Add baseline-snapshot related-context coverage in tests/Feature/Filament/BaselineSnapshotRelatedContextTest.php
  • 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

  • T021 [US2] Implement policy, policy-version, snapshot, and profile matrix rules in app/Support/Navigation/CrossResourceNavigationMatrix.php and app/Support/Navigation/RelatedNavigationResolver.php
  • T022 [US2] Add parent-policy and snapshot drill-down behavior to policy-version list and detail surfaces in app/Filament/Resources/PolicyVersionResource.php
  • 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
  • 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

  • T025 [P] [US3] Add canonical operations related-navigation coverage in tests/Feature/Monitoring/OperationsRelatedNavigationTest.php
  • 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
  • T027 [P] [US3] Add backup-set to run navigation coverage in tests/Feature/Filament/BackupSetRelatedNavigationTest.php

Implementation for User Story 3

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

  • 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
  • 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
  • T034 Run focused Pest verification from specs/131-cross-resource-navigation/quickstart.md
  • 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

# 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

# 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

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