ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/349-customer-review-workspace-output-resolution-guidance/plan.md
ahmido 9b46c0e435 feat: customer review workspace output resolution guidance (spec 349) (#420) 
Implemented the output resolution guidance for the customer review workspace and internal views. Added ReviewPackOutputResolutionGuidance, updated CustomerReviewWorkspace and EnvironmentReviewResource, and added related blade views and tests.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #420
2026-06-03 01:35:55 +00:00

14 KiB
Raw Permalink Blame History

Implementation Plan: Spec 349 - Customer Review Workspace Output Resolution Guidance

Branch: 349-customer-review-workspace-output-resolution-guidance | Date: 2026-06-03 | Spec: specs/349-customer-review-workspace-output-resolution-guidance/spec.md
Input: User-provided Spec 349 draft + repo truth from current Spec 347 readiness work, current Customer Review Workspace runtime, and current Environment Review detail surface.

Summary

Translate existing Review Pack output-readiness truth into calmer operator guidance without changing the underlying workflow model.

This slice should:

  • reuse current ReviewPackOutputReadiness truth
  • convert the highest-priority limitation into one dominant blocker and one dominant next action
  • group remaining limitations into compact disclosure
  • qualify download wording honestly
  • surface PII/internal-only boundaries explicitly
  • separate review publication/completeness from output readiness on Environment Review detail

This slice must not:

  • create persistence
  • create a new workflow engine or state machine
  • reopen Review Pack generation semantics beyond the already-completed Spec 347 contract
  • build a portal or renderer
  • weaken current authorization, workspace isolation, or signed-download safety

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 Feature/Livewire tests plus one bounded Pest Browser smoke file
  • Validation Lanes: confidence + browser
  • Target Platform: apps/platform Laravel monolith; Sail-first locally; Dokploy posture unchanged
  • Project Type: web application with server-rendered Filament/Blade surfaces
  • Performance Goals: no new remote calls during render, no new queue family, and no duplicate read-model layer beyond a bounded derived guidance adapter
  • Constraints: no false customer-safe wording, no warning wall, no hidden shell-scope behavior, no new route family, no new persisted guidance state, and no detail-surface redesign outside the output-guidance slice
  • Scale/Scope: one strategic workspace surface, one review detail surface, existing review-pack proof/download path, focused Feature coverage, and one Browser smoke

UI / Surface Guardrail Plan

  • Guardrail scope: material change to an existing strategic customer-safe review surface plus an existing review detail surface
  • Affected routes/pages/actions/states/navigation/panel/provider surfaces:
    • /admin/reviews/workspace
    • apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
    • apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
    • apps/platform/app/Filament/Resources/EnvironmentReviewResource.php
    • apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php
    • existing review-pack download wording as reached from those surfaces
  • No-impact class, if applicable: N/A
  • Native vs custom classification summary: native Filament page/resource plus existing Blade/infolist composition; no new route or panel/provider
  • Shared-family relevance: status messaging, next-action guidance, disclosure, proof links, qualified download wording
  • State layers in scope: page payload, detail payload, URL-query filter on workspace, derived output-guidance payload only
  • Audience modes in scope: operator-MSP, customer-safe review consumer, support where authorized
  • Decision/diagnostic/raw hierarchy plan: one output verdict first, grouped limitations second, technical details third
  • Raw/support gating plan: keep technical details collapsed or clearly secondary; keep support/raw detail capability-gated where already applicable
  • One-primary-action / duplicate-truth control: preserve one dominant next action and remove repeated blocker summaries from lower panels
  • Handling modes by drift class or surface: review-mandatory
  • Repository-signal treatment: review-mandatory because this is a strategic trust surface
  • Special surface test profiles: global-context-shell + shared-detail-family
  • Required tests or manual smoke: functional-core + browser smoke
  • Exception path and spread control: one bounded guidance adapter is allowed; no cross-domain framework
  • Active feature PR close-out entry: Guardrail / Smoke Coverage
  • UI/Productization coverage decision: update docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md; add a second report only if implementation proves the existing identity cannot absorb the detail-surface notes cleanly
  • Coverage artifacts to update: existing workspace page report only unless repo truth later proves more is required
  • Navigation / Filament provider-panel handling: N/A; no panel/provider change expected
  • Screenshot or page-report need: yes, because this is a strategic customer-safe surface and one bounded browser smoke will produce proof artifacts

Shared Pattern & System Fit

  • Cross-cutting feature marker: yes
  • Systems touched:
    • App\Support\ReviewPacks\ReviewPackOutputReadiness
    • App\Filament\Pages\Reviews\CustomerReviewWorkspace
    • App\Filament\Resources\EnvironmentReviewResource
    • App\Filament\Resources\EnvironmentReviewResource\Pages\ViewEnvironmentReview
    • existing review-pack and evidence link helpers
  • Shared abstractions reused:
    • current limitation codes and readiness fields from ReviewPackOutputReadiness
    • current workspace link/action helper paths
    • current Environment Review artifact-truth and summary presentation
  • New abstraction introduced? why?: maybe one narrow ReviewPackOutputResolutionGuidance-style adapter if direct extension of ReviewPackOutputReadiness would blur raw output truth and UI guidance responsibilities
  • Why the existing abstraction was sufficient or insufficient: current readiness truth is sufficient as the source, but it is not yet shaped for grouped operator guidance across multiple surfaces
  • Bounded deviation / spread control: any new guidance adapter must remain local to review output guidance and must not become a generic workflow-resolution framework

OperationRun UX Impact

  • Touches OperationRun start/completion/link UX?: existing proof-link usage only
  • Central contract reused: existing Review Pack / Environment Review proof links
  • Delegated UX behaviors: unchanged
  • Surface-owned behavior kept local: one-blocker ranking, grouped limitation copy, and qualified next-action wording
  • Queued DB-notification policy: unchanged
  • Terminal notification path: unchanged
  • Exception path: none

Provider Boundary & Portability Fit

  • Shared provider/platform boundary touched?: no new provider seam
  • Provider-owned seams: N/A
  • Platform-core seams: output readiness, customer-safe/internal-only/blocked guidance vocabulary
  • Neutral platform terms / contracts preserved: review pack, evidence basis, limitation, customer-safe, internal-only, next action
  • Retained provider-specific semantics and why: only where current review/evidence text already carries provider-backed content
  • Bounded extraction or follow-up path: none

Current Repo Truth Summary

  • App\Support\ReviewPacks\ReviewPackOutputReadiness already derives:
    • readiness_state
    • customer_safe_state
    • primary_reason
    • primary_action
    • limitations
    • section_summary
  • CustomerReviewWorkspace already folds that truth into:
    • effectiveWorkspaceReadinessState()
    • workspaceReadinessLabel()
    • workspaceReadinessReason()
    • workspaceReadinessImpact()
    • workspaceReadinessActions()
    • current decision card and proof-panel payloads
  • Current workspace gaps:
    • no grouped limitation list tied to one dominant blocker
    • no explicit technical-details disclosure contract for output guidance
    • existing primary/secondary action mapping is still spread across multiple helper methods
  • EnvironmentReviewResource / ViewEnvironmentReview already own the detail surface:
    • infolist sections for outcome summary, review, executive posture, and sections
    • customer-workspace mode that narrows header actions
    • no explicit summary block separating review publication/completeness from output-readiness/sharing state
  • Route truth is already stable and workspace/environment scoped; no new route family is needed
  • Existing page audit identity is ui-006-customer-review-workspace.md

Implementation Approach

Phase 0 - Repo Truth Gate

  1. Re-read the prepared spec.md, plan.md, tasks.md, repo-truth-map.md, and checklists/requirements.md before runtime edits.
  2. Re-check current runtime truth in:
    • apps/platform/app/Support/ReviewPacks/ReviewPackOutputReadiness.php
    • apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
    • apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php
    • apps/platform/app/Filament/Resources/EnvironmentReviewResource.php
    • apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php
  3. Keep specs/349-customer-review-workspace-output-resolution-guidance/repo-truth-map.md current if runtime inspection reveals additional bounded truth.

Phase 1 - Tests First

  1. Add focused guidance tests before runtime refactor:
    • apps/platform/tests/Feature/ReviewPack/Spec349ReviewPackResolutionGuidanceTest.php
    • apps/platform/tests/Feature/Filament/Spec349CustomerReviewWorkspaceOutputGuidanceTest.php
    • apps/platform/tests/Feature/EnvironmentReview/Spec349EnvironmentReviewOutputGuidanceTest.php
    • apps/platform/tests/Browser/Spec349OutputResolutionGuidanceSmokeTest.php
  2. Lock the following before runtime changes:
    • one primary output state
    • one primary next action
    • grouped limitation disclosure
    • qualified download wording
    • explicit PII/internal-only warning
    • collapsed technical details by default
    • review detail separation of status dimensions
  3. Reuse current review/evidence/review-pack fixtures; do not widen default helper cost.

Phase 2 - Bounded Guidance Adapter

  1. Choose the narrowest implementation home:
    • extend ReviewPackOutputReadiness with derived presentation fields only if raw truth remains legible, or
    • add a small ReviewPackOutputResolutionGuidance companion under app/Support/ReviewPacks/
  2. Keep the guidance layer derived-only:
    • display state
    • label
    • severity
    • primary reason
    • impact
    • primary action
    • grouped limitations
    • secondary actions
    • technical-details payload
  3. If additional display states such as publication_blocked are needed, keep them presentation-only and map them from current limitation codes or publish-blocker truth.

Phase 3 - Action Mapping And Copy

  1. Map limitation codes to plain-language guidance:
    • evidence basis incomplete -> open evidence basis
    • required sections incomplete -> review section limitations
    • mapping/control limitations -> review unmapped evidence or control interpretation
    • publish blockers -> resolve review blockers
    • contains PII -> review package contents / PII state
    • export not ready -> review output limitations
  2. Prefer existing route helpers and scoped resource URLs.
  3. Keep button and notification vocabulary aligned to current localization patterns: Verb + Object, conservative sharing language, no false-ready wording.

Phase 4 - Customer Review Workspace Update

  1. Update CustomerReviewWorkspace payload building to consume the bounded guidance object instead of scattered reason/action logic.
  2. Update the Blade view to show:
    • one output-guidance label
    • one primary reason
    • one impact statement
    • one primary action
    • compact grouped limitations
    • qualified secondary download/action wording
    • collapsed technical details
  3. Preserve current acknowledgement, accepted-risk, findings, and proof sections unless a minimal copy/order change is required to support the one-blocker hierarchy.

Phase 5 - Environment Review Detail Update

  1. Update EnvironmentReviewResource / ViewEnvironmentReview so the detail surface clearly separates:
    • review status
    • output readiness
    • publication/sharing state
  2. Keep fingerprint and raw proof detail secondary or hidden in customer-workspace mode.
  3. Preserve customer-workspace-mode access, download safety, and current lifecycle-action behavior outside that mode.

Phase 6 - Localization, Audit, And Browser Proof

  1. Update only the required output-guidance keys in:
    • apps/platform/lang/en/localization.php
    • apps/platform/lang/de/localization.php
  2. Update docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md with the new guidance model, one-primary-action rule, grouped limitation behavior, and repo-truth note about the missing ui-009-review-pack-output-contract.md.
  3. Capture screenshots under specs/349-customer-review-workspace-output-resolution-guidance/artifacts/screenshots/.

Phase 7 - Validation And Close-Out

  1. Run focused Feature tests for the new guidance layer and the current Spec 347 regressions.
  2. Run the bounded Browser smoke for representative states.
  3. Run pint --dirty and git diff --check.
  4. Record any unrelated failures separately without widening scope.

Validation Plan

cd apps/platform
./vendor/bin/sail artisan test tests/Feature/ReviewPack/Spec349ReviewPackResolutionGuidanceTest.php tests/Feature/Filament/Spec349CustomerReviewWorkspaceOutputGuidanceTest.php tests/Feature/EnvironmentReview/Spec349EnvironmentReviewOutputGuidanceTest.php --compact
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec349OutputResolutionGuidanceSmokeTest.php --compact
./vendor/bin/sail artisan test --compact --filter=Spec347
./vendor/bin/sail artisan test --compact --filter=CustomerReviewWorkspace
./vendor/bin/sail artisan test --compact --filter=ReviewPack
./vendor/bin/sail pint --dirty
git diff --check

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 change