TenantAtlas/specs/349-customer-review-workspace-output-resolution-guidance/tasks.md

Tasks: Spec 349 - Customer Review Workspace Output Resolution Guidance

Input: specs/349-customer-review-workspace-output-resolution-guidance/spec.md, plan.md, repo-truth-map.md, and checklists/requirements.md

Tests: Required. This is a runtime guidance and trust-surface change on existing review-pack, workspace, and review-detail paths.

Test Governance Checklist

• Lane assignment is explicit and narrow: Feature for mapping and surface behavior, Browser for first-screen trust proof.
• New or changed tests stay in the smallest honest family, and the browser addition is explicit.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• The declared surface profiles (global-context-shell and shared-detail-family) are explicit.
• Any derived-state expansion remains presentation-only and does not create a hidden new domain state family.

Phase 1: Preparation And Repo Truth

Purpose: Keep the implementation bounded to existing readiness truth and current workspace/detail surfaces.

• T001 Re-read spec.md, plan.md, repo-truth-map.md, and checklists/requirements.md before runtime changes.
• T002 Re-read related historical context only: Specs 258, 308, 311, 326, 342, 343, 344, and 347. Do not modify their artifacts.
• T003 Re-verify 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
• T004 Keep specs/349-customer-review-workspace-output-resolution-guidance/repo-truth-map.md updated if implementation-time inspection reveals a narrower or broader bounded truth.
• T005 Confirm no migration, package, env var, queue family, scheduler change, storage-topology change, panel/provider change, or global-search change is required.
• T006 Confirm Filament v5 / Livewire v4.0+ compliance and avoid legacy Filament or Livewire APIs.
• T007 Confirm panel provider registration remains apps/platform/bootstrap/providers.php.

Phase 2: Tests First

Purpose: Lock the operator-guidance behavior before runtime refactor.

• T008 Add apps/platform/tests/Feature/ReviewPack/Spec349ReviewPackResolutionGuidanceTest.php.
• T009 Add apps/platform/tests/Feature/Filament/Spec349CustomerReviewWorkspaceOutputGuidanceTest.php.
• T010 Add apps/platform/tests/Feature/EnvironmentReview/Spec349EnvironmentReviewOutputGuidanceTest.php.
• T011 Add apps/platform/tests/Browser/Spec349OutputResolutionGuidanceSmokeTest.php.
• T012 Add assertions that the workspace shows exactly one dominant output state and exactly one primary next action.
• T013 Add assertions that grouped limitations appear compactly and technical details stay collapsed/secondary by default.
• T014 Add assertions that PII/internal-only output shows an explicit warning before customer-safe wording.
• T015 Add assertions that download labels are qualified honestly for customer-safe, internal-only, limited, and not-ready states.
• T016 Add assertions that Environment Review detail separates review status, output readiness, and publication/sharing state.
• T017 Reuse or extend current regressions such as:
  • apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackOutputContractTest.php
  • apps/platform/tests/Feature/ReviewPack/Spec347ReviewPackReadinessSemanticsTest.php
  • apps/platform/tests/Feature/Filament/Spec347CustomerReviewWorkspaceOutputReadinessTest.php
  • apps/platform/tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php
  • apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php
  • apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php
  • apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewUiContractTest.php

Phase 3: Guidance Mapping

Purpose: Build one bounded derived mapping from readiness truth to operator guidance.

• T018 Choose the narrowest implementation home:
  • extend apps/platform/app/Support/ReviewPacks/ReviewPackOutputReadiness.php, or
  • add apps/platform/app/Support/ReviewPacks/ReviewPackOutputResolutionGuidance.php
• T019 Derive display state, label, severity, primary reason, impact, primary action, grouped limitations, secondary actions, and technical details from existing readiness truth only.
• T020 Keep any added states such as publication_blocked or internal_only presentation-only; do not create new persisted enums or workflow states.
• T021 Map existing limitation codes to plain-language operator guidance and repo-real destinations using current scoped route helpers.
• T022 Keep the mapping shared enough to prevent workspace/detail wording drift, but bounded enough to avoid a generic workflow-resolution framework.

Phase 4: Customer Review Workspace Update

Purpose: Turn the current readiness truth into one calm first-screen decision.

• T023 Update apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php to consume the bounded guidance mapping instead of scattered reason/action logic.
• T024 Update apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php so the decision card shows one output state, one reason, one impact statement, and one primary action.
• T025 Add a compact grouped limitations disclosure with supporting actions and collapsed technical details.
• T026 Qualify review-pack download labels and surrounding copy without weakening existing signed-download safety or authorization.
• T027 Preserve current acknowledgement, findings, accepted-risk, and proof sections unless a minimal hierarchy adjustment is required to support the one-blocker rule.
• T028 Preserve the visible environment_id workspace filter contract and avoid reintroducing hidden topbar or shell-context behavior.
• T029 Ensure grouped limitation disclosure, details toggles, and status text remain text-backed, keyboard-reachable, and not color-only.

Phase 5: Environment Review Detail Update

Purpose: Separate review publication truth from output-readiness truth on the detail surface.

• T030 Update apps/platform/app/Filament/Resources/EnvironmentReviewResource.php infolist presentation if needed so the detail summary exposes distinct status dimensions cleanly.
• T031 Update apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php or the supporting infolist state so the detail surface shows review status, output readiness, and publication/sharing state separately.
• T032 Keep fingerprint, raw proof metadata, and support-only detail secondary or hidden in customer-workspace mode.
• T033 Preserve existing customer-workspace-mode access, header-action narrowing, and lifecycle-action behavior outside customer-workspace mode.

Phase 6: Copy, Audit, And Browser Proof

Purpose: Align wording and audit artifacts with the bounded guidance model.

• T034 Update only the required output-guidance localization keys in:
  • apps/platform/lang/en/localization.php
  • apps/platform/lang/de/localization.php
• T035 Update docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md with the one-primary-action rule, grouped limitation disclosure, and repo-truth note about the user-draft ui-009 conflict.
• T036 If implementation proves a second durable page report is required, create it under the next repo-real identity instead of reusing ui-009.
• T037 Capture browser screenshots under specs/349-customer-review-workspace-output-resolution-guidance/artifacts/screenshots/.

Phase 7: Validation

Purpose: Prove the guidance mapping and preserve existing safety.

• T038 Run cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/ReviewPack/Spec349ReviewPackResolutionGuidanceTest.php tests/Feature/Filament/Spec349CustomerReviewWorkspaceOutputGuidanceTest.php tests/Feature/EnvironmentReview/Spec349EnvironmentReviewOutputGuidanceTest.php --compact.
• T039 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec349OutputResolutionGuidanceSmokeTest.php --compact.
• T040 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec347.
• T041 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=CustomerReviewWorkspace.
• T042 Run cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ReviewPack.
• T043 Run cd apps/platform && ./vendor/bin/sail pint --dirty.
• T044 Run git diff --check.
• T045 Report any unrelated broader-suite failures honestly if they remain out of scope.

Non-Goals Checklist

• NT001 Do not create a new persisted resolution entity, table, or status family.
• NT002 Do not add a workflow engine, approval engine, or queue family.
• NT003 Do not build a Customer Portal or Review Pack PDF/HTML renderer.
• NT004 Do not rewrite Review Pack generation or reopen Spec 347 contract truth broadly.
• NT005 Do not redesign Governance Inbox or broadly redesign Customer Review Workspace outside the output-guidance slice.
• NT006 Do not weaken existing workspace/environment scope, policies, or signed-download safety.