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

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

• Lane assignment is explicit and narrow: Unit for contract/adapters, Feature for surface integration, Browser for first-screen trust proof.
• New or changed tests stay in the smallest honest family, and the browser addition is explicit.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
• Planned validation commands cover the change without pulling unrelated lane cost.
• The declared surface profiles (global-context-shell and shared-detail-family) are explicit.
• 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.

• T001 Re-read spec.md, plan.md, repo-truth-map.md, all contract docs, and checklists/requirements.md before runtime changes.
• T002 Re-read related historical context only: Specs 161, 312, 338, 346, 347, and 349. Do not modify their artifacts.
• T003 Re-verify the current runtime truth in apps/platform/app/Support/ReviewPacks/ReviewPackOutputResolutionGuidance.php.
• T004 Re-verify the current runtime truth in apps/platform/app/Support/OpsUx/OperationUxPresenter.php.
• 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.
• T006 Re-verify the current runtime truth in apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php and apps/platform/app/Filament/Resources/EnvironmentReviewResource.php.
• 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.
• T008 Keep specs/350-operator-resolution-guidance-framework-v1/repo-truth-map.md current if runtime inspection reveals a narrower or broader bounded truth.
• T009 Confirm no migration, package, env var, queue family, scheduler change, storage-topology change, panel/provider change, or global-search change is required.
• 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.

• T011 Add apps/platform/tests/Unit/ResolutionGuidance/Spec350ResolutionCaseContractTest.php.
• 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.
• T015 Add apps/platform/tests/Feature/Filament/Spec350CustomerReviewWorkspaceGuidanceIntegrationTest.php.
• T016 Add apps/platform/tests/Feature/EnvironmentReview/Spec350EnvironmentReviewResolutionGuidanceTest.php.
• T017 Add apps/platform/tests/Browser/Spec350OperatorResolutionGuidanceSmokeTest.php.
• T018 Add assertions that every case has explicit scope, source refs, evidence refs where applicable, exactly one primary action, and no fake execution paths.
• 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.
• 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.

• 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.
• T025 Ensure the contract stays derived-only and request-scoped; do not add persistence or request-crossing cache behavior.
• T026 Ensure the contract carries explicit scope, one primary action, secondary actions, source refs, evidence refs where applicable, and technical-detail disclosure payloads.
• T027 Ensure the contract shape can wrap existing ReviewPackOutputResolutionGuidance, OperationUxPresenter, OperatorExplanationPattern, and primaryNextStep semantics without replacing them.
• 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.

• T029 Create apps/platform/app/Support/ResolutionGuidance/Adapters/ReviewPackOutputResolutionAdapter.php.
• T030 Wrap ReviewPackOutputResolutionGuidance so review-output cases expose explicit scope, source refs, evidence refs, and safe action typing.
• T031 Keep evidence-basis guidance inside the review-output adapter for v1; do not introduce a standalone EvidenceBasisResolutionAdapter.
• T032 Keep published-versus-draft review immutability and next-step rules aligned with current repo truth and current customer-workspace/detail behavior.
• T033 Preserve current CustomerReviewWorkspace findings-follow-up and accepted-risk follow-up overrides instead of flattening them into the shared contract.
• T034 Preserve current customer-workspace detail-mode CTA suppression in EnvironmentReviewResource.
• 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.
• 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.
• T046 Update apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php so the first decision block renders the shared case shape.
• 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.
• 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.
• 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.

• 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.
• T054 Update matching keys in apps/platform/lang/de/localization.php when new copy is actually required; existing copy remained sufficient in this slice.
• T055 Update docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md for the required first consumer changes.
• 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.
• 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.

• T060 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Unit/ResolutionGuidance/Spec350ResolutionCaseContractTest.php tests/Unit/ResolutionGuidance/Spec350ReviewPackResolutionAdapterTest.php --compact.
• T061 Run cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec350CustomerReviewWorkspaceGuidanceIntegrationTest.php tests/Feature/EnvironmentReview/Spec350EnvironmentReviewResolutionGuidanceTest.php --compact.
• 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.
• T064 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec347.
• T065 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec349.
• 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.
• 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.