# Tasks: Spec 350 - Operator Resolution Guidance Framework v1

**Input**: `specs/350-operator-resolution-guidance-framework-v1/spec.md`, `plan.md`, `repo-truth-map.md`, `contracts/`, and `checklists/requirements.md`

**Tests**: Required. This is a cross-surface operator-guidance and trust-surface change over existing Filament pages, detail surfaces, and support-layer guidance producers.

## Test Governance Checklist

- [x] Lane assignment is explicit and narrow: Unit for contract/adapters, Feature for surface integration, Browser for first-screen trust proof.
- [x] New or changed tests stay in the smallest honest family, and the browser addition is explicit.
- [x] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
- [x] Planned validation commands cover the change without pulling unrelated lane cost.
- [x] The declared surface profiles (`global-context-shell` and `shared-detail-family`) are explicit.
- [x] Any new abstraction remains derived-only and does not create hidden persistence or a workflow engine.

## Phase 1: Preparation And Repo Truth

**Purpose**: Keep the implementation bounded to the existing guidance-producing runtime paths and prevent a third parallel framework.

- [x] T001 Re-read `spec.md`, `plan.md`, `repo-truth-map.md`, all contract docs, and `checklists/requirements.md` before runtime changes.
- [x] T002 Re-read related historical context only: Specs 161, 312, 338, 346, 347, and 349. Do not modify their artifacts.
- [x] T003 Re-verify the current runtime truth in `apps/platform/app/Support/ReviewPacks/ReviewPackOutputResolutionGuidance.php`.
- [x] T004 Re-verify the current runtime truth in `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`.
- [x] T005 Re-verify the current runtime truth in `apps/platform/app/Support/Ui/OperatorExplanation/OperatorExplanationPattern.php` and `apps/platform/app/Support/Ui/EnterpriseDetail/EnterpriseDetailSectionFactory.php`.
- [x] T006 Re-verify the current runtime truth in `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` and `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php`.
- [x] T007 Re-verify the current runtime truth in `apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php`, `apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php`, `apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php`, and `apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php`.
- [x] T008 Keep `specs/350-operator-resolution-guidance-framework-v1/repo-truth-map.md` current if runtime inspection reveals a narrower or broader bounded truth.
- [x] T009 Confirm no migration, package, env var, queue family, scheduler change, storage-topology change, panel/provider change, or global-search change is required.
- [x] T010 Confirm Filament v5 / Livewire v4.0+ compliance and that panel provider registration remains `apps/platform/bootstrap/providers.php`.

## Phase 2: Tests First

**Purpose**: Lock the central contract, adapter semantics, and first visible consumers before runtime refactor.

- [x] T011 Add `apps/platform/tests/Unit/ResolutionGuidance/Spec350ResolutionCaseContractTest.php`.
- [x] T012 Add `apps/platform/tests/Unit/ResolutionGuidance/Spec350ReviewPackResolutionAdapterTest.php`.
- [ ] T013 Only if a provider-readiness adapter is adopted in-scope, add `apps/platform/tests/Unit/ResolutionGuidance/Spec350ProviderReadinessResolutionAdapterTest.php`.
- [ ] T014 Only if an operation-follow-up adapter is adopted in-scope, add `apps/platform/tests/Unit/ResolutionGuidance/Spec350OperationFollowUpResolutionAdapterTest.php`.
- [x] T015 Add `apps/platform/tests/Feature/Filament/Spec350CustomerReviewWorkspaceGuidanceIntegrationTest.php`.
- [x] T016 Add `apps/platform/tests/Feature/EnvironmentReview/Spec350EnvironmentReviewResolutionGuidanceTest.php`.
- [x] T017 Add `apps/platform/tests/Browser/Spec350OperatorResolutionGuidanceSmokeTest.php`.
- [x] T018 Add assertions that every case has explicit scope, source refs, evidence refs where applicable, exactly one primary action, and no fake execution paths.
- [x] T019 Add assertions that executable actions are modeled only when a source-owned safety envelope exists, otherwise they degrade to navigation, qualified download, disclosure, or `none`.
- [x] T020 Reuse or extend existing Spec 347/349 regressions instead of duplicating their full runtime coverage; pull in Spec 346 only if a Governance Inbox consumer or inbox-facing shared helper is adopted.

## Phase 3: Core Contract

**Purpose**: Introduce the narrowest shared case/action envelope that can wrap the existing guidance producers.

- [x] T021 Choose the narrowest contract shape under `apps/platform/app/Support/ResolutionGuidance/`, preferring validated arrays unless small readonly value objects clearly reduce review risk.
- [ ] T022 If value objects are the narrowest shape, create `apps/platform/app/Support/ResolutionGuidance/ResolutionCase.php`.
- [ ] T023 If value objects are the narrowest shape, create `apps/platform/app/Support/ResolutionGuidance/ResolutionAction.php`.
- [ ] T024 Only add presentation-only supporting enums/value objects for severity, status, or action type if plain strings/constants prove insufficient.
- [x] T025 Ensure the contract stays derived-only and request-scoped; do not add persistence or request-crossing cache behavior.
- [x] T026 Ensure the contract carries explicit scope, one primary action, secondary actions, source refs, evidence refs where applicable, and technical-detail disclosure payloads.
- [x] T027 Ensure the contract shape can wrap existing `ReviewPackOutputResolutionGuidance`, `OperationUxPresenter`, `OperatorExplanationPattern`, and `primaryNextStep` semantics without replacing them.
- [x] T028 Add validation/mapping tests proving unsupported or unsafe executable actions degrade to navigation, qualified download, disclosure, or `none`.

## Phase 4: Review-Pack Adapter And Review-Output Guardrails

**Purpose**: Reuse the existing review-output guidance work and extend it into the shared contract without reopening Spec 347 or Spec 349 truth.

- [x] T029 Create `apps/platform/app/Support/ResolutionGuidance/Adapters/ReviewPackOutputResolutionAdapter.php`.
- [x] T030 Wrap `ReviewPackOutputResolutionGuidance` so review-output cases expose explicit scope, source refs, evidence refs, and safe action typing.
- [x] T031 Keep evidence-basis guidance inside the review-output adapter for v1; do not introduce a standalone `EvidenceBasisResolutionAdapter`.
- [x] T032 Keep published-versus-draft review immutability and next-step rules aligned with current repo truth and current customer-workspace/detail behavior.
- [x] T033 Preserve current `CustomerReviewWorkspace` findings-follow-up and accepted-risk follow-up overrides instead of flattening them into the shared contract.
- [x] T034 Preserve current customer-workspace detail-mode CTA suppression in `EnvironmentReviewResource`.
- [x] T035 Add focused tests for blocked published review, draft-refresh path, evidence-missing path, follow-up override behavior, and safe disclosure fallback.

## Phase 5: Optional Provider And Operation Adapters

**Purpose**: Standardize provider-readiness and operation-follow-up guidance only if a concrete same-slice consumer can adopt them without rebuilding those domains.

- [ ] T036 Only if a provider-readiness consumer is adopted in-scope, create `apps/platform/app/Support/ResolutionGuidance/Adapters/ProviderReadinessResolutionAdapter.php`.
- [ ] T037 If the provider adapter is adopted, wrap existing provider summary, required-permissions, verification, and provider-owned next-step truth without inventing a new provider readiness engine.
- [ ] T038 If the provider adapter is adopted, keep provider-specific terms and permission details inside the provider adapter and provider surfaces, not in the core contract.
- [ ] T039 Only if an operation-follow-up consumer is adopted in-scope, create `apps/platform/app/Support/ResolutionGuidance/Adapters/OperationFollowUpResolutionAdapter.php`.
- [ ] T040 If the operation adapter is adopted, wrap `OperationUxPresenter`, existing proof links, and operator explanation truth into explicit follow-up cases with safe action typing.
- [ ] T041 If the operation adapter is adopted, ensure operation-follow-up cases do not change queueing, dedupe, terminal notification, or run lifecycle behavior.
- [ ] T042 Only if optional adapters are adopted, add focused tests for provider gaps or operation follow-up plus proof-link-based fallback behavior.

## Phase 6: Rendering And First Consumers

**Purpose**: Apply the shared contract where it already has the strongest repo-real value and keep broader rollout bounded.

- [ ] T043 Create `apps/platform/resources/views/components/resolution-guidance-card.blade.php` only if it reduces real duplication across the first consumers.
- [ ] T044 Create `apps/platform/resources/views/components/resolution-guidance-list.blade.php` only if the list wrapper reduces duplication without creating a new global UI framework.
- [x] T045 Update `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` to consume the shared contract via the review-output adapter without regressing current follow-up overrides.
- [x] T046 Update `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php` so the first decision block renders the shared case shape.
- [x] T047 Update `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php` to expose the shared case shape for output guidance and qualified download behavior while preserving customer-workspace detail mode.
- [x] T048 Update `apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php` or its supporting state so the detail surface uses the same case/action reading direction without reintroducing repeated primary-action rails.
- [x] T049 Keep technical details collapsed or clearly secondary in the first visible consumers.
- [ ] T050 Only if reuse remains bounded, integrate the same contract into the Governance Inbox top recommendation without replacing the existing lane model.
- [ ] T051 Only if reuse remains bounded, integrate the same contract into provider readiness or required-permissions summary surfaces without redesigning the full provider surface.
- [ ] T052 Only if reuse remains bounded, integrate the same contract into environment dashboard readiness/recommended-action summaries without introducing a new dashboard taxonomy.

## Phase 7: Copy, Audit, And Browser Proof

**Purpose**: Align copy, audit artifacts, and screenshots with the shared contract.

- [x] T053 Update only the required guidance localization keys in `apps/platform/lang/en/localization.php` when new copy is actually required; existing copy remained sufficient in this slice.
- [x] T054 Update matching keys in `apps/platform/lang/de/localization.php` when new copy is actually required; existing copy remained sufficient in this slice.
- [x] T055 Update `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md` for the required first consumer changes.
- [x] T056 Resolve `UI-040` in `docs/ui-ux-enterprise-audit/unresolved-pages.md` unless a dedicated Environment Review detail report is added in the implementation PR.
- [ ] T057 If Governance Inbox is consumed, update `docs/ui-ux-enterprise-audit/page-reports/ui-004-governance-inbox.md`.
- [ ] T058 If provider readiness or required permissions is consumed, update `docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md` and any current `UI-077` registry artifact that records Required Permissions coverage.
- [x] T059 Capture screenshots under `specs/350-operator-resolution-guidance-framework-v1/artifacts/screenshots/`.

## Phase 8: Validation

**Purpose**: Prove the contract stays bounded and preserves existing trust/safety rules.

- [x] T060 Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Unit/ResolutionGuidance/Spec350ResolutionCaseContractTest.php tests/Unit/ResolutionGuidance/Spec350ReviewPackResolutionAdapterTest.php --compact`.
- [x] T061 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec350CustomerReviewWorkspaceGuidanceIntegrationTest.php tests/Feature/EnvironmentReview/Spec350EnvironmentReviewResolutionGuidanceTest.php --compact`.
- [x] T062 Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec350OperatorResolutionGuidanceSmokeTest.php --compact`.
- [ ] T063 Only if a Governance Inbox consumer or inbox-facing shared helper is adopted, run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec346`.
- [x] T064 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec347`.
- [x] T065 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec349`.
- [x] T066 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=CustomerReviewWorkspace`.
- [ ] T067 Only if optional provider-readiness or operation consumers are adopted, run their focused unit tests and any additional surface regressions.
- [x] T068 Run `cd apps/platform && ./vendor/bin/sail pint --dirty` and `git diff --check`.

## Non-Goals Checklist

- [ ] NT001 Do not create a new persisted resolution entity, table, or runtime-owned state machine.
- [ ] NT002 Do not create a workflow engine, approval engine, or queue family.
- [ ] NT003 Do not replace `ReviewPackOutputResolutionGuidance`, `OperationUxPresenter`, or `OperatorExplanationPattern` with a greenfield subsystem.
- [ ] NT004 Do not broaden dashboard, governance inbox, or provider readiness into redesign work if bounded consumption proves insufficient.
- [ ] NT005 Do not add AI execution, AI summaries, or AI-visible runtime suggestions.
- [ ] NT006 Do not weaken current workspace/environment scope, authorization, signed-download safety, or existing destructive-action safeguards.