187 lines
9.7 KiB
Markdown
187 lines
9.7 KiB
Markdown
---
|
||
|
||
description: "Task list for Spec 115 implementation"
|
||
---
|
||
|
||
# Tasks: Baseline Operability & Alert Integration (Spec 115)
|
||
|
||
**Input**: Design documents from `/specs/115-baseline-operability-alerts/`
|
||
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md
|
||
|
||
**Tests**: REQUIRED (Pest) — this feature changes runtime behavior (Jobs/Services/Settings/UI).
|
||
|
||
**Operations (Ops-UX)**: This feature reuses `OperationRun`. Tasks must preserve the 3-surface feedback contract, keep all status/outcome transitions service-owned (via `OperationRunService`), and keep `summary_counts` numeric-only with keys from `OperationSummaryKeys::all()`.
|
||
|
||
**RBAC**: Any new/changed UI mutations or operation-start surfaces must use the capability registry (no raw strings) and preserve 404 vs 403 semantics (non-member/tenant-mismatch → 404; member missing capability → 403).
|
||
|
||
**Filament**: Any destructive-like actions must use `->requiresConfirmation()` and remain workspace vs tenant-plane correct (FR-018).
|
||
|
||
**Organization**: Tasks are grouped by user story so each story can be implemented and tested independently.
|
||
|
||
## Phase 1: Setup (Confirm Inputs)
|
||
|
||
- [X] T001 Confirm scope + priorities in specs/115-baseline-operability-alerts/spec.md
|
||
- [X] T002 Confirm implementation sequencing and touched paths in specs/115-baseline-operability-alerts/plan.md
|
||
|
||
---
|
||
|
||
## Phase 2: Foundational (Blocking Prerequisites)
|
||
|
||
**Purpose**: Shared building blocks required by US1/US2/US3.
|
||
|
||
- [X] T003 Add baseline settings definitions + strict validation in app/Support/Settings/SettingsRegistry.php
|
||
- [X] T004 [P] Add canonical run types for baseline operations in app/Support/OperationRunType.php
|
||
- [X] T005 Update baseline run creation to use canonical run types in app/Services/Baselines/BaselineCompareService.php and app/Services/Baselines/BaselineCaptureService.php
|
||
- [X] T006 [P] Add baseline compare precondition regression coverage ensuring unmet preconditions return `ok=false` and no `OperationRun` is created in tests/Feature/Baselines/BaselineComparePreconditionsTest.php
|
||
|
||
**Checkpoint**: Baseline settings keys exist with correct defaults; baseline run types are canonical and referenced from code.
|
||
|
||
---
|
||
|
||
## Phase 3: User Story 1 — Safe auto-close removes stale baseline drift (Priority: P1) 🎯
|
||
|
||
**Goal**: Resolve stale baseline drift findings only after a fully successful, complete compare, and never on `partially_succeeded`/failed/incomplete runs.
|
||
|
||
**Independent Test**: A compare that produces an initial seen fingerprint set, followed by a fully successful compare where those fingerprints are absent, resolves only the stale baseline findings.
|
||
|
||
### Tests (write first)
|
||
|
||
- [X] T007 [P] [US1] Add auto-close safety gate coverage in tests/Feature/Baselines/BaselineOperabilityAutoCloseTest.php
|
||
- [X] T008 [P] [US1] Extend lifecycle coverage (new vs reopened vs preserve open status) in tests/Feature/Baselines/BaselineCompareFindingsTest.php
|
||
|
||
### Implementation
|
||
|
||
- [X] T009 [US1] Add safe auto-close implementation in app/Services/Baselines/BaselineAutoCloseService.php
|
||
- [X] T010 [US1] Preserve finding workflow state and implement reopen semantics in app/Jobs/CompareBaselineToTenantJob.php
|
||
- [X] T011 [US1] Apply baseline severity mapping by change_type when upserting findings in app/Jobs/CompareBaselineToTenantJob.php
|
||
- [X] T012 [US1] Wire auto-close into compare completion using the safe gate (outcome+safety+completeness+kill-switch) in app/Jobs/CompareBaselineToTenantJob.php and app/Services/Baselines/BaselineAutoCloseService.php
|
||
|
||
### Verification
|
||
|
||
- [X] T013 [US1] Run focused baseline tests: `vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineOperabilityAutoCloseTest.php`
|
||
|
||
**Checkpoint**: Auto-close resolves only when safe; `partially_succeeded`/failed/incomplete compares never resolve baseline findings.
|
||
|
||
---
|
||
|
||
## Phase 4: User Story 2 — Baseline alerts are precise and deduplicated (Priority: P1)
|
||
|
||
**Goal**: Emit baseline alerts only for new/reopened baseline findings (within window), and for compare failures, with correct dedupe/cooldown.
|
||
|
||
**Independent Test**: Create baseline findings with controlled timestamps and statuses; evaluate alerts and ensure only new/reopened findings emit `baseline_high_drift` and only failed/`partially_succeeded` compares emit `baseline_compare_failed`.
|
||
|
||
### Tests (write first)
|
||
|
||
- [X] T014 [P] [US2] Add baseline drift alert event coverage in tests/Feature/Alerts/BaselineHighDriftAlertTest.php
|
||
- [X] T015 [P] [US2] Add baseline compare failed alert event coverage in tests/Feature/Alerts/BaselineCompareFailedAlertTest.php
|
||
|
||
### Implementation
|
||
|
||
- [X] T016 [US2] Register baseline alert event constants in app/Models/AlertRule.php
|
||
- [X] T017 [US2] Add baseline event types to the rule UI options/labels in app/Filament/Resources/AlertRuleResource.php
|
||
- [X] T018 [US2] Produce baseline_high_drift events (baseline-only, new/reopened-only, severity threshold) in app/Jobs/Alerts/EvaluateAlertsJob.php
|
||
- [X] T019 [US2] Produce baseline_compare_failed events for baseline compare runs with outcome failed/partially_succeeded in app/Jobs/Alerts/EvaluateAlertsJob.php
|
||
- [X] T020 [US2] Ensure baseline drift event dedupe uses finding fingerprint (not numeric ID) in app/Jobs/Alerts/EvaluateAlertsJob.php
|
||
|
||
### Verification
|
||
|
||
- [X] T021 [US2] Run focused alert tests: `vendor/bin/sail artisan test --compact tests/Feature/Alerts/BaselineHighDriftAlertTest.php`
|
||
- [X] T022 [US2] Run focused alert tests: `vendor/bin/sail artisan test --compact tests/Feature/Alerts/BaselineCompareFailedAlertTest.php`
|
||
|
||
**Checkpoint**: Alerts fire only on new/reopened baseline work; repeated compares do not re-alert the same open finding.
|
||
|
||
---
|
||
|
||
## Phase 5: User Story 3 — Workspace-controlled severity mapping and alert threshold (Priority: P2)
|
||
|
||
**Goal**: Workspace admins can configure baseline severity mapping, alert threshold, and auto-close enablement via Workspace Settings.
|
||
|
||
**Independent Test**: Saving workspace overrides updates effective values and affects newly created baseline findings and baseline alert eligibility.
|
||
|
||
### Tests (write first)
|
||
|
||
- [X] T023 [P] [US3] Extend manage flow assertions for baseline settings in tests/Feature/SettingsFoundation/WorkspaceSettingsManageTest.php
|
||
- [X] T024 [P] [US3] Extend read-only flow assertions for baseline settings in tests/Feature/SettingsFoundation/WorkspaceSettingsViewOnlyTest.php
|
||
|
||
### Implementation
|
||
|
||
- [X] T025 [US3] Add baseline settings fields to the settings field map in app/Filament/Pages/Settings/WorkspaceSettings.php
|
||
- [X] T026 [US3] Render a "Baseline settings" section (mapping + minimum severity + auto-close toggle) in app/Filament/Pages/Settings/WorkspaceSettings.php
|
||
- [X] T027 [US3] Ensure save/reset uses SettingsWriter validation and records audit logs for baseline settings in app/Filament/Pages/Settings/WorkspaceSettings.php
|
||
|
||
### Verification
|
||
|
||
- [X] T028 [US3] Run focused settings tests: `vendor/bin/sail artisan test --compact tests/Feature/SettingsFoundation/WorkspaceSettingsManageTest.php`
|
||
|
||
**Checkpoint**: Workspace overrides are validated strictly and reflected as effective settings.
|
||
|
||
---
|
||
|
||
## Phase 6: Polish & Cross-Cutting Concerns
|
||
|
||
- [X] T029 [P] Validate implementation matches the baseline alert event contract in specs/115-baseline-operability-alerts/contracts/baseline-alert-events.openapi.yaml and app/Jobs/Alerts/EvaluateAlertsJob.php
|
||
- [X] T030 Validate the manual workflow remains accurate in specs/115-baseline-operability-alerts/quickstart.md
|
||
- [X] T031 Run focused suites: `vendor/bin/sail artisan test --compact tests/Feature/Baselines/` and `vendor/bin/sail artisan test --compact tests/Feature/Alerts/`
|
||
- [X] T032 [P] Add FR-018 regression coverage ensuring Baseline Profile CRUD remains workspace-owned (not reachable via tenant-context URLs and not present in tenant navigation) in tests/Feature/Baselines/BaselineProfileWorkspaceOwnershipTest.php
|
||
|
||
---
|
||
|
||
## Dependencies & Execution Order
|
||
|
||
### Dependency Graph
|
||
|
||
```mermaid
|
||
graph TD
|
||
Setup[Phase 1: Setup] --> Foundation[Phase 2: Foundational]
|
||
Foundation --> US1[US1: Safe auto-close]
|
||
Foundation --> US2[US2: Baseline alerts]
|
||
Foundation --> US3[US3: Workspace baseline settings]
|
||
US1 --> Polish[Phase 6: Polish]
|
||
US2 --> Polish
|
||
US3 --> Polish
|
||
```
|
||
|
||
### Phase Dependencies
|
||
|
||
- **Setup (Phase 1)**: No dependencies.
|
||
- **Foundational (Phase 2)**: Blocks all user stories.
|
||
- **US1 + US2 (Phase 3–4)**: Can proceed in parallel after Phase 2.
|
||
- **US3 (Phase 5)**: Can proceed after Phase 2; does not block US1/US2 (defaults exist), but is required for workspace customization.
|
||
- **Polish (Phase 6)**: After desired user stories complete.
|
||
|
||
### User Story Dependencies
|
||
|
||
- **US1 (P1)** depends on: baseline settings defaults (T003) and compare job wiring.
|
||
- **US2 (P1)** depends on: baseline settings defaults (T003) and baseline compare run type (T004–T005).
|
||
- **US3 (P2)** depends on: baseline settings definitions (T003) and Workspace Settings page wiring (T025–T027).
|
||
|
||
---
|
||
|
||
## Parallel Execution Examples
|
||
|
||
### US1
|
||
|
||
- Run in parallel:
|
||
- T007 (auto-close tests) and T008 (lifecycle tests)
|
||
- T009 (auto-close service) and T010/T011 (compare job lifecycle + severity mapping)
|
||
|
||
### US2
|
||
|
||
- Run in parallel:
|
||
- T014 (baseline drift alert tests) and T015 (compare failed alert tests)
|
||
- T016/T017 (rule model/UI constants) while T018–T020 (job event producers) are implemented
|
||
|
||
### US3
|
||
|
||
- Run in parallel:
|
||
- T023 (manage tests) and T024 (view-only tests)
|
||
- T025 (field map) and T026 (form section rendering)
|
||
|
||
---
|
||
|
||
## Implementation Strategy
|
||
|
||
- **MVP**: Complete Phase 2 + Phase 3 (US1). This delivers operability via safe auto-close with defaults.
|
||
- **Next**: Phase 4 (US2) to make alerting low-noise and actionable.
|
||
- **Then**: Phase 5 (US3) to let workspaces tailor severity mapping and alert thresholds.
|