ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
9e435ea91f
TenantAtlas/specs/351-review-output-resolve-actions-v1/repo-truth-map.md
ahmido d4e4d2d109 feat: review output resolve actions v1 (spec 351) (#422) 
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.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #422
2026-06-04 00:55:02 +00:00

6.9 KiB
Raw Blame History

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