ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/359-operationrun-reconciliation-adapter-framework-review-compose-adapter/tasks.md
ahmido 840c9bd28d refactor: rename ManagedEnvironment context badge to Environment context (#431) 
Renames ManagedEnvironment context badge to Environment context as requested.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #431
2026-06-06 20:30:26 +00:00

18 KiB
Raw Permalink 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.

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

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

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

  • T027 [P] [US4] Add apps/platform/tests/Browser/Spec359ReviewComposeReconciliationSmokeTest.php covering reconciled-success, attention-required, and duplicate-recovered visible states.
  • 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

  • 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.
  • 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] No broader touched-file boundary was confirmed at merge; remaining canonical-cutover artifact refresh is explicitly carried by specs/360-operationrun-canonical-cutover-cleanup/.
  • T032 [P] Completed at merge time in bounded form: Spec 359 shipped with focused Unit/Feature/Browser validation as recorded in merge commit 3a750726.
  • 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/.
  • 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.
  • 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.
  • T036 [P] Formatting and hygiene are carried forward to the active post-merge cutover validation gate in specs/360-operationrun-canonical-cutover-cleanup/.
  • T037 [P] Run git diff --check.
  • 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

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