a6ff903093
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 3m45s
Implemented the first version of review output resolve actions. Included a ReviewOutputResolveActionMapper, commands to seed browser fixtures, updated CustomerReviewWorkspace, EnvironmentReviewResource, UI enforcement, and related views. Also added extensive unit, feature, and browser tests, and updated the design coverage matrix.
163 lines
6.9 KiB
Markdown
163 lines
6.9 KiB
Markdown
# Repo Truth Map: Spec 351 - Review Output Resolve Actions v1
|
|
|
|
**Status**: preparation context
|
|
**Updated**: 2026-06-03
|
|
**Feature**: `specs/351-review-output-resolve-actions-v1/spec.md`
|
|
|
|
## Scope Boundary
|
|
|
|
This prep is intentionally limited to review-output resolution actions on:
|
|
|
|
- `CustomerReviewWorkspace`
|
|
- Environment Review detail
|
|
|
|
Deferred from this prep:
|
|
|
|
- Governance Inbox reuse
|
|
- Provider readiness / required permissions reuse
|
|
- Environment dashboard reuse
|
|
- Portal / PDF / PSA / AI follow-up
|
|
|
|
## Existing Review-Output Derivation Path
|
|
|
|
Current review-output truth flows through:
|
|
|
|
1. `App\Support\ReviewPacks\ReviewPackOutputReadiness`
|
|
2. `App\Support\ReviewPacks\ReviewPackOutputResolutionGuidance`
|
|
3. `App\Support\ResolutionGuidance\Adapters\ReviewPackOutputResolutionAdapter`
|
|
4. first consumers:
|
|
- `App\Filament\Pages\Reviews\CustomerReviewWorkspace`
|
|
- `App\Filament\Resources\EnvironmentReviewResource`
|
|
|
|
What this already solves:
|
|
|
|
- derives output state, limitation list, impact, and qualified download wording
|
|
- derives a `ResolutionCase` envelope for review output
|
|
- keeps findings and accepted-risk follow-up overrides on the workspace
|
|
- keeps customer-workspace detail mode free of duplicate CTA rails
|
|
|
|
What it does **not** yet solve:
|
|
|
|
- deterministic selection of repo-backed review lifecycle actions as the dominant next step
|
|
- execution of those actions from the workspace decision card
|
|
- safe distinction between executable action, honest fallback navigation, and disclosure-only action
|
|
|
|
## Existing Repo-Backed Review Lifecycle Actions
|
|
|
|
### Environment Review detail
|
|
|
|
`App\Filament\Resources\EnvironmentReviewResource\Pages\ViewEnvironmentReview`
|
|
|
|
- `refresh_review`
|
|
- label from `GovernanceActionCatalog::rule('refresh_review')`
|
|
- service: `EnvironmentReviewService::refresh()`
|
|
- confirmation: yes
|
|
- capability: `Capabilities::ENVIRONMENT_REVIEW_MANAGE`
|
|
- audit: yes (`EnvironmentReviewRefreshed`)
|
|
- `OperationRun`: yes, via existing review composition flow
|
|
|
|
- `publish_review`
|
|
- label from `GovernanceActionCatalog::rule('publish_review')`
|
|
- service: `EnvironmentReviewLifecycleService::publish()`
|
|
- confirmation: yes
|
|
- capability: `Capabilities::ENVIRONMENT_REVIEW_MANAGE`
|
|
- audit: yes (`EnvironmentReviewPublished`)
|
|
- `OperationRun`: no new run; publish is an audited lifecycle state transition
|
|
|
|
- `create_next_review`
|
|
- label: `Create next review`
|
|
- service: `EnvironmentReviewLifecycleService::createNextReview()`
|
|
- confirmation: **no current confirmation**
|
|
- capability: `Capabilities::ENVIRONMENT_REVIEW_MANAGE`
|
|
- audit: yes (`EnvironmentReviewSuccessorCreated`)
|
|
- `OperationRun`: indirectly yes through `EnvironmentReviewService::create()` / queued composition of the successor review
|
|
|
|
### Evidence detail
|
|
|
|
`App\Filament\Resources\EvidenceSnapshotResource\Pages\ViewEvidenceSnapshot`
|
|
|
|
- `refresh_evidence`
|
|
- service: `EvidenceSnapshotService::refresh()`
|
|
- confirmation: yes
|
|
- capability: `Capabilities::EVIDENCE_MANAGE`
|
|
- audit / queue semantics: evidence-owned and already repo-real
|
|
|
|
This matters because Spec 351 may use `Open evidence basis` as the primary review-output fallback, while `Refresh evidence` remains optional unless a safe review-surface reuse path is proven.
|
|
|
|
## Existing Workspace-Side Executable Action Pattern
|
|
|
|
`App\Filament\Pages\Reviews\CustomerReviewWorkspace`
|
|
|
|
- already defines a real Filament page action: `acknowledgeReviewAction()`
|
|
- the Blade view already mounts actions via `wire:click="mountAction(...)"`
|
|
- the Blade view already includes `<x-filament-actions::modals />`
|
|
|
|
Repo-truth implication:
|
|
|
|
- workspace-side execution of bounded review actions is feasible without inventing a second action system
|
|
- implementation should prefer source-owned Filament page actions plus existing services and modal patterns
|
|
- direct service calls from Blade are unnecessary and should remain forbidden
|
|
|
|
## Current Detail-Surface Constraint
|
|
|
|
`apps/platform/resources/views/filament/infolists/entries/review-pack-output-guidance.blade.php`
|
|
|
|
- current guidance card renders only URL-based buttons
|
|
- normal Environment Review detail already has header lifecycle actions
|
|
- customer-workspace detail mode suppresses action buttons inside the guidance card and shows context note only
|
|
|
|
Repo-truth implication:
|
|
|
|
- Spec 351 must avoid duplicate primary CTA rails on detail
|
|
- the detail requirement can be satisfied by aligning the guidance card next-step semantics to the existing dominant header action instead of adding a second equal-weight execution button
|
|
|
|
## Draft / Successor Semantics
|
|
|
|
`App\Services\EnvironmentReviews\EnvironmentReviewLifecycleService::createNextReview()`
|
|
|
|
- only published reviews can start the next cycle
|
|
- the service creates or reuses a mutable successor review through `EnvironmentReviewService::create()`
|
|
- when a new successor review is created, the published review becomes `superseded`
|
|
- the source review stores `superseded_by_review_id`
|
|
|
|
Repo-truth implication:
|
|
|
|
- a generic "Open existing draft review" action is not currently a standalone workspace helper
|
|
- it is only repo-real when a concrete successor review target is already known, for example via `superseded_by_review_id` or another deterministic lookup proven at implementation time
|
|
- the workspace must not fabricate this action from a purely conceptual draft state
|
|
|
|
## Authorization And Surface Availability
|
|
|
|
- `CustomerReviewWorkspace` is visible to entitled viewers, including readonly roles
|
|
- `EnvironmentReviewResource::outputGuidanceState()` already capability-gates evidence links
|
|
- mutating review actions require `Capabilities::ENVIRONMENT_REVIEW_MANAGE`
|
|
- evidence refresh requires `Capabilities::EVIDENCE_MANAGE`
|
|
- current review-output guidance does not yet differentiate actionable mutation from honest fallback by viewer capability
|
|
|
|
Repo-truth implication:
|
|
|
|
- action mapping must consider both repo-backed behavior **and** current actor/surface execution availability
|
|
- readonly viewers on the workspace should see truthful fallback navigation/disclosure instead of fake enabled mutation buttons
|
|
|
|
## Confirmed Deviations From The User Draft
|
|
|
|
- The repo already has `Create next review`, `Refresh review`, and `Publish review`; Spec 351 does not need to invent those actions.
|
|
- The repo does **not** currently have a generic workspace-level "Open draft review" resolver.
|
|
- The repo already has a safe evidence-refresh action, but it lives on evidence detail, not on current review-output surfaces.
|
|
- `create_next_review` is repo-real but lacks confirmation today; surfacing it more prominently makes that gap visible and must be handled intentionally.
|
|
|
|
## Preparation Decision
|
|
|
|
Spec 351 should implement:
|
|
|
|
- one review-output-only resolve-action mapper
|
|
- one bounded workspace execution bridge through Filament page actions
|
|
- one non-duplicative detail alignment path
|
|
|
|
It should not implement:
|
|
|
|
- a new action framework
|
|
- generic draft discovery
|
|
- provider/dashboard/governance reuse
|
|
- a second lifecycle runtime outside existing source-owned services and actions
|