TenantAtlas/specs/350-operator-resolution-guidance-framework-v1/plan.md

# Implementation Plan: Spec 350 - Operator Resolution Guidance Framework v1

**Branch**: `350-operator-resolution-guidance-framework-v1` | **Date**: 2026-06-03 | **Spec**: `specs/350-operator-resolution-guidance-framework-v1/spec.md`  
**Input**: User-provided Spec 350 draft + repo truth from existing output guidance, operator explanation, next-step, provider readiness, and governance inbox paths.

## Summary

Introduce one bounded derived `ResolutionCase` / `ResolutionAction` contract over existing guidance-producing runtime paths so operators see the same reading direction first on review output, with optional reuse on provider-readiness or operation-follow-up consumers only when that reuse stays bounded:

1. issue
2. reason
3. impact
4. one dominant next action
5. supporting proof and source references

This slice must reuse current guidance producers instead of replacing them:

- `ReviewPackOutputResolutionGuidance`
- `OperationUxPresenter`
- `OperatorExplanationPattern`
- `EnterpriseDetailSectionFactory::primaryNextStep()`
- current Governance Inbox next-recommended-item logic
- current provider readiness and required-permissions guidance

This slice must not:

- create persistence
- create a workflow engine
- create a new provider framework
- broaden dashboard or governance surface redesigns beyond bounded consumption
- introduce AI execution

## Technical Context

- **Language/Version**: PHP 8.4.15, Laravel 12.52.x
- **Primary Dependencies**: Filament 5.2.x, Livewire 4.1.x, Pest 4, Tailwind CSS 4
- **Storage**: PostgreSQL; no schema change expected
- **Testing**: Pest Unit + Feature/Livewire + one bounded Browser smoke
- **Validation Lanes**: fast-feedback + confidence + browser
- **Target Platform**: `apps/platform` Laravel monolith, Sail-first locally
- **Project Type**: server-rendered Filament web application
- **Performance Goals**: keep derivation DB-only and scoped; no new remote calls during render; no new queue family
- **Constraints**: reuse-first, no new persistence, no fake actions, no hidden scope, no provider-semantic bleed into the core contract, no third parallel explanation framework
- **Scale/Scope**: one support-layer contract, one required review-output adapter, up to two optional bounded adapters if a concrete same-slice consumer exists, one reusable rendering path if required, first visible rollout on review-output surfaces, optional bounded follow-through on other surfaces

## UI / Surface Guardrail Plan

- **Guardrail scope**: strategic operator and customer-safe surfaces with existing guidance islands
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - `/admin/reviews/workspace`
  - Environment Review detail
  - existing Governance Inbox top recommendation only if consumed
  - existing provider readiness / required-permissions summary only if consumed
  - existing environment dashboard readiness / recommendation cards only if consumed
- **No-impact class, if applicable**: N/A
- **Native vs custom classification summary**: native Filament page/resource/detail surfaces plus existing Blade composition; no new route family or panel/provider work expected
- **Shared-family relevance**: review/output guidance, next recommended action, readiness cards, proof links, provider readiness guidance
- **State layers in scope**: page, detail, URL-query, derived request-scoped support-layer contract
- **Audience modes in scope**: customer-safe reader, operator-MSP, manager, support where already authorized
- **Decision/diagnostic/raw hierarchy plan**: issue, reason, impact, primary action first; technical/source/proof details second; raw/support detail stays source-owned and gated
- **Raw/support gating plan**: preserve current raw/support gating on source surfaces and avoid moving raw detail into the shared contract
- **One-primary-action / duplicate-truth control**: the new contract owns only the dominant case/action summary; downstream sections add proof, not a second headline
- **Handling modes by drift class or surface**: review-mandatory
- **Repository-signal treatment**: review-mandatory because the feature adds a shared contract over existing strategic surfaces
- **Special surface test profiles**: `global-context-shell` + `shared-detail-family` + bounded strategic smoke
- **Required tests or manual smoke**: focused unit/feature tests plus one browser smoke for first-screen review-output guidance
- **Exception path and spread control**: if a proposed consumer needs a broader redesign, stop and keep that consumer out of Spec 350
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage
- **UI/Productization coverage decision**: update only the existing relevant page reports for actually touched surfaces, and resolve `UI-040` / `UI-077` registry obligations through the existing audit files (`page-reports`, `unresolved-pages`, and related registry files) rather than inventing a new taxonomy

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**:
  - `App\Support\ReviewPacks\ReviewPackOutputResolutionGuidance`
  - `App\Support\OpsUx\OperationUxPresenter`
  - `App\Support\Ui\OperatorExplanation\OperatorExplanationPattern`
  - `App\Support\Ui\EnterpriseDetail\EnterpriseDetailSectionFactory`
  - `App\Filament\Pages\Reviews\CustomerReviewWorkspace`
  - `App\Filament\Resources\EnvironmentReviewResource`
  - `App\Filament\Pages\Governance\GovernanceInbox`
  - `App\Support\EnvironmentDashboard\EnvironmentDashboardSummaryBuilder`
  - `App\Support\Providers\TargetScope\ProviderConnectionSurfaceSummary`
  - `App\Filament\Pages\EnvironmentRequiredPermissions`
- **Shared abstractions reused**:
  - current review/output readiness mapping
  - current run-detail operator guidance and next-step text
  - current operator explanation / enterprise-detail decision zone semantics
  - current scoped route helpers and `OperationRunLinks`
- **New abstraction introduced? why?**: yes, one bounded resolution-case/action contract is justified because multiple real guidance families now exist and already drift in shape, but the required v1 proof remains review-output first
- **Why the existing abstraction was sufficient or insufficient**: each current producer solves its local problem well, but no existing contract standardizes source refs, explicit scope, one action, and safe non-executable defaults across those producers
- **Bounded deviation / spread control**: do not replace `OperatorExplanationPattern`, `ReviewPackOutputResolutionGuidance`, or `OperationUxPresenter`; wrap them

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: only deep-link and follow-up guidance normalization
- **Central contract reused**: `OperationRunLinks`, existing proof URLs, and `OperationUxPresenter`
- **Delegated UX behaviors**: unchanged queue/terminal behavior
- **Surface-owned behavior kept local**: case ranking and grouped supporting details
- **Queued DB-notification policy**: unchanged
- **Terminal notification path**: unchanged
- **Exception path**: none

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes
- **Provider-owned seams**: verification, required permissions, consent/credential readiness detail
- **Platform-core seams**: cross-surface case/action contract, scope, source refs, severity/status/action typing
- **Neutral platform terms / contracts preserved**: provider, environment, evidence basis, operation, resolution case, resolution action
- **Retained provider-specific semantics and why**: provider-owned adapters may still surface provider permission or verification labels because those surfaces already are provider-owned
- **Bounded extraction or follow-up path**: any deeper provider readiness redesign becomes a follow-up spec, not hidden scope

## Current Repo Truth Summary

- `ReviewPackOutputResolutionGuidance` already returns a rich derived structure: state, label, primary reason, impact, qualified download label, limitations, primary action, secondary actions, and technical details.
- `CustomerReviewWorkspace` already consumes that guidance and is the best first visible consumer for a generalized contract, but it also contains repo-real findings and accepted-risk follow-up overrides that must remain authoritative.
- `EnvironmentReviewResource` already exposes output-guidance state and qualified download wording on detail, and the customer-workspace detail mode intentionally suppresses repeated action rails.
- `OperationUxPresenter::surfaceGuidance()` already produces dominant follow-up text, and `OperationRunResource` plus enterprise-detail helpers already model a `primaryNextStep` shape.
- `GovernanceInbox` already has a repo-real first-viewport `Next recommended action`, but it is lane/page-specific and not a general case envelope.
- `ProviderConnectionSurfaceSummary` already distills provider readiness to a summary, while `EnvironmentRequiredPermissions` already exposes guidance, next-step links, and verification follow-through on a dedicated page.
- `EnvironmentDashboardSummaryBuilder` already builds readiness and recommended-action cards that can act as a later bounded consumer if the new contract remains thin.
- No repo-real cross-surface contract currently combines explicit scope, one primary action, safe non-executable defaults, source refs, and secondary proof across the current guidance families.

## Implementation Approach

### Phase 0 - Repo Truth Gate

1. Re-read `spec.md`, `plan.md`, `tasks.md`, `repo-truth-map.md`, and the contract docs before runtime changes.
2. Re-verify the current guidance producers in:
   - `apps/platform/app/Support/ReviewPacks/ReviewPackOutputResolutionGuidance.php`
   - `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`
   - `apps/platform/app/Support/Ui/OperatorExplanation/OperatorExplanationPattern.php`
   - `apps/platform/app/Support/Ui/EnterpriseDetail/EnterpriseDetailSectionFactory.php`
   - `apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php`
   - `apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php`
   - `apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php`
3. Keep `repo-truth-map.md` current if runtime inspection changes the narrowest correct implementation.

### Phase 1 - Tests First

1. Add focused contract and adapter unit tests before implementation:
   - `apps/platform/tests/Unit/ResolutionGuidance/Spec350ResolutionCaseContractTest.php`
   - `apps/platform/tests/Unit/ResolutionGuidance/Spec350ReviewPackResolutionAdapterTest.php`
   - optional: `apps/platform/tests/Unit/ResolutionGuidance/Spec350ProviderReadinessResolutionAdapterTest.php`
   - optional: `apps/platform/tests/Unit/ResolutionGuidance/Spec350OperationFollowUpResolutionAdapterTest.php`
2. Add focused first-consumer tests:
   - `apps/platform/tests/Feature/Filament/Spec350CustomerReviewWorkspaceGuidanceIntegrationTest.php`
   - `apps/platform/tests/Feature/EnvironmentReview/Spec350EnvironmentReviewResolutionGuidanceTest.php`
3. Add one bounded browser smoke:
   - `apps/platform/tests/Browser/Spec350OperatorResolutionGuidanceSmokeTest.php`
4. Extend or reuse Spec 347/349 regressions rather than duplicating them wholesale, and pull in Spec 346 only if a Governance Inbox consumer or inbox-facing shared helper is adopted.

### Phase 2 - Core Contract

1. Choose the narrowest implementation shape:
   - prefer rigorously validated arrays if they fit the current support-layer style, or
   - use small readonly value objects under `app/Support/ResolutionGuidance/` only if they reduce review risk without creating a new framework layer
2. Define:
   - `ResolutionCase`
   - `ResolutionAction`
   - presentation-only severity/status/action-type vocabularies only if plain strings/constants prove insufficient
3. Keep the contract derived-only and request-scoped.
4. Do not persist or cache the new cases beyond the current request unless an existing request-scoped pattern is already in place.

### Phase 3 - Bounded Adapters

1. Review-pack output adapter:
   - wrap `ReviewPackOutputResolutionGuidance`
   - preserve current output/readiness truth
   - add explicit scope, source refs, and safe action typing
   - keep evidence-basis guidance inside this adapter for v1 instead of adding a standalone evidence adapter
2. Preserve current review-output exceptions:
   - keep `CustomerReviewWorkspace` findings/accepted-risk follow-up overrides authoritative
   - keep customer-workspace detail mode on `EnvironmentReviewResource` free of repeated primary-action rails

### Phase 4 - Rendering And Required First Consumers

1. Add one reusable rendering path only if it reduces real duplication:
   - e.g. `resolution-guidance-card.blade.php` and list wrapper
2. Required first consumers:
   - `CustomerReviewWorkspace`
   - Environment Review detail
3. Preserve current review-output behavior while adopting the shared contract:
   - do not regress qualified download wording
   - do not regress findings/accepted-risk follow-up overrides
   - do not regress customer-workspace detail-mode CTA suppression

### Phase 5 - Optional Additional Adapters And Consumers

1. Provider readiness adapter, only if an in-scope consumer can adopt it without a broader redesign:
   - wrap current provider surface summary, verification state, and required-permissions guidance
   - keep provider-specific detail inside the adapter, not the core contract
2. Operation follow-up adapter, only if an in-scope consumer can adopt it without a broader redesign:
   - wrap current operation follow-up text and explanation
   - enrich with scope, proof links, and stable action typing
3. Optional bounded consumers:
   - Governance Inbox top recommendation
   - provider readiness / required-permissions summary
   - environment dashboard readiness/recommended-action cards
4. If any optional adapter or consumer requires a broader local taxonomy or layout rewrite, keep it out of Spec 350.

### Phase 6 - Copy, Audit, And Browser Proof

1. Update only the required copy keys in the existing localization files.
2. Update the existing relevant UI audit page reports for touched surfaces.
3. Resolve `UI-040` in the current audit registry by updating `unresolved-pages.md` unless a dedicated review-detail report is added in the implementation PR.
4. If `UI-077` is touched through a required-permissions consumer, update the current provider/support registry artifacts instead of assuming `ui-009` alone is sufficient.
5. Capture screenshots under `specs/350-operator-resolution-guidance-framework-v1/artifacts/screenshots/`.
6. Keep technical details collapsed or clearly secondary in the rendered consumers.

### Phase 7 - Validation And Close-Out

1. Run focused Spec 350 tests.
2. Run bounded browser smoke.
3. Re-run filtered regressions for Specs 347/349, plus Spec 346 only if a Governance Inbox consumer or inbox-facing shared helper is adopted.
4. Run `pint --dirty` and `git diff --check`.
5. Report any out-of-scope failures separately without widening implementation scope.

## Validation Plan

```bash
cd apps/platform
./vendor/bin/sail php vendor/bin/pest tests/Unit/ResolutionGuidance/Spec350ResolutionCaseContractTest.php tests/Unit/ResolutionGuidance/Spec350ReviewPackResolutionAdapterTest.php --compact
./vendor/bin/sail artisan test tests/Feature/Filament/Spec350CustomerReviewWorkspaceGuidanceIntegrationTest.php tests/Feature/EnvironmentReview/Spec350EnvironmentReviewResolutionGuidanceTest.php --compact
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec350OperatorResolutionGuidanceSmokeTest.php --compact
./vendor/bin/sail artisan test --compact --filter=Spec347
./vendor/bin/sail artisan test --compact --filter=Spec349
./vendor/bin/sail artisan test --compact --filter=CustomerReviewWorkspace
./vendor/bin/sail pint --dirty
git diff --check
```

Add `./vendor/bin/sail artisan test --compact --filter=Spec346` only if a Governance Inbox consumer or inbox-facing shared helper is actually adopted in-scope. Add optional provider-readiness or operation-follow-up unit tests, plus any optional consumer regressions, only if those adapters or consumers are actually adopted in-scope.

## Deployment Impact

- **Env vars**: none expected
- **Migrations**: none
- **Queues / scheduler**: none
- **Storage**: none
- **Assets**: no new Filament asset registration expected; `filament:assets` is not newly required by this slice