TenantAtlas/specs/336-baseline-compare-product-process-flow-alignment/plan.md

Implementation Plan: Spec 336 - Baseline Compare Product Process Flow Alignment

• Branch: 336-baseline-compare-product-process-flow-alignment
• Date: 2026-05-29
• Spec: specs/336-baseline-compare-product-process-flow-alignment/spec.md
• Input: User-provided draft + repo inspection (BaselineCompareLanding, BaselineCompareStats, Spec 332 flow pattern).

Summary

Align the existing Baseline Compare Landing page to the shared Product Process Flow contract introduced in Spec 332, across repo-backed states.

This is runtime UX alignment only:

• no backend compare engine rewrite
• no new persistence
• no new OperationRun semantics
• no new evidence generator backend

Baseline Compare must become decision-first and flow-driven for the full state family, not only the no-assignment state.

Technical Context

• Language/Version: PHP 8.4.15, Laravel 12.x.
• Primary Dependencies: Filament v5 + Livewire v4, Pest v4, Tailwind v4.
• Storage: PostgreSQL; no schema change expected.
• Testing: Pest Feature/Livewire render tests + 1 browser smoke file.
• Validation Lanes: confidence + browser.
• Target Platform: Sail locally; Dokploy/container posture unchanged.
• Project Type: Laravel monolith under apps/platform.
• Performance Goals: DB-only render; no provider/Graph calls during page render; no new query families beyond existing BaselineCompareStats sources.
• Constraints: No migrations, packages, env vars, queue/scheduler/storage changes, route family changes, or legacy query alias reintroduction.

UI / Surface Guardrail Plan

• Guardrail scope: changed existing operator-facing strategic surface.
• Affected route/page/view:
  • /admin/workspaces/{workspace}/environments/{environment}/baseline-compare
  • apps/platform/app/Filament/Pages/BaselineCompareLanding.php
  • apps/platform/resources/views/filament/pages/baseline-compare-landing.blade.php
• Native vs custom: keep Filament-native primitives; reuse Spec 332 flow pattern; no new local design system.
• Decision hierarchy: decision card first, readiness flow always visible, proof/evidence panel next, diagnostics collapsed.
• One-primary-action rule: exactly one state-specific primary next action; no competing CTAs.
• Disclosure policy: raw/support/diagnostics remain collapsed and capability-aware; no raw diff by default.
• Coverage artifacts: no change to docs/ui-ux-enterprise-audit/* expected (route/archetype unchanged); proof is Spec 336 tests + screenshots.

Shared Pattern & System Fit

• Cross-cutting marker: yes (Product Process Flow consumer alignment; OperationRun proof links; decision-first vocabulary).
• Shared systems reused:
  • Spec 332 Product Process Flow pattern (Restore consumer)
  • Baseline compare truth: BaselineCompareStats, BaselineSnapshotTruthResolver
  • Operation deep links: OperationRunLinks, OperationUxPresenter, OpsUxBrowserEvents
• New abstraction: add a small presenter/view-model only if required to avoid scattering state mapping logic across Blade and the Page class. Avoid a new generic “workflow engine” layer.
• Bounded deviation: if a shared horizontal flow renderer is introduced, it must be justified by 2+ consumers and remain a small UI primitive (not a taxonomy/framework).

OperationRun UX Impact

• This spec must not change:
  • Compare now confirmation requirement (->requiresConfirmation()),
  • capability gating (TENANT_SYNC via UiEnforcement),
  • queued toast + Open operation link semantics (OperationUxPresenter, OperationRunLinks),
  • run identity/type (OperationRunType::BaselineCompare).
• Changes are limited to how Baseline Compare surfaces proof/evidence state on the page.

Provider Boundary / Platform Core Check

N/A. No provider/platform seam is changed.

Current Repo Truth Summary (Implementation-Relevant)

• Page state derives from BaselineCompareStats::forTenant():
  • no_assignment, no_snapshot, invalid_scope, idle, comparing, failed, ready.
• Readiness flow currently renders only for no_assignment (page-local array + Blade pipeline).
• Compare start uses BaselineCompareService::startCompare() and dispatches CompareBaselineToTenantJob (OperationRun-backed).
• Coverage/evidence gaps are derived from latest compare run context/diagnostics; “no drift” messaging must be caveated when gaps exist.

Implementation Approach

Phase 0 — Repo Truth Gate (No Runtime Edits)

1. Finalize repo-truth-map.md and baseline-compare-state-contract.md from actual code sources.
2. Confirm which step states are repo-real (no “stale” unless a real signal exists).

Phase 1 — Flow State Presenter (Bounded)

1. Introduce a small Baseline Compare presenter (or expand an existing one) that computes:
   • decision card fields
   • readiness flow steps across the full state family
   • proof/input panel items (repo-backed only)
   • drift summary + evidence/coverage state (separated from OperationRun proof)
   • diagnostics disclosure state (collapsed default)
2. Ensure presenter uses existing sources only (BaselineCompareStats, BaselineSnapshotTruthResolver, latest inventory sync/coverage proof, OperationRun).

Phase 2 — UI Alignment

1. Replace the page-local readiness pipeline markup with the shared Product Process Flow render primitive (or a bounded extraction consistent with Spec 332).
2. Ensure readiness flow is visible across repo-backed states (not just no_assignment).
3. Remove any duplicated lower status/summary blocks introduced by state-specific sections.
4. Keep raw diagnostics and raw diff behind disclosure by default.

Phase 3 — Truthful Drift/Evidence Messaging

1. Replace any broad “tenant matches baseline” claim with scoped wording:
   • “no open drift findings for this baseline comparison”
   • plus explicit caveat when coverage/evidence gaps exist.
2. Ensure evidence path copy never implies customer-safe output unless an actual evidence/report artifact exists and is linked.

Phase 4 — Tests

1. Add apps/platform/tests/Feature/Filament/Spec336BaselineCompareProductProcessFlowAlignmentTest.php covering the core state family.
2. Update existing Baseline Compare tests (e.g., Spec 330 file) only where necessary, keeping equivalent or stronger assertions.

Phase 5 — Browser Smoke + Screenshots

1. Add apps/platform/tests/Browser/Spec336BaselineCompareProductProcessFlowAlignmentSmokeTest.php covering:
   • no baseline, snapshot required, compare required, compare in progress, compare ready, evidence gaps, diagnostics collapsed, dark mode (if practical).
2. Capture the required screenshots under specs/336-baseline-compare-product-process-flow-alignment/artifacts/screenshots/.

Phase 6 — Hygiene + Validation

1. Run the spec’s minimal validation commands (Feature + Browser + filter run).
2. Run ./vendor/bin/sail pint --dirty and git diff --check.