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

- [x] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
- [x] New or changed tests stay in the smallest honest family, and any PostgreSQL/browser addition is explicit.
- [x] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
- [x] Planned validation commands cover the change without pulling in unrelated lane cost.
- [x] 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.

- [x] 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.
- [x] 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.
- [x] T003 Inspect exact Environment Review model, resource, page, policy, and route names before adding the resolution entry point.
- [x] T004 Inspect existing review readiness/publish/export gates and record which service(s) are authoritative for publication blockers.
- [x] T005 Inspect existing EvidenceSnapshotService and evidence generation OperationRun behavior before adding evidence step execution.
- [x] T006 Inspect existing StoredReport/report-generation services for permission posture, admin roles, findings summary, accepted-risk summary, and baseline posture before mapping report steps.
- [x] T007 Inspect existing Review Pack generation service/job/action behavior before mapping review-pack steps.
- [x] T008 Inspect existing OperationRun start/link/presenter helpers and confirm which shared path must be reused for queued/run-link UX.
- [x] T009 Inspect existing audit logging helpers and action IDs before adding resolution lifecycle events.
- [x] T010 Inspect existing capability constants, policies, and `UiEnforcement`/`WorkspaceUiEnforcement` patterns for the relevant review/evidence/report/pack operations.
- [x] 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.
- [x] 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.

- [x] 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.
- [x] T020 Add `ReviewPublicationResolutionCase` model with casts, relationships, scopes for workspace/environment/review/action/status/active/current, and safe metadata handling.
- [x] T021 Add `ReviewPublicationResolutionStep` model with casts, relationships, ordered-step helpers, proof reference helpers, and safe metadata handling.
- [x] 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`.
- [x] 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.
- [x] 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.

- [x] T036 Implement `ReviewPublicationReadinessEvaluator` under a review-publication-specific namespace to evaluate current publication readiness from existing services/artifacts.
- [x] T037 Ensure the evaluator does not create reports, collect evidence, refresh reviews, generate packs, publish reviews, or call Graph/provider APIs.
- [x] T038 Implement a stable readiness fingerprint from review, evidence, required report, review-pack/export, blocker, and readiness status inputs.
- [x] T039 Implement `ReviewPublicationResolutionPlanner` to map evaluator requirements to ordered v1 steps only.
- [x] T040 Ensure planner output has one primary actionable step unless implementation updates spec/plan/tasks to approve parallel report steps.
- [x] 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.

- [x] 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.
- [x] T047 Add feature tests proving changed fingerprint re-evaluates and updates or supersedes stale case safely.
- [x] 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.

- [x] T052 Implement `ReviewPublicationResolutionCaseService` create/resume behavior in a transaction.
- [x] T053 Persist initial steps from the planner with stable ordering and safe summaries.
- [x] T054 Update step statuses after readiness re-evaluation without overwriting proof truth incorrectly.
- [x] T055 Mark cases completed, cancelled, or superseded according to current lifecycle rules.
- [x] T056 Enforce workspace/environment/review consistency for all case and step operations.
- [x] T057 Add lock/idempotency handling to prevent duplicate active/current cases on double click or concurrent requests.
- [x] 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.

- [x] T059 Add tests for `complete_required_reports` using existing report generation service/action paths and linking proof.
- [x] 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.
- [x] 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.

- [x] T067 Implement `ReviewPublicationResolutionActionService` to execute allowed current-step actions.
- [x] T068 Wire report-generation steps to existing report services/actions; do not invent fake `StoredReport` rows.
- [x] T069 Wire evidence snapshot steps to existing evidence services/jobs.
- [x] T070 Wire review refresh/composition steps to existing review services/jobs.
- [x] T071 Wire review-pack steps to existing review-pack services/jobs.
- [x] T072 Link the primary `operation_run_id` to the current step when an async operation is created or reused.
- [x] T073 Link the primary artifact proof reference when an artifact exists and currentness checks pass.
- [x] 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.
- [x] 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.

- [x] 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.
- [x] T079 Add Filament/Livewire tests proving clicking the CTA creates/resumes the case and redirects/opens the resolution workflow.
- [x] 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.
- [x] 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.

- [x] T085 Add the review-owned resolution route/page/action under `EnvironmentReviewResource` using existing Filament discovery conventions.
- [x] T086 Add or update the blocked-state CTA on `ViewEnvironmentReview` or the current summary view.
- [x] T087 Keep the review surface one-primary-action: `Resolve publication blockers` while blocked.
- [x] T088 Render resolution page decision summary with blocked reason, required reports, next safe action, what happens after this, and no-auto-publish copy.
- [x] T089 Render compact preparation progress in the first decision section, with the actionable step visually emphasized and completed/pending steps secondary.
- [x] T090 Render proof links behind proof sections and technical detail behind explicit disclosure.
- [x] 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.
- [x] T093 Use native Filament actions/components/shared primitives first; avoid local semantic color/button/card systems.
- [x] T094 Ensure no new top-level navigation item, generic resource, bulk action, or global search surface is added.
- [x] T095 Run focused Filament/Livewire tests and fix only in-scope issues.

## Phase 12: Audit and Security

**Purpose**: Make the workflow attributable and safe.

- [x] T096 Add audit events for `review_publication_resolution.created`.
- [x] T097 Add audit events for `review_publication_resolution.resumed`.
- [x] T098 Add audit events for `review_publication_resolution.step_started`.
- [x] T099 Add audit events for `review_publication_resolution.operation_linked`.
- [x] T100 Add audit events for `review_publication_resolution.step_completed`.
- [x] T101 Add audit events for `review_publication_resolution.step_failed`.
- [x] T102 Add audit events for `review_publication_resolution.case_completed`.
- [x] T103 Add audit events for `review_publication_resolution.cancelled`.
- [x] T104 Add audit events for `review_publication_resolution.superseded`.
- [x] 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.

- [x] T109 Update `docs/ui-ux-enterprise-audit/route-inventory.md` for the new subject-driven resolution route or page-action surface.
- [x] T110 Update `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` for the new workflow surface.
- [x] T111 Update or create the relevant page report for Review Publication Resolution workflow.
- [x] 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.
- [x] 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.
- [x] 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`.
- [x] 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`).
- [x] T121 Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` (local fallback used: `./vendor/bin/pint --dirty --test`).
- [x] 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

- [x] NT001 Do not modify completed dependency specs except as read-only context.
- [x] NT002 Do not create a generic workflow engine, registry, adapter framework, or generic action-resolution CRUD resource.
- [x] NT003 Do not add top-level navigation or global search for resolution cases.
- [x] NT004 Do not auto-publish reviews or bypass existing publish/export gates.
- [x] NT005 Do not expose internal resolution case details to customer-facing surfaces.
- [x] 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.