215 lines
13 KiB
Markdown
215 lines
13 KiB
Markdown
# Tasks: BaselineSnapshot Artifact Truth & Downstream Consumption Guards
|
|
|
|
**Input**: Design documents from `/specs/159-baseline-snapshot-truth/`
|
|
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/openapi.yaml, quickstart.md
|
|
|
|
**Tests**: Tests are REQUIRED for this feature because it changes runtime behavior across capture, compare, UI truth presentation, and historical backfill.
|
|
**Operations**: `baseline.capture` and `baseline.compare` already use canonical `OperationRun` flows. Tasks below preserve queued-only toasts, progress-only active surfaces, terminal `OperationRunCompleted`, service-owned run transitions, and numeric-only `summary_counts`.
|
|
**RBAC**: Workspace-plane and tenant-plane authorization behavior is preserved. Non-members remain 404, members without capability remain 403, and destructive-like actions keep `->requiresConfirmation()`.
|
|
**Badges**: All new lifecycle/usability status mapping must stay inside `BadgeCatalog` / `BadgeRenderer` / `ArtifactTruthPresenter`; no ad-hoc Filament mappings.
|
|
**List Surface Review**: Modified Baseline Profiles and Baseline Snapshots list surfaces must be reviewed against `docs/product/standards/list-surface-review-checklist.md`.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Create the shared lifecycle scaffolding this feature needs before any story-specific behavior can be implemented.
|
|
|
|
- [X] T001 Add BaselineSnapshot lifecycle/backfill schema changes in `database/migrations/2026_03_23_000001_add_lifecycle_state_to_baseline_snapshots_table.php`
|
|
- [X] T002 [P] Create the BaselineSnapshot lifecycle enum in `app/Support/Baselines/BaselineSnapshotLifecycleState.php`
|
|
- [X] T003 [P] Extend snapshot lifecycle factory states in `database/factories/BaselineSnapshotFactory.php`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Add the shared domain, reason, and badge infrastructure that all user stories depend on.
|
|
|
|
**⚠️ CRITICAL**: No user story work should start until this phase is complete.
|
|
|
|
- [X] T004 Update lifecycle casts, transition helpers, and consumable scopes in `app/Models/BaselineSnapshot.php`
|
|
- [X] T005 [P] Add effective-snapshot and consumability resolution in `app/Services/Baselines/BaselineSnapshotTruthResolver.php`
|
|
- [X] T006 [P] Add non-consumable baseline reason codes in `app/Support/Baselines/BaselineReasonCodes.php`
|
|
- [X] T007 [P] Add lifecycle/operator-safe reason translations in `app/Support/ReasonTranslation/ReasonTranslator.php`
|
|
- [X] T008 [P] Register the new lifecycle badge domain in `app/Support/Badges/BadgeDomain.php` and `app/Support/Badges/BadgeCatalog.php`
|
|
- [X] T009 [P] Add lifecycle taxonomy and badge mapping in `app/Support/Badges/OperatorOutcomeTaxonomy.php` and `app/Support/Badges/Domains/BaselineSnapshotLifecycleBadge.php`
|
|
|
|
**Checkpoint**: Shared lifecycle, resolver, and badge infrastructure are ready for story work.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Trust Only Complete Baselines (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Capture must only promote complete snapshots as effective baseline truth, while partial or failed captures remain explicitly unusable.
|
|
|
|
**Independent Test**: Start a successful capture and verify the snapshot ends `complete` and becomes current truth; simulate a partial-write failure and verify the snapshot ends `incomplete` and the previous complete snapshot remains current.
|
|
|
|
### Tests for User Story 1 ⚠️
|
|
|
|
> **NOTE: Write these tests first and confirm they fail before implementation.**
|
|
|
|
- [X] T010 [P] [US1] Add BaselineSnapshot lifecycle domain tests in `tests/Unit/Baselines/BaselineSnapshotLifecycleTest.php`
|
|
- [X] T011 [P] [US1] Update capture lifecycle and partial-write regression coverage in `tests/Feature/Baselines/BaselineCaptureTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T012 [US1] Add current-consumable snapshot helpers to `app/Models/BaselineProfile.php`
|
|
- [X] T013 [US1] Create `building` snapshots and completion-proof finalization in `app/Jobs/CaptureBaselineSnapshotJob.php`
|
|
- [X] T014 [US1] Guard `active_snapshot_id` promotion and current-snapshot rollover in `app/Jobs/CaptureBaselineSnapshotJob.php`
|
|
|
|
**Checkpoint**: Capture produces explicit lifecycle truth and only complete snapshots become effective current baselines.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Block Unsafe Compare Input (Priority: P2)
|
|
|
|
**Goal**: Compare must resolve only consumable snapshots and fail safely when the selected or implicit baseline is building, incomplete, or otherwise unusable.
|
|
|
|
**Independent Test**: Attempt compare with a complete snapshot, a building snapshot, and an incomplete snapshot; only the complete path should proceed while blocked cases return clear operator-safe reasons.
|
|
|
|
### Tests for User Story 2 ⚠️
|
|
|
|
- [X] T015 [P] [US2] Update compare precondition coverage for building/incomplete snapshots in `tests/Feature/Baselines/BaselineComparePreconditionsTest.php`
|
|
- [X] T016 [P] [US2] Add compare execution guard regression coverage in `tests/Feature/Baselines/BaselineCompareExecutionGuardTest.php`
|
|
- [X] T017 [P] [US2] Update effective-snapshot fallback and blocked-state stats coverage in `tests/Feature/Baselines/BaselineCompareStatsTest.php`
|
|
- [X] T018 [P] [US2] Add compare/capture confirmation and authorization regression coverage in `tests/Feature/Filament/BaselineActionAuthorizationTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T019 [US2] Resolve only effective consumable snapshots and block historical explicit overrides in `app/Services/Baselines/BaselineCompareService.php`
|
|
- [X] T020 [US2] Reject non-consumable snapshots during job execution in `app/Jobs/CompareBaselineToTenantJob.php`
|
|
- [X] T021 [US2] Derive compare availability from effective snapshot truth in `app/Support/Baselines/BaselineCompareStats.php`
|
|
- [X] T022 [US2] Surface blocked compare reasons while preserving confirmation and authorization rules on the tenant compare page in `app/Filament/Pages/BaselineCompareLanding.php`
|
|
- [X] T023 [US2] Sync compare warning widgets with blocked-state stats in `app/Filament/Widgets/Tenant/BaselineCompareCoverageBanner.php` and `app/Filament/Widgets/Dashboard/BaselineCompareNow.php`
|
|
|
|
**Checkpoint**: Compare can only run against complete snapshots and reports clear reasons when no consumable baseline exists.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - See Run Truth And Artifact Truth Separately (Priority: P3)
|
|
|
|
**Goal**: Operators can distinguish run outcome, snapshot lifecycle, snapshot usability, and historical status across the affected workspace and tenant surfaces.
|
|
|
|
**Independent Test**: Review baseline profile detail, baseline snapshot list/detail, compare landing, and run detail for complete, incomplete, and historically superseded snapshots; each surface must present run truth and artifact truth as separate concepts.
|
|
|
|
### Tests for User Story 3 ⚠️
|
|
|
|
- [X] T024 [P] [US3] Extend governance artifact-truth badge coverage in `tests/Unit/Badges/GovernanceArtifactTruthTest.php`
|
|
- [X] T025 [P] [US3] Add BaselineSnapshot artifact-truth presenter tests in `tests/Unit/Support/GovernanceArtifactTruth/BaselineSnapshotArtifactTruthTest.php`
|
|
- [X] T026 [P] [US3] Add baseline profile, snapshot, and compare truth-surface coverage in `tests/Feature/Filament/BaselineSnapshotTruthSurfaceTest.php`
|
|
- [X] T027 [P] [US3] Add monitoring run-detail baseline truth coverage in `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T028 [US3] Update BaselineSnapshot truth envelopes in `app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php`
|
|
- [X] T029 [US3] Show lifecycle and usability state in `app/Filament/Resources/BaselineSnapshotResource.php`
|
|
- [X] T030 [US3] Show effective-vs-latest snapshot truth in `app/Filament/Resources/BaselineProfileResource.php`
|
|
- [X] T031 [US3] Align capture and compare header actions with current-truth, confirmation, and authorization rules in `app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php`
|
|
- [X] T032 [US3] Update snapshot detail enterprise state in `app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php`
|
|
- [X] T033 [US3] Separate run outcome from snapshot truth on monitoring run detail in `app/Filament/Resources/OperationRunResource.php`
|
|
|
|
**Checkpoint**: Operators can read baseline trust accurately without inferring artifact completeness from run outcome alone.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Finish legacy handling, regression coverage, and validation for the complete feature.
|
|
|
|
- [X] T034 [P] Add deterministic expected-item decision-table coverage for legacy backfill in `tests/Feature/Baselines/BaselineSnapshotBackfillTest.php`
|
|
- [X] T035 Update expected-item decision-table legacy backfill branches in `database/migrations/2026_03_23_000001_add_lifecycle_state_to_baseline_snapshots_table.php`
|
|
- [X] T036 [P] Refresh lifecycle taxonomy regression coverage in `tests/Unit/Badges/OperatorOutcomeTaxonomyTest.php`
|
|
- [X] T037 [P] Add lifecycle auditability coverage for producing-run links, incomplete reasons, and derived historical truth in `tests/Feature/Baselines/BaselineSnapshotLifecycleAuditabilityTest.php`
|
|
- [X] T038 [P] Add Ops-UX guard coverage for service-owned run transitions and canonical terminal notifications in `tests/Feature/Operations/BaselineOperationRunGuardTest.php`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: Starts immediately.
|
|
- **Foundational (Phase 2)**: Depends on Setup completion and blocks all user stories.
|
|
- **User Stories (Phases 3-5)**: All depend on Foundational completion.
|
|
- **Polish (Phase 6)**: Depends on the desired user stories being complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: Starts after Foundational and delivers the MVP.
|
|
- **User Story 2 (P2)**: Starts after Foundational; it depends on shared lifecycle and resolver infrastructure but not on US1 implementation order.
|
|
- **User Story 3 (P3)**: Starts after Foundational; it depends on shared lifecycle and badge infrastructure but can proceed independently of US1 and US2 if teams split work.
|
|
|
|
### Within Each User Story
|
|
|
|
- Write tests first and confirm they fail before implementation.
|
|
- Update shared/domain helpers before wiring them into services, jobs, or Filament surfaces.
|
|
- Finish model/service/job behavior before final UI and stats integration.
|
|
- Keep each story independently verifiable against its stated checkpoint.
|
|
|
|
## Parallel Opportunities
|
|
|
|
- `T002` and `T003` can run in parallel after `T001`.
|
|
- `T005` through `T009` can run in parallel once `T004` defines the model lifecycle contract.
|
|
- Story test tasks marked `[P]` can run in parallel within each user story.
|
|
- UI tasks in US3 can split across separate resources/pages once `T026` lands the shared artifact-truth envelope changes.
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Write and run the capture-focused tests in parallel:
|
|
T010 tests/Unit/Baselines/BaselineSnapshotLifecycleTest.php
|
|
T011 tests/Feature/Baselines/BaselineCaptureTest.php
|
|
|
|
# After tests exist, split the model/job work:
|
|
T012 app/Models/BaselineProfile.php
|
|
T013 app/Jobs/CaptureBaselineSnapshotJob.php
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Compare guard tests can be prepared together:
|
|
T015 tests/Feature/Baselines/BaselineComparePreconditionsTest.php
|
|
T016 tests/Feature/Baselines/BaselineCompareExecutionGuardTest.php
|
|
T017 tests/Feature/Baselines/BaselineCompareStatsTest.php
|
|
T018 tests/Feature/Filament/BaselineActionAuthorizationTest.php
|
|
|
|
# Then service/job/page updates can be split by file:
|
|
T019 app/Services/Baselines/BaselineCompareService.php
|
|
T020 app/Jobs/CompareBaselineToTenantJob.php
|
|
T022 app/Filament/Pages/BaselineCompareLanding.php
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Shared truth tests can be prepared together:
|
|
T024 tests/Unit/Badges/GovernanceArtifactTruthTest.php
|
|
T025 tests/Unit/Support/GovernanceArtifactTruth/BaselineSnapshotArtifactTruthTest.php
|
|
T026 tests/Feature/Filament/BaselineSnapshotTruthSurfaceTest.php
|
|
T027 tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
|
|
|
|
# After T028 lands shared presenter changes, UI files can split:
|
|
T029 app/Filament/Resources/BaselineSnapshotResource.php
|
|
T030 app/Filament/Resources/BaselineProfileResource.php
|
|
T033 app/Filament/Resources/OperationRunResource.php
|
|
```
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First
|
|
|
|
1. Complete Phase 1 and Phase 2.
|
|
2. Deliver User Story 1 as the MVP so capture truth is no longer ambiguous.
|
|
3. Validate US1 with the focused capture lifecycle tests before moving on.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Add User Story 2 to block unsafe compare input once capture truth is explicit.
|
|
2. Add User Story 3 to make the new truth model visible and operator-safe across the affected surfaces.
|
|
3. Finish Phase 6 for deterministic legacy backfill and regression hardening.
|
|
|
|
### Suggested MVP Scope
|
|
|
|
- Phase 1: Setup
|
|
- Phase 2: Foundational
|
|
- Phase 3: User Story 1 only
|