TenantAtlas/specs/384-baseline-subject-resolution-ui/plan.md

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

Branch: 384-baseline-subject-resolution-ui | Date: 2026-06-16 | Spec: specs/384-baseline-subject-resolution-ui/spec.md Input: Feature specification from /specs/384-baseline-subject-resolution-ui/spec.md

Summary

Add a focused environment-scoped Baseline Subject Resolution surface that derives actionable rows from Spec 383 structured compare semantics, lets authorized operators create or revoke audited decisions through existing ProviderResourceBindingService, links from existing Baseline Compare and OperationRun contexts, and delegates rerun/refresh compare to existing baseline compare OperationRun UX. Do not add a generic workflow engine, new decision table, Evidence/Review readiness mapping, or provider mutation.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52.0 Primary Dependencies: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, PostgreSQL via Sail Storage: Existing PostgreSQL tables; provider_resource_bindings is the decision truth. No new primary table approved. Testing: Pest 4 feature/unit tests, Filament/Livewire action tests, targeted browser smoke for the new surface Validation Lanes: fast-feedback, confidence, browser; PostgreSQL lane only if migrations/indexes/locks/constraints are added Target Platform: Laravel monolith in apps/platform, Sail locally, Dokploy for staging/production Project Type: Laravel/Filament web application inside apps/platform Performance Goals: New page renders from DB-only data without provider/Graph calls; query remains scoped by workspace/environment and paginated. Constraints: No Graph calls on render; no display-name identity; non-member 404; member missing capability 403; high-impact actions require confirmation, note rules, audit, and tests. Scale/Scope: One environment-scoped resolution surface plus contextual links from existing Baseline Compare and OperationRun surfaces.

UI / Surface Guardrail Plan

• Guardrail scope: changed surfaces plus new strategic operator surface.
• Affected routes/pages/actions/states/navigation/panel/provider surfaces: new Baseline Subject Resolution page; existing BaselineCompareLanding; existing OperationRunResource detail; optional environment dashboard/Baseline Profile summary links.
• No-impact class, if applicable: N/A.
• Native vs custom classification summary: native Filament page/table/forms/actions first; custom Blade only if native/detail layout is insufficient and documented.
• Shared-family relevance: status messaging, action links, OperationRun follow-up links, audit/history, high-impact action modals.
• State layers in scope: page, URL-query, detail/modal, and existing admin panel page-list registration; no new panel provider or shell navigation.
• Audience modes in scope: operator-MSP and support-platform. No customer/read-only output.
• Decision/diagnostic/raw hierarchy plan: decision-first default rows; diagnostics and raw provider proof collapsed/truncated/capability-gated.
• Raw/support gating plan: truncate provider IDs by default; full IDs/proof/audit details inside diagnostics or detail drawer.
• One-primary-action / duplicate-truth control: the resolution page owns decision summaries and actions; Baseline Compare/OperationRun show counts/link only.
• Handling modes by drift class or surface: new page is review-mandatory; existing page links are report-only unless layout/action hierarchy changes.
• Repository-signal treatment: UI coverage registry updates are required because a new reachable surface is added.
• Special surface test profiles: shared-detail-family for the page/detail hierarchy; standard-native-filament for action/table behavior.
• Required tests or manual smoke: Filament/Livewire action tests, RBAC/audit tests, browser smoke.
• Exception path and spread control: none planned.
• Active feature PR close-out entry: Baseline Subject Resolution UI / Operator Decision Coverage.
• UI/Productization coverage decision: coverage artifacts must be updated during implementation.
• Coverage artifacts to update: docs/ui-ux-enterprise-audit/route-inventory.md, docs/ui-ux-enterprise-audit/design-coverage-matrix.md, and a new or updated page report for Baseline Subject Resolution.
• List-surface checklist: implementation must apply docs/product/standards/list-surface-review-checklist.md because the new page includes a list/table surface.
• No-impact rationale: N/A.
• Navigation / Filament provider-panel handling: register the page in the existing admin panel provider only; no new panel provider and no broad top-level navigation in V1.
• Screenshot or page-report need: yes, proportional screenshot/browser smoke because this is a new strategic decision surface with high-impact actions.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes.
• Systems touched: baseline compare semantics/rendering, OperationRun detail, provider resource binding decisions, audit logging, RBAC UI enforcement, UI coverage registry.
• Shared abstractions reused: ProviderResourceBindingService, ProviderResourceBindingPolicy, ProviderResourceResolutionMode, ProviderResourceBindingStatus, AuditRecorder, UiEnforcement/WorkspaceUiEnforcement, existing OperationRun link/start UX helpers, existing badge/status helpers.
• New abstraction introduced? why?: a focused BaselineSubjectResolutionQuery or equivalent may be added to derive actionable rows from structured compare semantics and active bindings. It is not persisted truth and not a workflow engine.
• Why the existing abstraction was sufficient or insufficient: binding service is sufficient for mutations; existing evidence-gap tables are insufficient because they are read-only and do not combine candidates/current decisions/audit/action forms into one decision context.
• Bounded deviation / spread control: the query service may serve only baseline subject resolution rows and filters. Any broader decision inbox/workflow usage requires a follow-up spec.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes for existing run detail links and optional baseline compare rerun; no new run type.
• Central contract reused: existing baseline compare OperationRun start UX through BaselineCompareService, OperationUxPresenter, OperationRunLinks, and existing lifecycle notification behavior.
• Delegated UX behaviors: queued toast, run link, browser event, dedupe/already-running messaging, terminal notification, and tenant/workspace-safe URL resolution remain delegated to the existing compare start path.
• Surface-owned behavior kept local: decision input collection, page filters, current decision display, and navigation to existing compare start controls.
• Queued DB-notification policy: no new queued DB notification.
• Terminal notification path: existing OperationRun lifecycle mechanism.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes.
• Provider-owned seams: provider key, provider resource type, provider resource ID, external ID, identity kind, canonical discriminator, descriptors/fingerprints.
• Platform-core seams: governed subject, canonical subject key, actionability, readiness impact, binding/exclusion/limitation decision, audit metadata, operator vocabulary.
• Neutral platform terms / contracts preserved: provider resource, governed subject, binding, accepted limitation, exclusion, unsupported coverage, missing expected, active/revoked/superseded decision.
• Retained provider-specific semantics and why: provider identifiers are needed to select a real candidate. They stay proof data and are not primary operator vocabulary or identity generated from display labels.
• Bounded extraction or follow-up path: document-in-feature for any provider-specific display hotspot; follow-up-spec if a reusable provider candidate renderer becomes necessary across unrelated domains.

Constitution Check

GATE: Must pass before implementation. Re-check after design and before code changes.

• Inventory-first: compare outcomes are derived from last observed inventory/compare context; no provider calls during render.
• Read/write separation: decisions are TenantPilot-only DB mutations with confirmation, required notes, authorization, audit, and tests. No provider mutation.
• Graph contract path: no Graph calls are introduced. If future evidence refresh requires Graph, it must use existing compare/sync jobs through GraphClientInterface, not this page render.
• Deterministic capabilities: V1 reuses workspace_baselines.view and workspace_baselines.manage; no raw capability strings in feature code.
• RBAC-UX: /admin tenant/workspace plane only; non-member workspace/environment access is 404; member missing capability is 403 for mutations; authorization uses Gates/Policies plus UI enforcement.
• Workspace isolation: workspace route context is mandatory and enforced before records/candidates are revealed.
• Tenant/environment isolation: every query/action is scoped to managed environment and workspace.
• Destructive-like actions: exclusion, accepted limitation, unsupported, missing expected, revocation, and manual binding require ->requiresConfirmation() or equivalent confirmed action flow.
• Global search: no globally searchable resource is added. If a Resource is later introduced, disable global search unless View/Edit and tenant-safe routing are proven.
• Run observability: resolution decisions are DB-only and audited; rerun compare uses existing OperationRun path.
• OperationRun start UX: local page must not compose queued toasts/links/events; reuse existing compare start UX.
• Ops-UX lifecycle: no direct OperationRun status/outcome transitions outside OperationRunService.
• Ops-UX summary counts: no new summary key is approved unless OperationSummaryKeys::all() and tests are updated.
• Test governance: unit, feature, Filament/Livewire, and browser lanes are explicitly planned.
• Proportionality: no new table/status family/capability family by default; one derived query/read service is justified by the focused decision workflow.
• Persisted truth: provider_resource_bindings remains the only durable decision truth.
• Behavioral state: reuse existing binding status and resolution modes.
• UI semantics: direct mapping from Spec 383 outcome truth and binding truth to UI; no new badge/status taxonomy unless an existing catalog cannot serve and spec is updated.
• Shared pattern first: use existing services/helpers/renderers before local implementations.
• Provider boundary: provider-specific identity stays descriptor/proof data; core UI and audit language remain provider-neutral.
• Filament-native UI: use native Filament components/shared primitives; no parallel local design system.
• UI/Productization coverage: implementation must update UI coverage registry and browser smoke evidence for the new surface.

Gate result for preparation: PASS.

Test Governance Check

• Test purpose / classification by changed surface: Unit for derived query/mapping; Feature for binding decisions, audit, RBAC, future compare consumption; Filament/Livewire for table/actions/modals; Browser for page reachability and visual smoke.
• Affected validation lanes: fast-feedback, confidence, browser; pgsql only if migrations/indexes/locks are introduced.
• Why this lane mix is the narrowest sufficient proof: The core risk is DB-backed decision correctness plus interactive Filament actions. Browser is limited to the new strategic surface.
• Narrowest proving command(s): see spec planned validation commands and tasks final validation.
• Fixture / helper / factory / seed / context cost risks: provider candidates and workspace/environment context can be expensive; keep them feature-local and explicit.
• Expensive defaults or shared helper growth introduced?: no planned shared defaults.
• Heavy-family additions, promotions, or visibility changes: no heavy-governance family by default.
• Surface-class relief / special coverage rule: standard-native-filament plus browser smoke for new strategic page.
• Closing validation and reviewer handoff: verify confirmation/auth/audit/display-name rejection/future compare consumption, UI registry updates, and browser smoke.
• Budget / baseline / trend follow-up: document-in-feature if browser fixture setup is slow.
• Review-stop questions: lane fit, hidden fixture cost, high-impact action confirmation, no raw provider proof as primary UI, no workflow creep.
• Escalation path: document-in-feature for contained UI/browser notes; follow-up-spec for granular capabilities, expiration, approval, or reusable workbench framework.
• Active feature PR close-out entry: Baseline Subject Resolution UI / Operator Decision Coverage.
• Why no dedicated follow-up spec is needed: the needed V1 resolution surface is bounded; listed follow-ups are optional future product decisions.

Existing Repository Surfaces Likely Affected

apps/platform/app/Filament/Pages/BaselineCompareLanding.php
apps/platform/app/Filament/Resources/OperationRunResource.php
apps/platform/app/Livewire/BaselineCompareEvidenceGapTable.php
apps/platform/app/Services/Resources/ProviderResourceBindingService.php
apps/platform/app/Models/ProviderResourceBinding.php
apps/platform/app/Policies/ProviderResourceBindingPolicy.php
apps/platform/app/Services/Baselines/Matching/SubjectMatchingPipeline.php
apps/platform/app/Support/Baselines/CompareSemantics/*
apps/platform/app/Support/Resources/ProviderResourceResolutionMode.php
apps/platform/app/Support/Resources/ProviderResourceBindingStatus.php
apps/platform/app/Support/Auth/Capabilities.php
apps/platform/app/Support/Audit/AuditActionId.php
docs/ui-ux-enterprise-audit/route-inventory.md
docs/ui-ux-enterprise-audit/design-coverage-matrix.md
docs/ui-ux-enterprise-audit/page-reports/...

The implementation may add a new page class, query/read service, focused Livewire component, translations, and tests under existing app/test directories. Exact file names should be verified during implementation rather than invented beyond this plan.

Technical Approach

1. Build a derived resolution query/read model over current baseline compare result semantics and active provider resource bindings.
2. Add a focused Filament page scoped by workspace/environment route and URL query filters.
3. Render a native Filament table with grouped actionable rows, clear empty states, and progressive detail.
4. Wire decision actions to ProviderResourceBindingService only. Do not duplicate transaction, supersession, or audit behavior in UI closures.
5. Add contextual links/counts from Baseline Compare and OperationRun detail.
6. Delegate rerun/refresh compare to existing baseline compare service and OperationRun UX.
7. Update UI coverage artifacts and run targeted validation.

Data / Migration Implications

• No new primary persisted entity is approved.
• No migration is planned for V1.
• If implementation proves an additive index or field is required, stop and update spec/plan before adding it.
• Existing provider_resource_bindings active uniqueness and status/mode checks remain authoritative.
• Decision records are tenant-owned operational truth scoped by workspace_id and managed_environment_id.

UI / Filament Implications

• Filament v5 / Livewire v4.0+ compliance is required; project currently has Livewire 4.1.4.
• Panel providers remain in apps/platform/bootstrap/providers.php; no new panel provider is planned.
• Do not enable global search for the resolution surface by default. If a Resource is introduced, disable global search unless View/Edit and tenant-safe URL rules are satisfied.
• The new list/table surface must follow docs/product/standards/list-surface-review-checklist.md; any deviation must be recorded in implementation close-out.
• High-impact actions execute through Action::make(...)->action(...) or equivalent Livewire/Filament action handlers and include confirmation.
• Use UiEnforcement/WorkspaceUiEnforcement and server-side Gates/Policies. UI disabled/hidden state is not authorization.
• No registered Filament assets are planned; php artisan filament:assets remains the normal deploy step only if assets are registered elsewhere.

Implementation Phases

Phase 1 - Prep and Guardrail Alignment

Confirm dependencies, re-read completed close-outs, update UI coverage classification, and verify no Spec 385/report/workflow scope enters the implementation.

Phase 2 - Resolution Query and Row Model

Create the derived query/read service and tests for actionable rows, filters, current decisions, candidate counts, and legacy-payload refusal.

Phase 3 - Decision Actions

Wire actions to existing binding service for manual binding, canonical confirmation where applicable, exclusion, accepted limitation, unsupported coverage, missing expected where already supported, and revocation. Add authorization, confirmation, audit, and note-rule tests.

Phase 4 - Filament Surface

Create the page/table/detail/modal UX with native Filament components, safe empty states, scope signals, progressive diagnostics, and no raw provider details as primary UI.

Phase 5 - Contextual Links and Compare Refresh

Add filtered links/counts from Baseline Compare and OperationRun detail. Add rerun/refresh compare path only through existing baseline compare OperationRun UX.

Phase 6 - Validation and Coverage Close-Out

Run targeted tests, browser smoke, UI registry updates, Pint, and git diff --check. Record close-out without changing completed dependency specs.

Risk Controls

• Stop if implementation needs new table, new capability family, provider call, workflow/approval engine, or customer readiness mapping.
• Stop and update spec/plan if the existing binding service cannot support a required V1 decision without changing persistence semantics.
• Keep candidate data sanitized/truncated and diagnostics secondary.
• Keep link-only changes out of OperationRun lifecycle logic.
• Require tests for display-name rejection and cross-workspace/environment denial.

Rollout Considerations

• Staging validation required because this adds high-impact governance UI.
• No env vars, scheduler changes, queue names, storage volumes, or reverse proxy changes are planned.
• Queue workers should be restarted as part of normal deploy so rerun compare paths use the latest code.
• No new filament:assets requirement unless implementation registers assets.
• Browser smoke is required before production promotion because this is a new reachable operator surface.

Project Structure

specs/384-baseline-subject-resolution-ui/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
    └── requirements.md

apps/platform/app/
├── Filament/
│   ├── Pages/
│   └── Resources/
├── Livewire/
├── Services/
│   ├── Baselines/
│   └── Resources/
├── Support/
│   ├── Baselines/
│   ├── Resources/
│   └── Rbac/
└── Policies/

apps/platform/tests/
├── Unit/
├── Feature/
│   ├── Baselines/
│   ├── Filament/
│   └── ProviderResources/
└── Browser/

Structure Decision: Use existing Laravel/Filament app structure. Add only feature-local classes where needed and prefer existing services/policies/helpers.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
New derived resolution query/read service	Operators need one decision worklist that combines compare semantics, candidates, and active decisions	Local buttons on existing gap rows scatter decision context and duplicate semantics
New strategic Filament page	Human decisions need a focused context with candidates/current decision/audit/action forms	OperationRun detail is diagnostics-oriented and Baseline Compare is status/review-oriented

Proportionality Review

• Current operator problem: actionable compare blockers cannot become durable decisions from UI.
• Existing structure is insufficient because: current surfaces are read-only or diagnostic and current binding service has no operator worklist.
• Narrowest correct implementation: one derived query, one focused page, existing service/policy/audit for mutations.
• Ownership cost created: page/query/tests/UI coverage and future maintenance of decision copy/action modals.
• Alternative intentionally rejected: generic workflow/task engine and broad Governance Inbox.
• Release truth: current-release truth after Specs 381-383.