ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/350-operator-resolution-guidance-framework-v1/plan.md
ahmido 4cf2712f92 feat: operator resolution guidance framework v1 (spec 350) (#421) 
Implemented the first version of the operator resolution guidance framework. Added new foundation classes (ResolutionCase, ResolutionAction) and a ReviewPackOutputResolutionAdapter. Updated the Customer Review Workspace and Environment Review Resource to use the new adapter. Added extensive test coverage for the framework and UI integrations.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #421
2026-06-03 15:35:25 +00:00

16 KiB
Raw Permalink Blame History

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

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