ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
cc93329672
TenantAtlas/specs/132-guid-context-resolver/tasks.md
ahmido 8ee1174c8d feat: add resolved reference presentation layer (#161) 
## Summary
- add the shared resolved-reference foundation with registry, resolvers, presenters, and badge semantics
- refactor related context, assignment evidence, and policy-version assignment rendering toward label-first reference presentation
- add Spec 132 artifacts and focused Pest coverage for reference resolution, degraded states, canonical linking, and tenant-context carryover

## Verification
- `vendor/bin/sail bin pint --dirty --format agent`
- focused Pest verification was marked complete in the task artifact

## Notes
- this PR is opened from the current session branch
- `specs/132-guid-context-resolver/tasks.md` reflects in-progress completion state for the implemented tasks

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #161
2026-03-10 18:52:52 +00:00

20 KiB
Raw Blame History

Tasks: GUID Context Resolver & Human-Readable Reference Presentation (132)

Input: Design documents from specs/132-guid-context-resolver/ (spec.md, plan.md, research.md, data-model.md, contracts/, quickstart.md)
Prerequisites: specs/132-guid-context-resolver/plan.md (required), specs/132-guid-context-resolver/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 references and canonical destinations.
RBAC: Preserve workspace and tenant isolation, deny-as-not-found 404 for non-members, 403 for in-scope members missing capability, and capability-registry usage only for reference linkability.
Filament UI: This feature extends existing Filament resource and page surfaces only; keep inspect affordances explicit, visible row actions capped, and read-only detail rendering inside structured infolist or related-context sections.

Phase 1: Setup (Shared Infrastructure)

Purpose: Reconfirm the exact target surfaces, shared helpers, and test neighborhoods before introducing the common reference layer.

  • T001 Audit current reference-heavy seams in app/Support/Navigation/RelatedNavigationResolver.php, app/Support/Navigation/CrossResourceNavigationMatrix.php, resources/views/filament/infolists/entries/related-context.blade.php, app/Support/OperationRunLinks.php, and app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php
  • T002 [P] Audit current local lookup, label, and badge sources in app/Services/Directory/EntraGroupLabelResolver.php, app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php, app/Services/Baselines/SnapshotRendering/RenderedSnapshotItem.php, app/Support/Badges/BadgeCatalog.php, and app/Support/Badges/BadgeRenderer.php
  • T003 [P] Audit current reference-related and tenant-context test neighborhoods in tests/Feature/PolicyVersionViewAssignmentsTest.php, tests/Feature/Drift/DriftFindingDetailShowsAssignmentsDiffTest.php, tests/Feature/Filament/BaselineSnapshotRbacRoleDefinitionsTest.php, tests/Feature/Filament/TenantRoleDefinitionsSelectorDbOnlyTest.php, and tests/Feature/Rbac/

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Build the shared reference contracts, registry, adapters, and renderers that every user story depends on.

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

  • T004 Create shared reference value objects in app/Support/References/ReferenceDescriptor.php, app/Support/References/ResolvedReference.php, app/Support/References/ReferenceLinkTarget.php, app/Support/References/ReferenceTechnicalDetail.php, app/Support/References/ReferencePresentationVariant.php, and app/Support/References/ReferenceResolutionState.php
  • T005 Create resolver contracts and registry in app/Support/References/Contracts/ReferenceResolver.php, app/Support/References/ReferenceResolverRegistry.php, and app/Support/References/Resolvers/FallbackReferenceResolver.php
  • T006 Wire the shared reference layer into existing support seams in app/Providers/AppServiceProvider.php, app/Support/Navigation/RelatedNavigationResolver.php, and app/Support/Navigation/RelatedContextEntry.php
  • T007 [P] Create shared type and state presentation helpers backed by app/Support/Badges/BadgeCatalog.php and app/Support/Badges/BadgeRenderer.php in app/Support/References/ReferenceTypeLabelCatalog.php and app/Support/References/ReferenceStatePresenter.php
  • T008 [P] Create reusable reference renderers in resources/views/filament/infolists/entries/resolved-reference-detail.blade.php, resources/views/filament/infolists/entries/resolved-reference-compact.blade.php, and resources/views/filament/infolists/entries/related-context.blade.php
  • T009 [P] Add foundational unit coverage in tests/Unit/Support/References/ReferenceResolverRegistryTest.php and tests/Unit/Support/References/ResolvedReferenceTest.php
  • T010 [P] Add adapter, rendering, badge-mapping, and domain-copy smoke coverage in tests/Feature/Filament/ResolvedReferenceRenderingSmokeTest.php, tests/Unit/Support/References/RelatedContextReferenceAdapterTest.php, and tests/Unit/Support/References/ReferenceStateBadgeMappingTest.php

Checkpoint: The repo has one shared reference contract, resolver registry, and rendering seam that all in-scope surfaces can consume consistently.

Phase 3: User Story 1 - Read referenced objects without decoding IDs (Priority: P1) 🎯 MVP

Goal: Operators can read internal model-backed references as names and context first across the highest-value surfaces instead of decoding GUIDs manually.

Independent Test: Open a finding, baseline snapshot, operation run, and backup set with supported internal references and verify the UI renders label-first references with contextual type and secondary technical IDs.

Tests for User Story 1

  • T011 [P] [US1] Add unit coverage for core model-backed resolvers in tests/Unit/Support/References/ModelBackedReferenceResolverTest.php
  • T012 [P] [US1] Add finding and baseline-snapshot feature coverage in tests/Feature/Filament/FindingResolvedReferencePresentationTest.php and tests/Feature/Filament/BaselineSnapshotResolvedReferencePresentationTest.php
  • T013 [P] [US1] Add operation-run and backup-set feature coverage in tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php and tests/Feature/Filament/BackupSetResolvedReferencePresentationTest.php

Implementation for User Story 1

  • T014 [US1] Implement model-backed resolvers in app/Support/References/Resolvers/PolicyReferenceResolver.php, app/Support/References/Resolvers/PolicyVersionReferenceResolver.php, app/Support/References/Resolvers/BaselineProfileReferenceResolver.php, app/Support/References/Resolvers/BaselineSnapshotReferenceResolver.php, app/Support/References/Resolvers/OperationRunReferenceResolver.php, and app/Support/References/Resolvers/BackupSetReferenceResolver.php
  • T015 [US1] Adapt internal reference descriptors and mappings in app/Support/Navigation/CrossResourceNavigationMatrix.php and app/Support/Navigation/RelatedNavigationResolver.php
  • T016 [US1] Refactor finding and operation-run detail surfaces to render resolved references in app/Filament/Resources/FindingResource.php and app/Filament/Resources/OperationRunResource.php
  • T017 [US1] Refactor baseline-snapshot and backup-set surfaces to render resolved references in app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php and app/Filament/Resources/BackupSetResource.php

Checkpoint: User Story 1 is complete when the primary internal references on the target governance and operations screens are no longer GUID-first.

Phase 4: User Story 2 - Understand degraded references safely (Priority: P1)

Goal: Operators can distinguish resolved, partial, missing, inaccessible, and limited-context provider-backed references without losing the underlying evidence.

Independent Test: Render provider-backed and assignment-like references in resolved, partial, unresolved, missing, and inaccessible states and verify each state remains visible, distinct, and non-misleading.

Tests for User Story 2

  • T018 [P] [US2] Add degraded-state and shared badge-vocabulary unit coverage in tests/Unit/Support/References/ReferenceResolutionStateTest.php, tests/Unit/Support/References/UnsupportedReferenceResolverTest.php, and tests/Unit/Support/References/ReferenceStateBadgeMappingTest.php
  • T019 [P] [US2] Add provider-backed group and role reference coverage in tests/Feature/Filament/EntraGroupResolvedReferencePresentationTest.php and tests/Feature/Filament/TenantRoleDefinitionsSelectorDbOnlyTest.php
  • T020 [P] [US2] Add degraded-state assignment and evidence coverage in tests/Feature/PolicyVersionViewAssignmentsTest.php, tests/Feature/Drift/DriftFindingDetailShowsAssignmentsDiffTest.php, tests/Feature/Filament/BaselineSnapshotRbacRoleDefinitionsTest.php, and tests/Feature/Filament/BaselineTenantAssignmentsResolvedReferencePresentationTest.php

Implementation for User Story 2

  • T021 [US2] Implement provider-backed and governance resolvers in app/Support/References/Resolvers/EntraGroupReferenceResolver.php, app/Support/References/Resolvers/EntraRoleDefinitionReferenceResolver.php, app/Support/References/Resolvers/PrincipalReferenceResolver.php, and app/Support/References/Resolvers/AssignmentTargetReferenceResolver.php
  • T022 [US2] Refactor local group-label enrichment into structured resolution support in app/Services/Directory/EntraGroupLabelResolver.php and app/Support/References/Resolvers/EntraGroupReferenceResolver.php
  • T023 [US2] Implement shared degraded-state presentation, shared badge-domain mapping, and secondary technical-detail handling in app/Support/References/ReferenceStatePresenter.php, resources/views/filament/infolists/entries/resolved-reference-detail.blade.php, and resources/views/filament/infolists/entries/resolved-reference-compact.blade.php
  • T024 [US2] Upgrade GUID-heavy directory and assignment evidence surfaces in app/Filament/Resources/EntraGroupResource.php, app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php, app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php, and app/Services/Baselines/SnapshotRendering/RenderedSnapshotItem.php

Checkpoint: User Story 2 is complete when degraded references look intentionally different from fully resolved ones and still preserve technical evidence secondarily.

Phase 5: User Story 3 - Navigate from references when allowed (Priority: P2)

Goal: Authorized operators can follow resolved references to canonical destinations, while unauthorized or non-actionable references remain informative but non-clickable.

Independent Test: Open supported references from in-scope screens and verify that only permitted references are actionable and that every actionable link resolves to the canonical destination for that object.

Tests for User Story 3

  • T025 [P] [US3] Add authorization-aware link generation unit coverage in tests/Unit/Support/References/ReferenceLinkTargetTest.php and tests/Unit/Support/References/CapabilityAwareReferenceResolverTest.php
  • T026 [P] [US3] Add clickable versus non-clickable RBAC coverage, including assignment-like relation-manager cases and tenant-context entry to canonical destinations, in tests/Feature/Rbac/ResolvedReferenceAuthorizationTest.php
  • T027 [P] [US3] Add canonical destination and tenant-context carryover coverage in tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php, tests/Feature/Filament/PolicyVersionResolvedReferenceLinksTest.php, and tests/Feature/Filament/TenantContextResolvedReferenceCarryoverTest.php

Implementation for User Story 3

  • T028 [US3] Add capability-aware canonical link generation in app/Support/References/ReferenceLinkBuilder.php and app/Support/OperationRunLinks.php
  • T029 [US3] Refactor shared navigation mapping to consume canonical link targets in app/Support/Navigation/RelatedNavigationResolver.php and app/Support/Navigation/CrossResourceNavigationMatrix.php
  • T030 [US3] Upgrade policy-version and finding row/detail actions to use resolved reference links while preserving explicit inspect affordances and row-action limits in app/Filament/Resources/PolicyVersionResource.php and app/Filament/Resources/FindingResource.php
  • T031 [US3] Upgrade operation-run, baseline-snapshot, and baseline tenant assignment contextual links to use shared canonical destinations while keeping documented action-surface exemptions current and preserving tenant-context filters, badges, or source-context metadata on canonical destinations in app/Filament/Resources/OperationRunResource.php, app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php, app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php, and app/Support/Navigation/CanonicalNavigationContext.php

Checkpoint: User Story 3 is complete when canonical linking is role-aware, predictable, and never ambiguous about clickability.

Phase 6: User Story 4 - Extend the same pattern to future surfaces (Priority: P3)

Goal: The product can add new reference classes and new reference-heavy surfaces without reintroducing page-specific formatting logic.

Independent Test: Register an unsupported or future reference class through the shared layer and verify the page degrades safely without rewriting existing target templates.

Tests for User Story 4

  • T032 [P] [US4] Add extensibility and unsupported-class regression coverage in tests/Unit/Support/References/ReferenceResolverRegistryExtensibilityTest.php and tests/Feature/Filament/ResolvedReferenceUnsupportedClassTest.php
  • T033 [P] [US4] Add regression coverage preventing GUID-first rendering from returning in tests/Feature/Filament/FindingResolvedReferencePresentationTest.php, tests/Feature/Filament/BaselineSnapshotResolvedReferencePresentationTest.php, and tests/Feature/Filament/EntraGroupResolvedReferencePresentationTest.php

Implementation for User Story 4

  • T034 [US4] Add reusable reference registration seams in app/Support/References/ReferenceClass.php, app/Support/References/ReferenceResolverRegistry.php, and app/Providers/AppServiceProvider.php
  • T035 [US4] Replace remaining page-specific GUID formatting branches, refresh action-surface declarations, and normalize domain-consistent operator copy across labels, helper text, link text, empty states, and degraded-state copy on touched Filament surfaces in app/Filament/Resources/BackupSetResource.php, app/Filament/Resources/EntraGroupResource.php, app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php, and resources/views/filament/infolists/entries/related-context.blade.php
  • T036 [US4] Add reusable compact/detail presentation adapters for future surfaces in app/Support/References/ResolvedReferencePresenter.php and app/Support/References/RelatedContextReferenceAdapter.php

Checkpoint: User Story 4 is complete when a new supported reference class can be added through the shared layer without touching every existing target surface.

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Final verification, formatting, and cross-surface cleanup after all user stories are implemented.

  • T037 [P] Run focused Pest verification from specs/132-guid-context-resolver/quickstart.md
  • T038 [P] Run formatting for changed files with vendor/bin/sail bin pint --dirty --format agent
  • T039 Validate the manual QA scenarios, tenant-context carryover behavior, domain-consistent operator copy, and rollout boundary from specs/132-guid-context-resolver/quickstart.md, confirming the named in-scope surfaces are migrated while out-of-scope dashboards and later summary views are explicitly deferred

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 layer exists.
  • User Story 3 (Phase 5): Depends on Foundational completion and benefits from US1 and US2 because the same resolved-reference contracts and degraded-state vocabulary will already be in place.
  • User Story 4 (Phase 6): Depends on Foundational completion and should land after the main surfaces prove the shared pattern works.
  • Polish (Phase 7): 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 after Foundational, though it reuses the same registry, renderers, and target surfaces established by US1.
  • User Story 3 (P2): Independent after Foundational, but gains efficiency once US1 and US2 establish the core reference payloads and degraded-state rules.
  • User Story 4 (P3): Independent after Foundational but should follow the main surface rollout so extensibility is shaped by proven behavior rather than theory.

Within Each User Story

  • Tests should be added before or alongside implementation and must fail before the story is considered complete.
  • Resolver registration and value-object work should land before surface wiring.
  • Shared rendering and degraded-state presentation should be complete before final linkability or row-action cleanup.
  • Authorization-aware behavior must be enforced before story verification is treated as complete.

Parallel Opportunities

  • Setup tasks T002 and T003 can run in parallel.
  • In Foundational, T007, T008, T009, and T010 can run in parallel after the core file layout from T004 through T006 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.
  • In US4, T032 and T033 can run in parallel.

Parallel Example: User Story 1

# Launch US1 test work in parallel:
T011 tests/Unit/Support/References/ModelBackedReferenceResolverTest.php
T012 tests/Feature/Filament/FindingResolvedReferencePresentationTest.php + tests/Feature/Filament/BaselineSnapshotResolvedReferencePresentationTest.php
T013 tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php + tests/Feature/Filament/BackupSetResolvedReferencePresentationTest.php

Parallel Example: User Story 2

# Launch US2 test work in parallel:
T018 tests/Unit/Support/References/ReferenceResolutionStateTest.php + tests/Unit/Support/References/UnsupportedReferenceResolverTest.php
T019 tests/Feature/Filament/EntraGroupResolvedReferencePresentationTest.php + tests/Feature/Filament/TenantRoleDefinitionsSelectorDbOnlyTest.php
T020 tests/Feature/PolicyVersionViewAssignmentsTest.php + tests/Feature/Drift/DriftFindingDetailShowsAssignmentsDiffTest.php + tests/Feature/Filament/BaselineSnapshotRbacRoleDefinitionsTest.php

Parallel Example: User Story 3

# Launch US3 test work in parallel:
T025 tests/Unit/Support/References/ReferenceLinkTargetTest.php + tests/Unit/Support/References/CapabilityAwareReferenceResolverTest.php
T026 tests/Feature/Rbac/ResolvedReferenceAuthorizationTest.php
T027 tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php + tests/Feature/Filament/PolicyVersionResolvedReferenceLinksTest.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 the label-first internal-reference behavior on findings, snapshots, runs, and backup sets before expanding further.

Incremental Delivery

  1. Ship US1 to eliminate GUID-first rendering for the primary internal references.
  2. Add US2 to make degraded and provider-backed references explicit and safe.
  3. Add US3 to make canonical linking capability-aware and predictable.
  4. Add US4 to lock in extensibility and prevent a return to page-specific formatting logic.

Suggested MVP Scope

  • MVP = Phases 1 through 3, then run the focused verification from specs/132-guid-context-resolver/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], [US3], and [US4] labels.
  • Parallel markers are used only where tasks can proceed independently without conflicting incomplete prerequisites.