ahmido
39298f27f2
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
234 lines
18 KiB
Markdown
234 lines
18 KiB
Markdown
# 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
|
|
|
|
- [x] TGC001 Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
|
|
- [x] TGC002 New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit.
|
|
- [x] TGC003 Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
|
|
- [x] TGC004 Planned validation commands cover the change without pulling in unrelated lane cost.
|
|
- [x] TGC005 The declared surface test profile or `standard-native-filament` relief is explicit.
|
|
- [x] 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.
|
|
|
|
- [x] 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.
|
|
- [x] 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/`.
|
|
- [x] 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.
|
|
- [x] 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`.
|
|
- [x] 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/`.
|
|
- [x] 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.
|
|
|
|
- [x] 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.
|
|
- [x] T008 [P] Add feature coverage for workspace/environment denial in `apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`.
|
|
- [x] 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`.
|
|
- [x] 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`.
|
|
- [x] T011 Ensure the query supports filters for operation run, provider, subject class, resource type, actionability, readiness impact, reason, active binding, and candidate availability.
|
|
- [x] T012 Ensure the query returns display labels only as human-readable metadata and never as identity.
|
|
- [x] 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
|
|
|
|
- [x] T014 [P] [US1] Add Filament/Livewire page render coverage in `apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`, including DB-only render coverage.
|
|
- [x] 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`.
|
|
- [x] T016 [P] [US1] Add candidate/detail disclosure coverage in `apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`.
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [x] T017 [US1] Add the environment-scoped Baseline Subject Resolution page under `apps/platform/app/Filament/Pages/` using the route chosen in `spec.md`.
|
|
- [x] 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.
|
|
- [x] T019 [US1] Implement focused row/action-modal detail with subject context, candidate list, and current decision using progressive disclosure.
|
|
- [x] T020 [US1] Add empty states for "no baseline subject decisions required" and "run baseline compare first".
|
|
- [x] 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
|
|
|
|
- [x] 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.
|
|
- [x] T023 [P] [US2] Add RBAC positive/negative action tests in `apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`.
|
|
- [x] T024 [P] [US2] Add audit assertions in `apps/platform/tests/Feature/ProviderResources/ProviderResourceBindingServiceTest.php` and `apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`.
|
|
- [x] T025 [P] [US2] Add display-name rejection coverage in `apps/platform/tests/Feature/ProviderResources/ProviderResourceBindingServiceTest.php`.
|
|
- [x] T026 [P] [US2] Add Filament action modal/note/confirmation tests in `apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`.
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [x] T027 [US2] Wire manual binding action to `ProviderResourceBindingService::createManualBinding()` and require a valid `ResourceIdentity` candidate plus operator note.
|
|
- [x] T028 [US2] Wire decision recording only when provider/canonical metadata supplies a valid identity.
|
|
- [x] 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.
|
|
- [x] T030 [US2] Wire revocation action to `ProviderResourceBindingService::revoke()` with required note and confirmation.
|
|
- [x] 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.
|
|
- [x] T032 [US2] Ensure every high-impact action uses Filament `->action(...)` plus confirmation and does not execute through URL-only actions.
|
|
- [x] 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
|
|
|
|
- [x] T034 [P] [US3] Add Baseline Compare contextual link/count coverage in `apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`.
|
|
- [x] T035 [P] [US3] Add OperationRun follow-up link coverage in `apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`.
|
|
- [x] T036 [P] [US3] Add link-scope denial coverage in `apps/platform/tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`.
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [x] 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.
|
|
- [x] T038 [US3] Update the OperationRun related-navigation support to add concise subject-resolution follow-up text and a filtered link for baseline compare runs.
|
|
- [x] T039 [US3] Ensure links include only safe filters such as operation run, workspace, and environment, and reject cross-environment run IDs.
|
|
- [x] 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
|
|
|
|
- [x] T041 [P] [US4] Existing `apps/platform/tests/Unit/Support/Baselines/Matching/SubjectMatchingPipelineTest.php` covers active-decision consumption.
|
|
- [x] T042 [P] [US4] Rerun/refresh UX delegates to existing compare UX in `apps/platform/app/Filament/Pages/BaselineSubjectResolution.php`.
|
|
- [x] T043 [P] [US4] Existing matching and provider-resource tests cover revoked decisions not being active truth.
|
|
|
|
### Implementation for User Story 4
|
|
|
|
- [x] 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.
|
|
- [x] T045 [US4] Ensure `SubjectMatchingPipeline` or existing compare integration consumes active decisions and ignores revoked decisions without adding display-name fallback.
|
|
- [x] 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.
|
|
|
|
- [x] 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.
|
|
- [x] 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.
|
|
- [x] T049 [P] Add automated browser smoke coverage for the new surface under `apps/platform/tests/Browser/`.
|
|
- [x] T050 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines tests/Unit/Support/Resources`.
|
|
- [x] 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`.
|
|
- [x] T052 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines/BaselineSubjectResolutionQueryTest.php tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`.
|
|
- [x] 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`.
|
|
- [x] T054 Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec384BaselineSubjectResolutionSmokeTest.php --filter BaselineSubjectResolution`.
|
|
- [x] T055 Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`.
|
|
- [x] T056 Run `git diff --check`.
|
|
- [x] 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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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
|
|
|
|
1. Finish setup/guardrails and query foundation.
|
|
2. Implement the list/detail page without mutations.
|
|
3. Add audited decision actions.
|
|
4. Add contextual links from Baseline Compare and OperationRun detail.
|
|
5. Add rerun/refresh compare delegation and future-compare consumption checks.
|
|
6. 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.
|