# Tasks: OperationRun Reconciliation Adapter Framework & Review Compose Adapter **Input**: `specs/359-operationrun-reconciliation-adapter-framework-review-compose-adapter/spec.md`, `plan.md`, and `checklists/requirements.md` **Prerequisites**: `spec.md` and `plan.md` **Tests**: REQUIRED (Pest). Keep proof bounded to Unit + Feature + PGSQL + one explicit Browser smoke. **Operations**: Reuse current `OperationRun` lifecycle ownership. No new run status column, no new queue family, no new schema, and no destructive cleanup. **RBAC**: Reuse current workspace-first run access plus `Capabilities::ENVIRONMENT_REVIEW_MANAGE` for review initiation. Presentation must never reveal cross-workspace or cross-environment review truth. **Shared Pattern Reuse**: Reuse `OperationRunService`, `OperationRun::reconciliation()`, current monitoring/detail surfaces, current review-create feedback, and the current restore adapter precedent instead of building a parallel framework. **Filament / Panel Guardrails**: Filament remains v5 on Livewire v4. Provider registration stays in `apps/platform/bootstrap/providers.php`. No new panel, route family, or asset strategy is allowed. **Organization**: Tasks are grouped by user story so the new contract, duplicate recovery, review-start idempotency, and visible wording each remain independently reviewable. ## Repo Baseline At Prep Time - **Branch**: `359-operationrun-reconciliation-adapter-framework-review-compose-adapter` - **HEAD**: `2a12729d feat: implement operation run queue truth foundation (spec 358) (#429)` - **`git status --short --branch`**: clean before Spec Kit branch creation; this prep adds only `specs/359-operationrun-reconciliation-adapter-framework-review-compose-adapter/` - **Relevant runtime surfaces**: - `apps/platform/app/Services/OperationRunService.php` - `apps/platform/app/Services/Operations/OperationLifecycleReconciler.php` - `apps/platform/app/Services/AdapterRunReconciler.php` - `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewService.php` - `apps/platform/app/Jobs/ComposeEnvironmentReviewJob.php` - `apps/platform/app/Models/EnvironmentReview.php` - `apps/platform/app/Filament/Pages/Monitoring/Operations.php` - `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` - `apps/platform/app/Filament/Resources/OperationRunResource.php` - `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php` - **Spec 358 baseline status**: completed foundation context only; use it as the generic queue-truth baseline and do not rewrite its historical close-out or validation language. - **Related completed context**: Spec 357 remains regression context for report/review output; Spec 311 remains completed shell/scope foundation context only. ## Merge Close-Out Status - **Merged baseline**: `3a750726 feat: implement review compose reconciliation adapter (spec 359) (#430)` on `platform-dev` - **Merge note**: Spec 359 shipped the bounded review-compose adapter path, deterministic duplicate/superseded recovery, shared review truth resolution, and bounded Unit/Feature/Browser coverage. - **Known blocked validation at merge**: local PGSQL validation remained unavailable because the PGSQL host or Docker runtime was not available. - **Deferred follow-through moved to Spec 360**: - canonical adapter-seam cleanup beyond the bounded Spec 359 path - canonical `context.dispatch` and shared queue/failure correlation - operation-type alias retirement and canonical read-side cutover - only the bounded review-start feedback or link follow-through that depends on the canonical run or related-artifact truth cutover; no broad UI or localization cleanup rides with Spec 360 - **Historical baseline note**: the `Repo Baseline At Prep Time` section above remains the original prep-time context and is not the post-merge runtime baseline. ## 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 the PGSQL/browser additions remain 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 widening into unrelated lane cost. - [x] The declared monitoring/detail surface profile is explicit. - [x] Any material budget, baseline, trend, or escalation note is recorded in the active feature close-out. ## Phase 1: Setup (Repo Truth Inventory) **Purpose**: confirm the existing reconciliation, review-compose, and visible UX seams before runtime edits begin. - [x] T001 Re-read `spec.md`, `plan.md`, `checklists/requirements.md`, `.specify/memory/constitution.md`, `docs/ai-coding-rules.md`, `docs/architecture-guidelines.md`, `docs/testing-guidelines.md`, `docs/security-guidelines.md`, `docs/filament-guidelines.md`, and `specs/358-operationrun-queue-truth-foundation/{spec,plan,tasks}.md` together before touching runtime code. - [x] T002 [P] Confirm the current reconciliation seams in `apps/platform/app/Services/OperationRunService.php`, `apps/platform/app/Services/Operations/OperationLifecycleReconciler.php`, `apps/platform/app/Services/AdapterRunReconciler.php`, and `apps/platform/app/Models/OperationRun.php`. - [x] T003 [P] Confirm the current review-compose seams in `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewService.php`, `apps/platform/app/Jobs/ComposeEnvironmentReviewJob.php`, `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php`, `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewFingerprint.php`, `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewLifecycleService.php`, and `apps/platform/app/Models/EnvironmentReview.php`. - [x] T004 [P] Confirm the current visible proof owners in `apps/platform/app/Filament/Pages/Monitoring/Operations.php`, `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`, `apps/platform/app/Filament/Resources/OperationRunResource.php`, `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php`, `apps/platform/app/Filament/Widgets/Dashboard/RecentOperations.php`, `apps/platform/app/Filament/System/Pages/Ops/Runs.php`, `apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php`, and the current EN/DE localization families. - [x] T005 Confirm that no new schema, no new panel/provider path, no new asset registration, and no new provider-boundary work are required. --- ## Phase 2: Foundational (Blocking Reconciliation Contract) **Purpose**: settle one narrow business-truth reconciliation seam before touching individual review/job surfaces. **Critical**: no user-story runtime work should begin until this phase is complete. - [x] T006 [P] Add failing Unit coverage for the result/decision model in `apps/platform/tests/Unit/Support/Operations/Reconciliation/Spec359ReconciliationResultTest.php`. - [x] T007 [P] Add failing Unit coverage for `apps/platform/app/Services/AdapterRunReconciler.php` supported-type behavior in `apps/platform/tests/Unit/Support/Operations/Reconciliation/Spec359AdapterRunReconcilerSupportedTypesTest.php`, including `restore.execute`, `environment.review.compose`, unsupported-type handling, and current restore-path preservation expectations. - [x] T008 [P] Add failing Unit coverage for same-scope proof and fail-closed branches in `apps/platform/tests/Unit/Support/Operations/Reconciliation/Spec359EnvironmentReviewComposeAdapterTest.php`. - [x] T009 Extend `apps/platform/app/Services/AdapterRunReconciler.php` with one local `environment.review.compose` path plus a thin decision/result helper, without introducing a new registry/resolver namespace or a universal business reconciliation engine. - [x] T010 Extend or wrap `apps/platform/app/Services/OperationRunService.php` so adapter-driven reconciliation writes merge richer `context.reconciliation` metadata idempotently and preserve current terminal audit behavior. - [x] T011 Keep `apps/platform/app/Services/AdapterRunReconciler.php` behavior intact or bridge it minimally behind the new contract without changing restore business behavior. **Checkpoint**: one shared adapter contract exists, richer reconciliation metadata is service-owned, and restore-specific behavior still works. --- ## Phase 3: User Story 1 - Reuse proven review truth for a stale review-compose run (Priority: P1) **Goal**: a same-scope ready or published review can safely complete a queued/running `environment.review.compose` run as succeeded. **Independent Test**: seed a queued/running compose run plus a same-scope ready review and verify succeeded reconciliation with related review metadata. ### Tests for User Story 1 - [x] T012 [P] [US1] Add `apps/platform/tests/Feature/Operations/Spec359OperationRunAdapterReconciliationTest.php` for `completed/succeeded` reconciliation from existing ready/published review truth. - [x] T013 [P] [US1] Extend monitoring/detail presentation coverage in `apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php` or a new Spec 359-focused feature file so the reconciled review-compose explanation is visible without generic wait-state copy. - [x] T013A [P] [US1] Extend shared-consumer feature coverage for review-compose explanation on dashboard/system/summary surfaces if shared presenter wording changes remain in scope. ### Implementation for User Story 1 - [x] T014 [US1] Implement the `environment.review.compose` adapter so it proves same-workspace, same-environment, same-fingerprint review truth and returns `reconciled_succeeded` only for safe ready/published review states. - [x] T015 [US1] Extend `apps/platform/app/Services/OperationRunService.php` so adapter success records previous status/outcome, related model metadata, and bounded evidence in `context.reconciliation`. - [x] T016 [US1] Update the current operations/detail presentation seams in `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`, `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`, and `apps/platform/app/Filament/Resources/OperationRunResource.php` only as needed so review-compose reconciliation reads calmly and consistently. - [x] T016A [US1] Update `apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php` and `apps/platform/app/Support/OperationRunLinks.php` to prefer reconciliation-related review metadata before falling back to `operation_run_id` lookups. **Checkpoint**: User Story 1 is independently functional when same-scope review truth safely completes the run and visible monitoring surfaces explain it. --- ## Phase 4: User Story 2 - Recover duplicate fingerprint and superseded review lineages deterministically (Priority: P1) **Goal**: duplicate collisions and late jobs end as succeeded/blocked/attention deterministically, never as endless active runs. **Independent Test**: simulate duplicate-key and superseded-successor cases in PGSQL-aware coverage and verify deterministic outcomes. ### Tests for User Story 2 - [x] T017 [P] [US2] Add duplicate recovery and unrecoverable-duplicate cases to `apps/platform/tests/Feature/EnvironmentReview/Spec359ReviewComposeReconciliationTest.php`. - [x] T018 [P] [US2] PGSQL duplicate-index / locking proof was deferred to `specs/360-operationrun-canonical-cutover-cleanup/` because Spec 359 merged with the runtime path in place while local PGSQL validation was still blocked. - [x] T019 [P] [US2] Add ambiguous/superseded successor cases to `apps/platform/tests/Unit/Support/Operations/Reconciliation/Spec359EnvironmentReviewComposeAdapterTest.php`. ### Implementation for User Story 2 - [x] T020 [US2] Integrate the adapter seam into `apps/platform/app/Jobs/ComposeEnvironmentReviewJob.php` for pre-proof checks, duplicate-key recovery, and clean blocked/attention/failed fallback behavior. - [x] T021 [US2] Keep `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php` pure composition only; duplicate recovery and review reuse must stay outside the composer. - [x] T022 [US2] Ensure the final decision evidence includes considered review IDs, chosen related review ID, fingerprint, workspace ID, managed environment ID, and safe status lineage only. **Checkpoint**: User Story 2 is independently functional when recoverable duplicates succeed from review truth and unrecoverable cases stop cleanly in terminal follow-up. --- ## Phase 5: User Story 3 - Keep review-start dispatch idempotent for repeated triggers (Priority: P2) **Goal**: repeated create/refresh triggers reuse the correct mutable review or active run instead of multiplying conflicting state. **Independent Test**: trigger the same review composition repeatedly and verify reuse of the active review/run path. ### Tests for User Story 3 - [x] T023 [P] [US3] Add repeated-trigger coverage to `apps/platform/tests/Feature/EnvironmentReview/Spec359ReviewComposeIdempotencyTest.php` for existing mutable review reuse and existing active run reuse. - [x] T024 [P] [US3] Deferred only the bounded review-create feedback follow-through to `specs/360-operationrun-canonical-cutover-cleanup/`, where the canonical run or related-artifact truth is finalized across current operations and review-start surfaces. ### Implementation for User Story 3 - [x] T025 [US3] Tighten `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewService.php` so `create()` / `refresh()` consider existing mutable review truth plus active compose runs before dispatching another job. - [x] T026 [US3] Deferred only the bounded `EnvironmentReviewResource` notification or link follow-through to `specs/360-operationrun-canonical-cutover-cleanup/` so it lands against the canonical read-side and correlation truth instead of the bounded Spec 359 seam alone. **Checkpoint**: User Story 3 is independently functional when duplicate clicks reuse truth and do not create competing mutable reviews or ghost runs. --- ## Phase 6: User Story 4 - Show calm review-compose reconciliation language on existing operations surfaces (Priority: P3) **Goal**: existing monitoring and review feedback surfaces explain adapter-based review truth without raw SQL/constraint wording. **Independent Test**: run one bounded browser smoke and confirm calm review-available or attention wording. ### Tests for User Story 4 - [x] T027 [P] [US4] Add `apps/platform/tests/Browser/Spec359ReviewComposeReconciliationSmokeTest.php` covering reconciled-success, attention-required, and duplicate-recovered visible states. - [x] T028 [P] [US4] Deferred only the bounded review-start or operation-surface wording follow-through to `specs/360-operationrun-canonical-cutover-cleanup/`, where any remaining copy consolidation can land against the final canonical operator wording. ### Implementation for User Story 4 - [x] T029 [US4] Deferred only the bounded wording or link follow-through needed by the canonical cutover to `specs/360-operationrun-canonical-cutover-cleanup/` instead of widening the already merged Spec 359 slice after the fact. - [x] T030 [US4] Ensure visible copy on monitoring/detail/review-start surfaces never exposes `SQLSTATE`, `duplicate key`, `environment_reviews_fingerprint_mutable_unique`, or crash/orphan claims as primary operator messaging. **Checkpoint**: User Story 4 is independently functional when operations and review-start surfaces show calm adapter-backed wording only. --- ## Phase 7: Polish & Validation - [x] T031 [P] No broader touched-file boundary was confirmed at merge; remaining canonical-cutover artifact refresh is explicitly carried by `specs/360-operationrun-canonical-cutover-cleanup/`. - [x] T032 [P] Completed at merge time in bounded form: Spec 359 shipped with focused Unit/Feature/Browser validation as recorded in merge commit `3a750726`. - [x] T033 [P] PGSQL validation was explicitly blocked at merge time and is carried forward as a named validation gap into `specs/360-operationrun-canonical-cutover-cleanup/`. - [x] T034 [P] The explicit Spec 358 regression rerun is carried forward to `specs/360-operationrun-canonical-cutover-cleanup/`, which is the post-merge canonical-cutover gate over the merged baseline. - [x] T035 [P] The named review/report regression reruns are carried forward to `specs/360-operationrun-canonical-cutover-cleanup/`, which now owns the post-merge cutover validation gate. - [x] T036 [P] Formatting and hygiene are carried forward to the active post-merge cutover validation gate in `specs/360-operationrun-canonical-cutover-cleanup/`. - [x] T037 [P] Run `git diff --check`. - [x] T038 [P] The merge close-out now records the shipped bounded adapter shape, the blocked PGSQL validation state, and the explicit Spec 360 follow-through boundary for the remaining canonical-cutover work. --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: no dependencies - **Foundational (Phase 2)**: depends on Setup and blocks all story work - **US1 (Phase 3)**: depends on Foundational completion - **US2 (Phase 4)**: depends on Foundational completion and is easiest after US1 settles the adapter contract - **US3 (Phase 5)**: depends on US1 and US2 because repeated-trigger reuse should point at the same proven truth path - **US4 (Phase 6)**: depends on US1 and US2 because visible copy needs the final decision vocabulary - **Polish (Phase 7)**: depends on all desired user stories ### Parallel Opportunities - `T002`, `T003`, and `T004` can run in parallel. - `T006`, `T007`, and `T008` can run in parallel. - `T012` and `T013` can run in parallel. - `T017`, `T018`, and `T019` can run in parallel. - `T023` and `T024` can run in parallel. - `T027` and `T028` can run in parallel. - `T032` through `T037` can run in parallel after implementation stabilizes. ### Implementation Strategy 1. Freeze the narrow contract and service-owned metadata path first. 2. Ship ready-review reuse so succeeded reconciliation has one authoritative shape. 3. Ship duplicate/superseded recovery on top of that contract. 4. Tighten repeated review-start dispatch so the entry path reuses the same truth. 5. Finish with calm visible copy, focused regressions, and explicit close-out notes. ## Non-Goals / Must-Not-Do - [x] NT001 Do not add a new `reconciled` status column, boolean, or `OperationRun` state family. - [x] NT002 Do not expand report/evidence/review-pack/restore/sync/backup/alert business reconciliation in this feature. - [x] NT003 Do not add a new queue/job family, a second operator-center UI, or a generic provider framework. - [x] NT004 Do not mutate unrelated `EnvironmentReview` records, delete records, or perform cleanup/purge work. - [x] NT005 Do not expose raw SQL/constraint/duplicate-key wording on operator-primary or customer-facing surfaces.