# Quickstart: BaselineSnapshot Artifact Truth

## Goal

Implement and verify explicit BaselineSnapshot lifecycle/completeness semantics so baseline compare and profile truth consume only complete snapshots.

## Implementation sequence

1. Add the schema changes for BaselineSnapshot lifecycle and completion metadata.
2. Add the BaselineSnapshot lifecycle enum/model helpers and a centralized consumability/effective-snapshot resolver.
3. Update capture finalization to create `building` snapshots and finalize to `complete` or `incomplete`.
4. Update profile current-snapshot promotion and supersession logic.
5. Update compare start and compare execution guards to reject non-consumable snapshots.
6. Update artifact-truth/badge presentation and the affected Filament surfaces.
7. Add conservative historical backfill logic.
8. Run focused Pest tests and format changed files.

## Focused verification commands

Start services if needed:

```bash
vendor/bin/sail up -d
```

Run the most relevant test groups:

```bash
vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCaptureTest.php
vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineComparePreconditionsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareStatsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament
vendor/bin/sail artisan test --compact tests/Unit/Badges
```

Run any new focused baseline lifecycle regression test file added during implementation:

```bash
vendor/bin/sail artisan test --compact --filter=BaselineSnapshot
```

Format changed files:

```bash
vendor/bin/sail bin pint --dirty --format agent
```

## Manual smoke checklist

1. Start a baseline capture from a workspace baseline profile and verify the produced snapshot becomes complete only after finalization.
2. Force or simulate a mid-assembly failure and verify the produced snapshot remains incomplete and is not promoted to current truth.
3. Open the baseline profile detail and confirm the latest complete snapshot remains the effective current snapshot when a newer attempt is incomplete.
4. Open baseline compare for an assigned tenant and verify compare is blocked with an operator-safe explanation when no consumable snapshot exists.
5. Open Monitoring run detail for capture/compare and confirm run outcome and snapshot lifecycle appear as separate truths.