02cc12f73f
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 59s
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.
242 lines
16 KiB
Markdown
242 lines
16 KiB
Markdown
# 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
|