TenantAtlas/specs/359-operationrun-reconciliation-adapter-framework-review-compose-adapter/tasks.md

# 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.