ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
acdb205e1b
TenantAtlas/specs/349-customer-review-workspace-output-resolution-guidance/plan.md
Ahmed Darrazi acdb205e1b
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 3m42s
Details
feat: customer review workspace output resolution guidance (spec 349) 
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.
2026-06-03 03:31:29 +02:00

14 KiB
Raw 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