ahmido 39298f27f2 feat(ui): implement baseline subject resolution ui (#455 )

Added `BaselineSubjectResolution` page and supporting logic to visualize missing identities, ambiguous matches, and skipped coverages as defined in Spec 384. Replaces legacy compare warnings with an actionable, deterministic UI surface.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #455

2026-06-16 23:36:38 +00:00

18 KiB

Raw Blame History

Tasks: Spec 384 - Baseline Subject Resolution UI and Operator Decisions v1

Input: Design documents from /specs/384-baseline-subject-resolution-ui/ Prerequisites: plan.md, spec.md

Tests: Tests are REQUIRED because this feature adds runtime behavior, high-impact Filament actions, RBAC/audit paths, and a new reachable operator surface.

Test Governance Checklist

TGC001 Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
TGC002 New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit.
TGC003 Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
TGC004 Planned validation commands cover the change without pulling in unrelated lane cost.
TGC005 The declared surface test profile or standard-native-filament relief is explicit.
TGC006 Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.

Implementation Notes

Planned separate test files were consolidated where narrower: BaselineSubjectResolutionPageTest.php covers render, empty states, actions, RBAC, Baseline Compare link behavior, and OperationRun related-navigation behavior; BaselineSubjectResolutionQueryTest.php covers query/filter/legacy semantics.
Existing ProviderResourceBindingServiceTest.php and SubjectMatchingPipelineTest.php remain the canonical coverage for all V1 binding modes and active/revoked decision consumption.
Broad tests/Feature/Baselines tests/Feature/ProviderResources validation was run and residual baseline capture/compare failures are recorded in implementation-close-out.md.

Phase 1: Setup and Guardrails

Purpose: Confirm dependency close-outs, repo truth, and UI guardrails before implementation starts.

T001 Confirm specs/381-provider-resource-identity-binding/implementation-close-out.md, specs/382-baseline-matching-canonicalization/implementation-close-out.md, and specs/383-baseline-result-semantics/implementation-close-out.md exist and treat them as dependency context only.
T002 Confirm no code or artifact changes are made to completed specs specs/381-provider-resource-identity-binding/, specs/382-baseline-matching-canonicalization/, specs/383-baseline-result-semantics/, or historical specs/163-baseline-subject-resolution/.
T003 Re-read apps/platform/app/Services/Resources/ProviderResourceBindingService.php, apps/platform/app/Models/ProviderResourceBinding.php, apps/platform/app/Policies/ProviderResourceBindingPolicy.php, and apps/platform/app/Support/Resources/ProviderResourceResolutionMode.php; explicitly verify whether missing_expected is already supported without new persistence before implementing that mode.
T004 Re-read apps/platform/app/Filament/Pages/BaselineCompareLanding.php, apps/platform/app/Filament/Resources/OperationRunResource.php, apps/platform/app/Livewire/BaselineCompareEvidenceGapTable.php, and docs/ui-ux-enterprise-audit/page-reports/ui-015-baseline-compare.md.
T005 Apply docs/product/standards/list-surface-review-checklist.md for the new list/table surface, then update UI coverage artifacts for the new surface in docs/ui-ux-enterprise-audit/route-inventory.md, docs/ui-ux-enterprise-audit/design-coverage-matrix.md, and a new or updated page report under docs/ui-ux-enterprise-audit/page-reports/.
T006 Confirm no new Filament panel provider, broad top-level navigation item, global search resource, generic workflow engine, Evidence/Review readiness mapping, or Management Report/PDF scope is added; if required, stop and update spec.md and plan.md.

Phase 2: Foundational Resolution Query

Purpose: Build the derived read path that turns Spec 383 result semantics plus active decisions into actionable resolution rows.

T007 [P] Add unit coverage for actionable row derivation in apps/platform/tests/Unit/Support/Baselines/BaselineSubjectResolutionQueryTest.php, including a negative assertion that row derivation uses persisted compare/binding data and does not invoke Graph or provider runtime clients.
T008 [P] Add feature coverage for workspace/environment denial in apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php.
T009 [P] Add feature coverage proving legacy subject-key or historical payload shapes are not authoritative in apps/platform/tests/Unit/Support/Baselines/BaselineSubjectResolutionQueryTest.php.
T010 Add a focused query/read service for subject resolution rows under apps/platform/app/Services/Baselines/ or apps/platform/app/Support/Baselines/, deriving rows from current compare semantics and active provider_resource_bindings.
T011 Ensure the query supports filters for operation run, provider, subject class, resource type, actionability, readiness impact, reason, active binding, and candidate availability.
T012 Ensure the query returns display labels only as human-readable metadata and never as identity.
T013 Ensure resolved/no-action subjects are excluded from the default worklist while available through explicit filters if needed.

Checkpoint: Actionable subject rows can be derived and tested without UI.

Phase 3: User Story 1 - Find Actionable Subject Decisions (Priority: P1) - MVP

Goal: Provide the focused list/detail context operators need before decisions can be made.

Independent Test: The page lists actionable outcomes, supports filters, and shows correct empty states without raw diagnostics.

Tests for User Story 1

T014 [P] [US1] Add Filament/Livewire page render coverage in apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php, including DB-only render coverage.
T015 [P] [US1] Add filter and empty-state coverage in apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php and apps/platform/tests/Unit/Support/Baselines/BaselineSubjectResolutionQueryTest.php.
T016 [P] [US1] Add candidate/detail disclosure coverage in apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php.

Implementation for User Story 1

T017 [US1] Add the environment-scoped Baseline Subject Resolution page under apps/platform/app/Filament/Pages/ using the route chosen in spec.md.
T018 [US1] Implement the native Filament table/list with columns for subject, class, type, provider, problem, readiness impact, actionability, candidate count, current decision, source/last seen, and action.
T019 [US1] Implement focused row/action-modal detail with subject context, candidate list, and current decision using progressive disclosure.
T020 [US1] Add empty states for "no baseline subject decisions required" and "run baseline compare first".
T021 [US1] Ensure raw provider IDs, external IDs, fingerprints, and source proof are truncated/collapsed by default and not primary page content.

Checkpoint: Operators can find actionable decisions in one scoped page.

Phase 4: User Story 2 - Make Audited Resolution Decisions (Priority: P1)

Goal: Let authorized operators persist binding, exclusion, limitation, unsupported, missing expected, and revocation decisions through existing decision truth.

Independent Test: Each action creates/supersedes/revokes an active decision, emits audit, enforces note rules, and denies unauthorized actors.

Tests for User Story 2

T022 [P] [US2] Add decision action tests in apps/platform/tests/Feature/ProviderResources/ProviderResourceBindingServiceTest.php and apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php for binding, accepted limitation, missing_expected support, supersession, and revocation.
T023 [P] [US2] Add RBAC positive/negative action tests in apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php.
T024 [P] [US2] Add audit assertions in apps/platform/tests/Feature/ProviderResources/ProviderResourceBindingServiceTest.php and apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php.
T025 [P] [US2] Add display-name rejection coverage in apps/platform/tests/Feature/ProviderResources/ProviderResourceBindingServiceTest.php.
T026 [P] [US2] Add Filament action modal/note/confirmation tests in apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php.

Implementation for User Story 2

T027 [US2] Wire manual binding action to ProviderResourceBindingService::createManualBinding() and require a valid ResourceIdentity candidate plus operator note.
T028 [US2] Wire decision recording only when provider/canonical metadata supplies a valid identity.
T029 [US2] Wire exclusion, accepted limitation, unsupported coverage, and missing_expected only when T003 confirms existing support to existing ProviderResourceBindingService methods, requiring notes and clear modal copy.
T030 [US2] Wire revocation action to ProviderResourceBindingService::revoke() with required note and confirmation.
T031 [US2] Apply UiEnforcement or WorkspaceUiEnforcement and server-side Gate/Policy checks so non-members are 404 and members missing manage capability are 403 on mutation.
T032 [US2] Ensure every high-impact action uses Filament ->action(...) plus confirmation and does not execute through URL-only actions.
T033 [US2] Ensure action copy states mutation scope is TenantPilot decision only and not a direct provider/Microsoft mutation.

Checkpoint: Operators can make audited decisions; unauthorized actors cannot.

Phase 5: User Story 3 - Navigate From Compare and Operation Context (Priority: P2)

Goal: Add filtered links/counts from existing surfaces without turning those surfaces into decision owners.

Independent Test: Baseline Compare and OperationRun detail show links only when actionable outcomes exist and preserve workspace/environment filters.

Tests for User Story 3

T034 [P] [US3] Add Baseline Compare contextual link/count coverage in apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php.
T035 [P] [US3] Add OperationRun follow-up link coverage in apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php.
T036 [P] [US3] Add link-scope denial coverage in apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php.

Implementation for User Story 3

T037 [US3] Update apps/platform/app/Filament/Pages/BaselineCompareLanding.php or its supporting presenter to show action-required counts and a Resolve baseline subjects navigation link only when actionable outcomes exist.
T038 [US3] Update the OperationRun related-navigation support to add concise subject-resolution follow-up text and a filtered link for baseline compare runs.
T039 [US3] Ensure links include only safe filters such as operation run, workspace, and environment, and reject cross-environment run IDs.
T040 [US3] No environment dashboard or Baseline Profile shortcut was added in V1.

Checkpoint: Operators can reach the resolution page from compare/run context without duplicate decision UI.

Phase 6: User Story 4 - Re-run or Refresh Compare After Decisions (Priority: P3)

Goal: Give operators a safe path to validate decisions through existing baseline compare OperationRun UX.

Independent Test: Rerun/refresh delegates to existing compare start UX, and the next compare consumes active decisions.

Tests for User Story 4

T041 [P] [US4] Existing apps/platform/tests/Unit/Support/Baselines/Matching/SubjectMatchingPipelineTest.php covers active-decision consumption.
T042 [P] [US4] Rerun/refresh UX delegates to existing compare UX in apps/platform/app/Filament/Pages/BaselineSubjectResolution.php.
T043 [P] [US4] Existing matching and provider-resource tests cover revoked decisions not being active truth.

Implementation for User Story 4

T044 [US4] Add a rerun/refresh compare path only by delegating to existing baseline compare service/start UX; do not locally compose queued toasts, run links, terminal notifications, or OperationRun lifecycle changes.
T045 [US4] Ensure SubjectMatchingPipeline or existing compare integration consumes active decisions and ignores revoked decisions without adding display-name fallback.
T046 [US4] Ensure resolved/excluded/accepted-limitation subjects no longer appear as unresolved after a rerun, while still avoiding false no-drift presentation.

Checkpoint: Operators can validate decisions through existing compare workflow.

Phase 7: Polish and Cross-Cutting Validation

Purpose: Close UI coverage, browser smoke, regression, formatting, and deployment notes.

T047 [P] Update UI coverage close-out details in docs/ui-ux-enterprise-audit/route-inventory.md, docs/ui-ux-enterprise-audit/design-coverage-matrix.md, and the new/updated page report.
T048 [P] Review localization/translation handling for new labels, empty states, actions, modal headings, warnings, and audit-facing copy; V1 keeps page-local operator copy consistent with adjacent Filament pages.
T049 [P] Add automated browser smoke coverage for the new surface under apps/platform/tests/Browser/.
T050 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines tests/Unit/Support/Resources.
T051 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines tests/Feature/ProviderResources; residual non-Spec-384 failures recorded in implementation-close-out.md.
T052 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines/BaselineSubjectResolutionQueryTest.php tests/Feature/Filament/BaselineSubjectResolutionPageTest.php.
T053 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/BaselineDriftPostureSourceTest.php tests/Feature/ReviewPack/Spec347ReviewPackReadinessSemanticsTest.php tests/Feature/ReviewPack/Spec349ReviewPackResolutionGuidanceTest.php.
T054 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec384BaselineSubjectResolutionSmokeTest.php --filter BaselineSubjectResolution.
T055 Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.
T056 Run git diff --check.
T057 Record implementation close-out with Livewire v4 compliance, provider registration location, global search status, destructive/high-impact action confirmation/authorization/audit, asset strategy, tests run, browser smoke result, and deployment impact.

Dependencies and Execution Order

Phase Dependencies

Phase 1 blocks implementation because dependency and UI coverage decisions must be confirmed first.
Phase 2 blocks all user stories because the page and links need a single derived query/read path.
US1 can begin after Phase 2 and delivers the MVP visible decision worklist.
US2 depends on Phase 2 and can run alongside parts of US1 after the page action targets are known.
US3 depends on the query and route from US1.
US4 depends on decision actions from US2 and link/page behavior from US1.
Phase 7 follows all implemented stories.

User Story Dependencies

US1 (P1): MVP list/detail surface.
US2 (P1): primary mutation value; depends on query rows/candidates.
US3 (P2): discoverability from existing surfaces; depends on route/query.
US4 (P3): validation loop after decisions; depends on actions.

Parallel Opportunities

T007-T009 can run in parallel.
T014-T016 can run in parallel.
T022-T026 can run in parallel.
T034-T036 can run in parallel.
T041-T043 can run in parallel.
T047-T049 can run in parallel near close-out.

Parallel Example: Query Foundation

Task: "Add unit coverage for actionable row derivation in apps/platform/tests/Unit/Support/Baselines/BaselineSubjectResolutionQueryTest.php"
Task: "Add feature coverage for workspace/environment denial in apps/platform/tests/Feature/Baselines/BaselineSubjectResolutionIsolationTest.php"
Task: "Add legacy-payload refusal coverage in apps/platform/tests/Feature/Baselines/BaselineSubjectResolutionLegacyPayloadTest.php"

Parallel Example: Decision Actions

Task: "Add decision action tests in apps/platform/tests/Feature/ProviderResources/ProviderResourceBindingServiceResolutionTest.php"
Task: "Add RBAC positive/negative action tests in apps/platform/tests/Feature/Filament/BaselineSubjectResolutionActionAuthorizationTest.php"
Task: "Add Filament action modal/note/confirmation tests in apps/platform/tests/Feature/Filament/BaselineSubjectResolutionActionsTest.php"

Implementation Strategy

MVP First

Deliver Phase 2 plus US1 first. This gives a focused, scoped, read-only operator worklist and proves the query/page shape before high-impact actions land.

Incremental Delivery

Finish setup/guardrails and query foundation.
Implement the list/detail page without mutations.
Add audited decision actions.
Add contextual links from Baseline Compare and OperationRun detail.
Add rerun/refresh compare delegation and future-compare consumption checks.
Finish UI coverage, browser smoke, regression, and close-out.

Non-Goals During Implementation

Do not implement Spec 385 Evidence/Review readiness.
Do not add Management Report/PDF work.
Do not introduce a generic workflow, task, approval, or notification engine.
Do not parse legacy subject-key payloads.
Do not use display names as identity.
Do not add a new primary decision table without updating spec and plan.

18 KiB Raw Blame History