TenantAtlas/specs/351-review-output-resolve-actions-v1/repo-truth-map.md

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