ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
61c4432de1
TenantAtlas/specs/115-baseline-operability-alerts/tasks.md
Ahmed Darrazi 61c4432de1 feat(115): baseline operability + alerts
2026-03-01 03:23:39 +01:00

9.7 KiB
Raw Blame History

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)

  • T001 Confirm scope + priorities in specs/115-baseline-operability-alerts/spec.md
  • 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.

  • T003 Add baseline settings definitions + strict validation in app/Support/Settings/SettingsRegistry.php
  • T004 [P] Add canonical run types for baseline operations in app/Support/OperationRunType.php
  • T005 Update baseline run creation to use canonical run types in app/Services/Baselines/BaselineCompareService.php and app/Services/Baselines/BaselineCaptureService.php
  • 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)

  • T007 [P] [US1] Add auto-close safety gate coverage in tests/Feature/Baselines/BaselineOperabilityAutoCloseTest.php
  • T008 [P] [US1] Extend lifecycle coverage (new vs reopened vs preserve open status) in tests/Feature/Baselines/BaselineCompareFindingsTest.php

Implementation

  • T009 [US1] Add safe auto-close implementation in app/Services/Baselines/BaselineAutoCloseService.php
  • T010 [US1] Preserve finding workflow state and implement reopen semantics in app/Jobs/CompareBaselineToTenantJob.php
  • T011 [US1] Apply baseline severity mapping by change_type when upserting findings in app/Jobs/CompareBaselineToTenantJob.php
  • 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

  • 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)

  • T014 [P] [US2] Add baseline drift alert event coverage in tests/Feature/Alerts/BaselineHighDriftAlertTest.php
  • T015 [P] [US2] Add baseline compare failed alert event coverage in tests/Feature/Alerts/BaselineCompareFailedAlertTest.php

Implementation

  • T016 [US2] Register baseline alert event constants in app/Models/AlertRule.php
  • T017 [US2] Add baseline event types to the rule UI options/labels in app/Filament/Resources/AlertRuleResource.php
  • T018 [US2] Produce baseline_high_drift events (baseline-only, new/reopened-only, severity threshold) in app/Jobs/Alerts/EvaluateAlertsJob.php
  • T019 [US2] Produce baseline_compare_failed events for baseline compare runs with outcome failed/partially_succeeded in app/Jobs/Alerts/EvaluateAlertsJob.php
  • T020 [US2] Ensure baseline drift event dedupe uses finding fingerprint (not numeric ID) in app/Jobs/Alerts/EvaluateAlertsJob.php

Verification

  • T021 [US2] Run focused alert tests: vendor/bin/sail artisan test --compact tests/Feature/Alerts/BaselineHighDriftAlertTest.php
  • 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)

  • T023 [P] [US3] Extend manage flow assertions for baseline settings in tests/Feature/SettingsFoundation/WorkspaceSettingsManageTest.php
  • T024 [P] [US3] Extend read-only flow assertions for baseline settings in tests/Feature/SettingsFoundation/WorkspaceSettingsViewOnlyTest.php

Implementation

  • T025 [US3] Add baseline settings fields to the settings field map in app/Filament/Pages/Settings/WorkspaceSettings.php
  • T026 [US3] Render a "Baseline settings" section (mapping + minimum severity + auto-close toggle) in app/Filament/Pages/Settings/WorkspaceSettings.php
  • T027 [US3] Ensure save/reset uses SettingsWriter validation and records audit logs for baseline settings in app/Filament/Pages/Settings/WorkspaceSettings.php

Verification

  • 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

  • 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
  • T030 Validate the manual workflow remains accurate in specs/115-baseline-operability-alerts/quickstart.md
  • T031 Run focused suites: vendor/bin/sail artisan test --compact tests/Feature/Baselines/ and vendor/bin/sail artisan test --compact tests/Feature/Alerts/
  • 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

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.