TenantAtlas/specs/384-baseline-subject-resolution-ui/implementation-close-out.md

# Implementation Close-Out: Spec 384 - Baseline Subject Resolution UI

Date: 2026-06-16
Branch: `384-baseline-subject-resolution-ui`

## Summary

Implemented a focused environment-scoped Baseline Subject Resolution page that derives actionable rows from Spec 383 compare semantics and active provider-resource decisions. Authorized operators can create manual bindings, record subject decisions, revoke active decisions, and rerun compare through existing baseline compare OperationRun UX.

No new persisted entity, migration, capability family, provider call, workflow engine, customer-facing readiness mapping, or report/PDF scope was added.

## Filament / Livewire Contract

- Filament v5 compliance: implemented against Filament 5.2.1 and Livewire 4.1.4; no Livewire v3 or Filament v3/v4 APIs were introduced.
- Provider registration: the new page is registered in the existing admin panel provider at `apps/platform/app/Providers/Filament/AdminPanelProvider.php`; the provider remains registered through `apps/platform/bootstrap/providers.php`.
- Global search: no Filament Resource was added, so no new globally searchable resource exists.
- Destructive/high-impact actions:
  - `bindSubject`: `Action::make(...)->action(...)`, `->requiresConfirmation()`, `workspace_baselines.manage` UI enforcement, server-side environment authorization, existing binding service audit.
  - `recordDecision`: `Action::make(...)->action(...)`, `->requiresConfirmation()`, `workspace_baselines.manage` UI enforcement, server-side environment authorization, existing binding service audit.
  - `revokeDecision`: `Action::make(...)->action(...)`, `->requiresConfirmation()`, destructive UI enforcement, `Gate::authorize('revoke')`, existing binding service audit.
  - `runComparisonAgain`: confirmed action, requires `tenant.sync`, delegates to `BaselineCompareService` and existing OperationRun presenter/events.
- Asset strategy: no new Filament assets, panel assets, or heavy frontend assets were registered. Normal deploy can keep the existing `cd apps/platform && php artisan filament:assets` step.
- Testing plan/result: unit tests cover derived query/filter behavior; Filament/Livewire tests cover page render, empty states, manual binding, record decision, revoke, RBAC disabled state, outside-scope 404, Baseline Compare link behavior, and OperationRun related-navigation link behavior; browser smoke covers route/content/modal/mobile overflow.

## Validation

Passed:

- `cd apps/platform && ./vendor/bin/sail artisan route:list --path=baseline-subject-resolution`
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines/BaselineSubjectResolutionQueryTest.php tests/Unit/Support/Baselines/Matching/SubjectMatchingPipelineTest.php tests/Unit/Support/Resources/ResourceIdentityTest.php tests/Unit/Support/Resources/ProviderResourceDescriptorTest.php`
  - 16 passed, 112 assertions
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines tests/Unit/Support/Resources`
  - 73 passed, 577 assertions
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderResources`
  - 20 passed, 4 skipped, 75 assertions
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines/BaselineSubjectResolutionQueryTest.php tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`
  - 14 passed, 65 assertions
- `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec384BaselineSubjectResolutionSmokeTest.php --filter BaselineSubjectResolution`
  - 1 passed, 21 assertions
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/BaselineDriftPostureSourceTest.php tests/Feature/ReviewPack/Spec347ReviewPackReadinessSemanticsTest.php tests/Feature/ReviewPack/Spec349ReviewPackResolutionGuidanceTest.php`
  - 11 passed, 58 assertions
- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- `git diff --check`

## Review Remediation

Date: 2026-06-17

Manual review findings resolved:

- Route workspace/environment mismatch now denies as not found before page access or action/query handling.
- Livewire table reads now reauthorize the locked environment ID on each read path instead of trusting mount-time state.
- Candidate discovery no longer treats matching display labels as bindable identity. Bindable candidates must come from stable compare `ProviderResourceDescriptor` payloads or inventory descriptors matched by canonical provider-resource identity.

Additional validation:

- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines/BaselineSubjectResolutionQueryTest.php tests/Feature/Filament/BaselineSubjectResolutionPageTest.php`
  - 14 passed, 65 assertions
- `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec384BaselineSubjectResolutionSmokeTest.php --filter BaselineSubjectResolution`
  - 1 passed, 21 assertions
- `cd apps/platform && ./vendor/bin/sail bin pint --format agent app/Filament/Pages/BaselineSubjectResolution.php app/Services/Baselines/BaselineSubjectResolutionQuery.php tests/Feature/Baselines/Support/BaselineSubjectResolutionFixtures.php tests/Feature/Filament/BaselineSubjectResolutionPageTest.php tests/Unit/Support/Baselines/BaselineSubjectResolutionQueryTest.php tests/Browser/Spec384BaselineSubjectResolutionSmokeTest.php`
- Untracked Spec-384 whitespace check passed.

Residual non-Spec-384 failures:

- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines tests/Feature/ProviderResources`
  - 187 passed, 4 skipped, 4 failed.
  - Failures are in existing baseline capture/compare tests outside the new page/query/action code:
    - `BaselineCaptureAmbiguousMatchGapTest` expected partial success, got succeeded.
    - `BaselineCaptureGapClassificationTest` expected capture gap reason counts.
    - `BaselineCompareFindingsTest` expected 3 total counts, got 4.
    - `BaselineCompareStrategySelectionTest` calls missing `BaselineSnapshotIdentity::subjectKey()`.

- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php`
  - Spec 384 page declaration violation was fixed and no longer appears.
  - Remaining failures are existing expectations outside this feature:
    - OperationRun clickable-row URL expectation differs because the table record URL includes canonical navigation context query parameters.
    - Required Permissions page assertion expects `Start verification`, which the rendered page did not contain.

## Browser Smoke Evidence

Browser smoke result: PASS

Route: `/admin/workspaces/{workspace}/environments/{environment}/baseline-subject-resolution?operation_run_id={run}`

Context: seeded workspace manager/owner with one baseline compare run containing an actionable duplicate-candidate subject.

Steps: smoke-login redirect to page, verify environment/worklist/action text, open `Bind subject` modal, verify TenantPilot-only/no-provider-mutation copy, resize to narrow viewport and verify no horizontal overflow.

Screenshots:

- `specs/384-baseline-subject-resolution-ui/artifacts/screenshots/spec384-01-baseline-subject-resolution.png`
- `specs/384-baseline-subject-resolution-ui/artifacts/screenshots/spec384-02-baseline-subject-resolution-bind-modal.png`
- `specs/384-baseline-subject-resolution-ui/artifacts/screenshots/spec384-03-baseline-subject-resolution-mobile.png`

## Deployment Impact

- Migrations: none.
- Environment variables: none.
- Queue/cron workers: no new workers or schedules. Existing queue workers should be restarted during normal deployment so baseline compare rerun paths use current code.
- Storage/volumes: no runtime storage changes. Browser screenshots are test/spec artifacts only.
- Dokploy/Staging: validate the new page on Staging with a seeded or real baseline compare run before production promotion because it exposes high-impact admin decisions.