ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
77c68d2d90
TenantAtlas/specs/359-operationrun-reconciliation-adapter-framework-review-compose-adapter/tasks.md
Ahmed Darrazi 77c68d2d90
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 1m1s
Details
feat: implement review compose reconciliation adapter (spec 359)
2026-06-06 16:41:10 +02:00

18 KiB
Raw Blame History

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.

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

  • T006 [P] Add failing Unit coverage for the result/decision model in apps/platform/tests/Unit/Support/Operations/Reconciliation/Spec359ReconciliationResultTest.php.
  • 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.
  • T008 [P] Add failing Unit coverage for same-scope proof and fail-closed branches in apps/platform/tests/Unit/Support/Operations/Reconciliation/Spec359EnvironmentReviewComposeAdapterTest.php.
  • 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.
  • 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.
  • 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

  • T012 [P] [US1] Add apps/platform/tests/Feature/Operations/Spec359OperationRunAdapterReconciliationTest.php for completed/succeeded reconciliation from existing ready/published review truth.
  • 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.
  • 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

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

  • 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.
  • T019 [P] [US2] Add ambiguous/superseded successor cases to apps/platform/tests/Unit/Support/Operations/Reconciliation/Spec359EnvironmentReviewComposeAdapterTest.php.

Implementation for User Story 2

  • 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.
  • T021 [US2] Keep apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php pure composition only; duplicate recovery and review reuse must stay outside the composer.
  • 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

  • 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

  • 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

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