TenantAtlas/specs/386-review-publication-resolution-workflow-v1/tasks.md

Tasks: Spec 386 - Review Publication Resolution Workflow v1

Input: Design documents from /specs/386-review-publication-resolution-workflow-v1/ Prerequisites: spec.md, plan.md Tests: Required. This feature adds persistence, policy-sensitive workflow state, a new operator workflow surface, and browser-visible behavior.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in the smallest honest family, and any PostgreSQL/browser addition is explicit.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• The declared workflow-detail surface profile and shared-detail-family proof coverage are explicit.
• Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.

Phase 1: Preparation and Repo Truth

Purpose: Confirm exact runtime surfaces and prevent scope bleed before implementation.

• T001 Confirm current branch/status and re-read specs/386-review-publication-resolution-workflow-v1/spec.md, plan.md, and tasks.md before runtime edits.
• T002 Verify completed-spec guardrail for specs/350-operator-resolution-guidance-framework-v1/, specs/351-review-output-resolve-actions-v1/, specs/367-operationrun-actionability-system/, and specs/385-evidence-review-readiness/; do not modify those packages.
• T003 Inspect exact Environment Review model, resource, page, policy, and route names before adding the resolution entry point.
• T004 Inspect existing review readiness/publish/export gates and record which service(s) are authoritative for publication blockers.
• T005 Inspect existing EvidenceSnapshotService and evidence generation OperationRun behavior before adding evidence step execution.
• T006 Inspect existing StoredReport/report-generation services for permission posture, admin roles, findings summary, accepted-risk summary, and baseline posture before mapping report steps.
• T007 Inspect existing Review Pack generation service/job/action behavior before mapping review-pack steps.
• T008 Inspect existing OperationRun start/link/presenter helpers and confirm which shared path must be reused for queued/run-link UX.
• T009 Inspect existing audit logging helpers and action IDs before adding resolution lifecycle events.
• T010 Inspect existing capability constants, policies, and UiEnforcement/WorkspaceUiEnforcement patterns for the relevant review/evidence/report/pack operations.
• T011 Confirm no generic workflow engine, top-level navigation, global-search resource, auto-publish behavior, customer self-resolution, or cross-domain adapter is needed; update spec/plan/tasks first if this is false.

Phase 2: Persistence and Policy Tests First

Purpose: Define schema, isolation, and authorization behavior before adding implementation.

• T012 [P] Add PostgreSQL migration tests for review_publication_resolution_cases and review_publication_resolution_steps JSONB/index/partial unique active-current constraints under the existing pgsql lane or nearest migration test family.
• T013 [P] Add model relationship tests for case-to-workspace, case-to-environment, case-to-review, case-to-steps, step-to-case, step-to-operation-run, and proof reference fields.
• T014 [P] Add policy tests proving non-workspace members receive deny-as-not-found for case view and step access.
• T015 [P] Add policy tests proving non-entitled environment access receives deny-as-not-found.
• T016 [P] Add policy tests proving an entitled readonly actor can view safe status but cannot execute step actions.
• T017 [P] Add policy tests proving operator/manager/owner capabilities map to the underlying evidence/report/review-pack operations instead of a blanket case permission.
• T018 Add a transactional/concurrency test proving duplicate active/current cases are not created for the same workspace/environment/review/action/currentness.

Checkpoint: These tests should fail before migrations/models/policies are implemented.

Phase 3: Migrations, Models, Statuses, and Policy

Purpose: Add bounded review-publication-specific persistence.

• T019 Create reversible migration(s) for review_publication_resolution_cases and review_publication_resolution_steps in apps/platform/database/migrations/, including the review.publication action key and PostgreSQL partial unique active-current constraint.
• T020 Add ReviewPublicationResolutionCase model with casts, relationships, scopes for workspace/environment/review/action/status/active/current, and safe metadata handling.
• T021 Add ReviewPublicationResolutionStep model with casts, relationships, ordered-step helpers, proof reference helpers, and safe metadata handling.
• T022 Add review-publication-specific case status value object/enum with only open, in_progress, waiting_for_run, blocked, ready_to_continue, completed, cancelled, and superseded.
• T023 Add review-publication-specific step status value object/enum with only pending, actionable, running, failed, completed, and superseded; do not persist skipped, not_applicable, or a step reason_code family in v1.
• T024 Add or extend policy registration for ReviewPublicationResolutionCasePolicy using deny-as-not-found for workspace/environment non-entitlement.
• T025 Ensure metadata/summary casts cannot store raw provider payloads, raw report content, full evidence JSON, secrets, or tokens by convention and tests.
• T026 Run the focused model/policy/pgsql tests and fix only in-scope issues.

Phase 4: Evaluator, Planner, and Fingerprint Tests First

Purpose: Define derived readiness and step-plan behavior before services are implemented.

• T027 [P] Add unit tests for no blockers -> ready/no case needed.
• T028 [P] Add unit tests for missing/stale reports -> complete_required_reports.
• T029 [P] Add unit tests for missing/stale evidence -> collect_evidence_snapshot.
• T030 [P] Add unit tests for output not customer-ready after inputs are current -> refresh_review_composition.
• T031 [P] Add unit tests for current review output with missing/stale pack/export -> generate_review_pack.
• T032 [P] Add unit tests for final unblocked state -> return_to_publication.
• T033 [P] Add unit tests proving irrelevant steps are omitted and v1 stays sequential.
• T034 [P] Add fingerprint tests proving relevant evidence/report/review/pack/run changes alter currentness while volatile UI-only fields do not.
• T035 [P] Add zero-findings/zero-drift tests proving evaluated successful empty results are complete and unevaluated empty states are not.

Checkpoint: These tests should fail before evaluator/planner services are implemented.

Phase 5: Evaluator, Planner, and Proof Resolver

Purpose: Build the derived planning layer without duplicating readiness or artifact truth.

• T036 Implement ReviewPublicationReadinessEvaluator under a review-publication-specific namespace to evaluate current publication readiness from existing services/artifacts.
• T037 Ensure the evaluator does not create reports, collect evidence, refresh reviews, generate packs, publish reviews, or call Graph/provider APIs.
• T038 Implement a stable readiness fingerprint from review, evidence, required report, review-pack/export, blocker, and readiness status inputs.
• T039 Implement ReviewPublicationResolutionPlanner to map evaluator requirements to ordered v1 steps only.
• T040 Ensure planner output has one primary actionable step unless implementation updates spec/plan/tasks to approve parallel report steps.
• T041 Implement ReviewPublicationResolutionProofResolver to derive OperationRun and artifact proof/currentness without making the case canonical truth.
• T042 Ensure old failed runs do not remain current blockers after newer successful current proof exists.
• T043 Ensure old successful proof does not complete current steps after review/evidence/report/pack currentness changes.
• T044 Run focused evaluator/planner/proof unit tests and fix only in-scope issues.

Phase 6: Case Service Tests First

Purpose: Define create/resume/update/complete/supersede behavior before implementation.

• T045 Add feature tests proving blocked review creates a case and ordered steps.
• T046 Add feature tests proving the same current active case resumes instead of duplicating.
• T047 Add feature tests proving changed fingerprint re-evaluates and updates or supersedes stale case safely.
• T048 Add feature tests proving no blockers complete or bypass case creation.
• T049 Add feature tests proving case completes only when current readiness evaluation is unblocked.
• T050 Add feature tests proving deleted or inaccessible review subject becomes superseded or inaccessible without leaking existence.
• T051 Add feature tests proving case scope cannot mix workspace/environment/review/proof records.

Phase 7: Case Service Implementation

Purpose: Persist and maintain workflow state safely.

• T052 Implement ReviewPublicationResolutionCaseService create/resume behavior in a transaction.
• T053 Persist initial steps from the planner with stable ordering and safe summaries.
• T054 Update step statuses after readiness re-evaluation without overwriting proof truth incorrectly.
• T055 Mark cases completed, cancelled, or superseded according to current lifecycle rules.
• T056 Enforce workspace/environment/review consistency for all case and step operations.
• T057 Add lock/idempotency handling to prevent duplicate active/current cases on double click or concurrent requests.
• T058 Run focused case service tests and fix only in-scope issues.

Phase 8: Step Action Tests First

Purpose: Define action execution, OperationRun linking, artifact proof, and capability behavior before implementation.

• T059 Add tests for complete_required_reports using existing report generation service/action paths and linking proof.
• T060 Add tests for collect_evidence_snapshot using existing EvidenceSnapshotService/job paths and linking OperationRun/artifact proof.
• T061 Add tests for refresh_review_composition using existing review refresh/composition paths and linking OperationRun/review proof.
• T062 Add tests for generate_review_pack using existing ReviewPack service/job paths and linking OperationRun/pack proof.
• T063 Add tests proving step actions do not auto-publish and existing publish gates still block unsafe publication.
• T064 Add tests proving running OperationRun sets step running and case waiting_for_run.
• T065 Add tests proving failed OperationRun sets step failed unless newer current successful proof exists.
• T066 Add tests proving capability denial renders safe blocked state and does not dispatch jobs, create reports, or create runs.

Phase 9: Step Action Implementation

Purpose: Execute only source-owned actions and link proof.

• T067 Implement ReviewPublicationResolutionActionService to execute allowed current-step actions.
• T068 Wire report-generation steps to existing report services/actions; do not invent fake StoredReport rows.
• T069 Wire evidence snapshot steps to existing evidence services/jobs.
• T070 Wire review refresh/composition steps to existing review services/jobs.
• T071 Wire review-pack steps to existing review-pack services/jobs.
• T072 Link the primary operation_run_id to the current step when an async operation is created or reused.
• T073 Link the primary artifact proof reference when an artifact exists and currentness checks pass.
• T074 Preserve existing shared OperationRun start UX for queued toasts, links, browser events, dedupe/already-running, and terminal notifications.
• T075 Ensure retry appears only for failed actionable steps and still enforces underlying capability, confirmation, audit, notification, and OperationRun link rules from the spec action confirmation contract.
• T076 Run focused step-action tests and fix only in-scope issues.

Phase 10: Filament Entry Point and Workflow UI Tests First

Purpose: Define the operator workflow and customer non-leakage surface before UI implementation.

• T077 Add Filament/Livewire tests proving blocked Environment Review shows one primary Resolve publication blockers CTA.
• T078 Add Filament/Livewire tests proving publish remains blocked/disabled when existing gates say blocked and refresh is not promoted as primary.
• T079 Add Filament/Livewire tests proving clicking the CTA creates/resumes the case and redirects/opens the resolution workflow.
• T080 Add Filament/Livewire tests proving the resolution page renders blocked reason, required reports, next safe action, preparation progress, and technical detail disclosure.
• T081 Add Filament/Livewire tests proving the current step has exactly one primary executable action where allowed and that queued/regeneration/cancel/supersede actions use the required confirmation behavior.
• T082 Add Filament/Livewire tests proving readonly/capability-denied users see safe disabled/blocked state and no executable button.
• T083 Add Filament/Livewire tests proving completed/ready state shows Return to review and does not auto-publish.
• T084 Add customer workspace tests proving no internal case, step, OperationRun debug, permission internals, raw report state, or technical remediation details are visible by default.

Phase 11: Filament Entry Point and Workflow UI Implementation

Purpose: Add the visible workflow while preserving Filament v5 and TenantPilot UX rules.

• T085 Add the review-owned resolution route/page/action under EnvironmentReviewResource using existing Filament discovery conventions.
• T086 Add or update the blocked-state CTA on ViewEnvironmentReview or the current summary view.
• T087 Keep the review surface one-primary-action: Resolve publication blockers while blocked.
• T088 Render resolution page decision summary with blocked reason, required reports, next safe action, what happens after this, and no-auto-publish copy.
• T089 Render compact preparation progress in the first decision section, with the actionable step visually emphasized and completed/pending steps secondary.
• T090 Render proof links behind proof sections and technical detail behind explicit disclosure.
• T091 Render safe empty/ready/already-published states without creating unnecessary cases.
• T092 Add or update Customer Review Workspace safe preparation/unavailable wording only if needed for non-leakage.
• T093 Use native Filament actions/components/shared primitives first; avoid local semantic color/button/card systems.
• T094 Ensure no new top-level navigation item, generic resource, bulk action, or global search surface is added.
• T095 Run focused Filament/Livewire tests and fix only in-scope issues.

Phase 12: Audit and Security

Purpose: Make the workflow attributable and safe.

• T096 Add audit events for review_publication_resolution.created.
• T097 Add audit events for review_publication_resolution.resumed.
• T098 Add audit events for review_publication_resolution.step_started.
• T099 Add audit events for review_publication_resolution.operation_linked.
• T100 Add audit events for review_publication_resolution.step_completed.
• T101 Add audit events for review_publication_resolution.step_failed.
• T102 Add audit events for review_publication_resolution.case_completed.
• T103 Add audit events for review_publication_resolution.cancelled.
• T104 Add audit events for review_publication_resolution.superseded.
• T105 Ensure audit payloads include safe workspace/environment/case/subject/step/run/proof/status identifiers and derived safe reason summaries only.
• T106 Add audit tests proving raw provider payloads, secrets, tokens, full report content, and full evidence JSON are not logged.
• T107 Add no-Graph-during-render and bounded DB-local planner/render tests or guards for the resolution page and blocked review render path.
• T108 Confirm cross-plane /system access does not expose or mutate admin-plane resolution cases.

Phase 13: UI/Productization Coverage

Purpose: Satisfy UI-COV-001 for the new workflow and affected surfaces.

• T109 Update docs/ui-ux-enterprise-audit/route-inventory.md for the new subject-driven resolution route or page-action surface.
• T110 Update docs/ui-ux-enterprise-audit/design-coverage-matrix.md for the new workflow surface.
• T111 Update or create the relevant page report for Review Publication Resolution workflow.
• T112 Update the Environment Review detail page report for the blocked-state CTA/action hierarchy change.
• T113 Update Customer Review Workspace page report if safe preparation/non-leakage wording changes materially.
• T114 Record screenshot/browser-smoke artifact paths for blocked CTA, open case, current step, running, failed, completed proof, ready return, customer no-leakage, and dark/mobile smoke where feasible.
• T115 Confirm the spec UI Action Matrix still matches implementation; update spec/plan/tasks before merge if action placement or dangerous-action behavior changes.

Phase 14: Validation

Purpose: Prove the implementation and capture residual risk.

• T116 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/ReviewPublicationResolution.
• T117 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPublicationResolution tests/Feature/EnvironmentReview tests/Feature/ReviewPack.
• T118 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/Spec386ReviewPublicationResolutionUiTest.php.
• T119 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest -c phpunit.pgsql.xml --filter Spec386.
• T120 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec386ReviewPublicationResolutionWorkflowTest.php (local fallback used: php artisan test --compact tests/Browser/Spec386ReviewPublicationResolutionWorkflowTest.php).
• T121 Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent (local fallback used: ./vendor/bin/pint --dirty --test).
• T122 Run git diff --check.
• T123 Record implementation close-out with Livewire v4 compliance, provider registration location, global search status, destructive/high-impact action handling, asset strategy, tests run, browser smoke result, and deployment impact.

Explicit Non-Goals

• NT001 Do not modify completed dependency specs except as read-only context.
• NT002 Do not create a generic workflow engine, registry, adapter framework, or generic action-resolution CRUD resource.
• NT003 Do not add top-level navigation or global search for resolution cases.
• NT004 Do not auto-publish reviews or bypass existing publish/export gates.
• NT005 Do not expose internal resolution case details to customer-facing surfaces.
• NT006 Do not store raw provider payloads, raw report content, full evidence JSON, secrets, or tokens in case/step/audit metadata.
• NT007 Do not call Graph/provider APIs during UI render or readiness display.
• NT008 Do not transition OperationRun.status or OperationRun.outcome outside existing services.
• NT009 Do not implement Restore, Provider Onboarding, Baseline Compare, Report Delivery, Customer Portal, AI, Billing, or Cross-Tenant Promotion resolution adapters in this spec.
• NT010 Do not use generic action_resolution_* persistence without first updating spec/plan/tasks with proportionality justification and review-publication-only constraints.