ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/336-baseline-compare-product-process-flow-alignment/baseline-compare-state-contract.md
ahmido 4c661f18f0 feat: align baseline compare product process flow (#406) 
## Summary
- align the Baseline Compare landing page with the shared Product Process Flow contract introduced by Spec 332
- add the horizontal flow rendering primitive and update the landing view/state presentation for readiness, proof, evidence, and next action
- add Spec 336 artifacts, screenshots, focused feature coverage, and browser smoke coverage for the aligned states

## Testing
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareEnvironmentRouteContractTest.php tests/Feature/Filament/Spec330EnvironmentDashboardBaselineCompareProductizationTest.php tests/Feature/Filament/Spec336BaselineCompareProductProcessFlowAlignmentTest.php tests/Browser/Spec330EnvironmentDashboardBaselineCompareSmokeTest.php tests/Browser/Spec336BaselineCompareProductProcessFlowAlignmentSmokeTest.php`

## Notes
- Filament v5 / Livewire v4 stack remains unchanged
- no panel provider registration changes; `bootstrap/providers.php` is unaffected
- no global-search resource behavior changes
- no new destructive actions and no asset registration/deployment changes

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #406
2026-05-29 22:22:53 +00:00

7.9 KiB
Raw Permalink Blame History

Spec 336 - Baseline Compare State Contract

Status: implemented Created: 2026-05-29 Scope: Baseline Compare Landing (/admin/workspaces/{workspace}/environments/{environment}/baseline-compare)

This contract defines what the Baseline Compare first screen must show per repo-backed state, without inventing compare/evidence truth.

Flow Steps (Default)

The Compare readiness flow uses these fixed steps:

  1. Baseline assigned
  2. Baseline snapshot
  3. Environment snapshot / coverage proof
  4. Compare run
  5. Decision output

Allowed step state vocabulary (presentation, not a new enum family): Complete, Missing, Available, Required, In progress, Failed, Needs review, Unavailable.

State Contracts

State: no_assignment (repo-backed)

  • Visible status: Baseline not assigned
  • Reason: This environment does not have an assigned baseline.
  • Impact: Baseline drift cannot be used for governance decisions yet; compare trust is unavailable until assignment exists.
  • Primary next action: Open baseline profiles (only when authorized; otherwise show unavailable state)
  • Flow gate states:
    • Baseline assigned: Missing (current blocker)
    • Baseline snapshot: Unavailable
    • Environment snapshot / coverage proof: Available or Unavailable (repo-backed; not a blocker for compare start yet)
    • Compare run: Unavailable
    • Decision output: Unavailable
  • Available inputs: environment snapshot presence (repo-backed), but baseline artifacts and compare proof are unavailable.
  • Compare proof: Unavailable
  • Evidence state: Unavailable
  • Diagnostics default: Collapsed

State: no_snapshot (repo-backed)

  • Visible status: Baseline snapshot required
  • Reason: A baseline is assigned, but no complete/consumable baseline snapshot is available (reason code may indicate building/incomplete/superseded).
  • Impact: Compare cannot start; drift decision output is unavailable.
  • Primary next action: Open baseline snapshots or Open baseline profile (only if repo-supported and authorized).
  • Flow gate states:
    • Baseline assigned: Complete
    • Baseline snapshot: Missing or Needs review (blocked by snapshot truth)
    • Environment snapshot / coverage proof: Available / Needs review / Unavailable (repo-backed)
    • Compare run: Unavailable
    • Decision output: Unavailable
  • Available inputs: assignment + environment snapshot truth; baseline snapshot link is shown only when a real snapshot record exists.
  • Compare proof: Unavailable
  • Evidence state: Unavailable
  • Diagnostics default: Collapsed

State: invalid_scope (repo-backed)

  • Visible status: Baseline scope requires review
  • Reason: The assigned baseline scope is invalid or no longer supported.
  • Impact: Compare cannot start safely until scope is corrected; drift decisions stay unavailable.
  • Primary next action: Open baseline profile (only when authorized).
  • Flow gate states:
    • Baseline assigned: Needs review
    • Baseline snapshot: Available / Missing / Unavailable (repo-backed; do not guess)
    • Environment snapshot / coverage proof: Available / Needs review / Unavailable (repo-backed)
    • Compare run: Unavailable (blocked)
    • Decision output: Unavailable
  • Available inputs: assignment + any repo-backed baseline snapshot truth; no compare result.
  • Compare proof: Unavailable (unless a historical run exists and is in-scope/authorized; do not surface by default without proof)
  • Evidence state: Unavailable
  • Diagnostics default: Collapsed

State: idle (repo-backed)

  • Visible status: Compare run required
  • Reason: Baseline assignment and a usable snapshot exist, but no compare run exists for the current state.
  • Impact: Drift findings and decision output are not available yet.
  • Primary next action: Compare now (confirmation-required; capability-gated)
  • Flow gate states:
    • Baseline assigned: Complete
    • Baseline snapshot: Available
    • Environment snapshot / coverage proof: Available / Needs review / Unavailable (repo-backed; affects trust)
    • Compare run: Required (current blocker)
    • Decision output: Required
  • Available inputs: assignment + baseline snapshot + environment coverage proof state.
  • Compare proof: Unavailable (no run yet)
  • Evidence state: Coverage/evidence state is “unknown” until a run exists; show only repo-backed environment snapshot/coverage truth.
  • Diagnostics default: Collapsed

State: comparing (repo-backed)

  • Visible status: Compare in progress
  • Reason: A compare run is queued or running.
  • Impact: Drift findings are not final; decision output is unavailable until run completes.
  • Primary next action: View operation progress (OperationRun proof link)
  • Flow gate states:
    • Baseline assigned: Complete
    • Baseline snapshot: Available
    • Environment snapshot / coverage proof: Available / Needs review / Unavailable (repo-backed)
    • Compare run: In progress
    • Decision output: Unavailable
  • Available inputs: assignment + snapshot + OperationRun link.
  • Compare proof: Available (OperationRun)
  • Evidence state: Unavailable until completion (show only repo-backed pre-run truth)
  • Diagnostics default: Collapsed

State: failed (repo-backed)

  • Visible status: Compare failed
  • Reason: The latest compare run ended with errors (use failure summary when present).
  • Impact: Drift findings cannot be trusted until failure is resolved; treat as no usable evidence.
  • Primary next action: Review compare failure (OperationRun proof link)
  • Flow gate states:
    • Baseline assigned: Complete
    • Baseline snapshot: Available
    • Environment snapshot / coverage proof: Available / Needs review / Unavailable (repo-backed)
    • Compare run: Failed
    • Decision output: Unavailable
  • Available inputs: assignment + snapshot + OperationRun proof.
  • Compare proof: Available (OperationRun)
  • Evidence state: Unavailable
  • Diagnostics default: Collapsed

State: ready (repo-backed; findings > 0)

  • Visible status: Drift findings available
  • Reason: The latest compare produced open drift findings for this baseline comparison.
  • Impact: Review findings before presenting the environment as aligned; avoid “all clear” copy.
  • Primary next action: Review drift findings (only when authorized)
  • Flow gate states:
    • Baseline assigned: Complete
    • Baseline snapshot: Available
    • Environment snapshot / coverage proof: Available or Needs review (repo-backed)
    • Compare run: Available (completed)
    • Decision output: Available
  • Available inputs: assignment + snapshot + OperationRun proof + findings summary.
  • Compare proof: Available (OperationRun)
  • Evidence state: Needs review when coverage warnings/evidence gaps exist; otherwise “Operation proof available” only as proof basis (no evidence-pack claim).
  • Diagnostics default: Collapsed

State: ready (repo-backed; findings = 0)

  • Visible status: No drift detected (scoped to available compare coverage)
  • Reason: No open drift findings exist for this baseline comparison (may still include warnings/gaps).
  • Impact: Must not be framed as “healthy/compliant/customer-safe”. If coverage warnings or evidence gaps exist, the outcome requires review.
  • Primary next action: Review evidence / operation proof (repo-backed path only)
  • Flow gate states:
    • Baseline assigned: Complete
    • Baseline snapshot: Available
    • Environment snapshot / coverage proof: Available or Needs review (repo-backed)
    • Compare run: Available (completed)
    • Decision output: Available or Needs review (when gaps exist)
  • Available inputs: assignment + snapshot + OperationRun proof + zero-findings outcome.
  • Compare proof: Available (OperationRun)
  • Evidence state: Needs review when gaps exist; otherwise evidence remains unavailable unless a repo-real evidence artifact is linked.
  • Diagnostics default: Collapsed

Universal Defaults

  • Diagnostics default: Collapsed for all states.
  • Raw diff/payload: never default-visible.
  • One primary next action: exactly one per state.
  • No evidence-pack/customer-safe claim without a linked repo-real artifact.