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