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