210 lines
18 KiB
Markdown
210 lines
18 KiB
Markdown
# 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.
|
|
|
|
## 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 the PGSQL/browser additions remain 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 widening into unrelated lane cost.
|
|
- [ ] The declared monitoring/detail surface profile is explicit.
|
|
- [ ] 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`.
|
|
- [ ] T018 [P] [US2] Add PGSQL duplicate-index / locking proof to `apps/platform/tests/Feature/EnvironmentReview/Spec359ReviewComposeIdempotencyTest.php` and run it in the `phpunit.pgsql.xml` lane.
|
|
- [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.
|
|
- [ ] T024 [P] [US3] Extend `apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewOperationsUxTest.php` or add a Spec 359 UX companion file so review-create feedback remains truthful for already-available and open-operation cases.
|
|
|
|
### 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.
|
|
- [ ] T026 [US3] Keep `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php` on the current notification/action family and extend it only as needed to surface reused review/run truth.
|
|
|
|
**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.
|
|
- [ ] T028 [P] [US4] Extend or add focused feature assertions for EN/DE localization keys if the visible copy is mapped through current localization helpers.
|
|
|
|
### Implementation for User Story 4
|
|
|
|
- [ ] T029 [US4] Add or extend bounded EN/DE localization keys in `apps/platform/lang/en/localization.php` and `apps/platform/lang/de/localization.php` for review-compose reconciliation outcomes, reusing the current review/operations families where possible.
|
|
- [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
|
|
|
|
- [ ] T031 [P] Refresh `spec.md`, `plan.md`, and `checklists/requirements.md` only if implementation proves a thinner or broader touched-file boundary.
|
|
- [ ] T032 [P] Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec359`.
|
|
- [ ] T033 [P] Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest -c phpunit.pgsql.xml --filter=Spec359`.
|
|
- [ ] T034 [P] Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec358`.
|
|
- [ ] T035 [P] Run the named review/report regressions from the active spec:
|
|
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/CustomerReviewWorkspaceSmokeTest.php`
|
|
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec357ReportProfilesSmokeTest.php`
|
|
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/Spec357RenderedReportProfileTest.php`
|
|
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackDownloadTest.php`
|
|
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php`
|
|
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/EnvironmentReviewExecutivePackTest.php`
|
|
- [ ] T036 [P] Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`.
|
|
- [x] T037 [P] Run `git diff --check`.
|
|
- [ ] T038 [P] Record the final adapter contract shape, restore-precedent handling decision, duplicate-recovery proof boundaries, and visible wording decisions in the active feature close-out entry `Guardrail / Smoke Coverage`.
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
- [ ] NT001 Do not add a new `reconciled` status column, boolean, or `OperationRun` state family.
|
|
- [ ] NT002 Do not expand report/evidence/review-pack/restore/sync/backup/alert business reconciliation in this feature.
|
|
- [ ] NT003 Do not add a new queue/job family, a second operator-center UI, or a generic provider framework.
|
|
- [ ] NT004 Do not mutate unrelated `EnvironmentReview` records, delete records, or perform cleanup/purge work.
|
|
- [ ] NT005 Do not expose raw SQL/constraint/duplicate-key wording on operator-primary or customer-facing surfaces.
|