ahmido
4c661f18f0
## 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
166 lines
7.9 KiB
Markdown
166 lines
7.9 KiB
Markdown
# 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.
|