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