TenantAtlas/specs/117-baseline-drift-engine/plan.md

Implementation Plan: Golden Master Baseline Drift — Deep Settings Drift via Provider Chain

Branch: 117-baseline-drift-engine | Date: 2026-03-02 | Spec: specs/117-baseline-drift-engine/spec.md

Summary

Implement a single, batch-oriented “current state hash resolver” for Golden Master baseline capture + compare.

• For each tenant subject, resolve best available evidence via provider chain (content via PolicyVersion since baseline snapshot captured time; else meta via Inventory meta contract).
• Compare baseline snapshot item hash vs current resolved hash to emit drift findings.
• Findings store + display baseline and current evidence provenance (fidelity, source, observed timestamp for each side) and add a fidelity badge + filter.
• Compare remains read-only (no new external calls during compare) and continues to run via OperationRun.

Technical Context

Language/Version: PHP 8.4 (Laravel 12) Primary Dependencies: Filament v5, Livewire v4, Pest v4 Storage: PostgreSQL (Sail) Testing: Pest (vendor/bin/sail artisan test --compact) Target Platform: Docker containers (Laravel Sail) Project Type: Web application (Laravel + Filament) Performance Goals: Baseline scope ~500 subjects resolves + compares within ~2 minutes (staging target from spec) Constraints:

• v1.5 compare MUST NOT initiate any upstream/Graph calls; DB-only + existing stored evidence only.
• Batch resolution (no per-subject query loops; chunk + set-based queries).
• Baseline snapshot items MUST NOT persist tenant identifiers. Scale/Scope: Per-run: 0–500+ subjects; per-tenant: multiple policy types; mixed evidence fidelity expected.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first: PASS — “meta evidence” comes from inventory_items (last observed); snapshot items remain immutable standards.
• Read/write separation: PASS — compare/capture are operational runs; no new write surfaces; findings are operational artifacts.
• Graph contract path: PASS — v1.5 compare uses only local DB evidence (no Graph calls).
• Deterministic capabilities: PASS — no new capabilities introduced.
• RBAC-UX / workspace+tenant isolation: PASS — use existing tenant-context Filament routes; non-members 404; members lacking capability 403.
• Run observability: PASS — both capture + compare are queued OperationRuns using OperationRunService.
• Ops-UX 3-surface feedback: PASS — existing run-start surfaces already enqueue; run detail is canonical.
• Ops-UX summary counts: PASS — any new detail stays in context; summary keys remain from OperationSummaryKeys::all().
• Badge semantics: PASS — new badges/filters will follow existing UI patterns (no ad-hoc status mappings).
• Filament action surface contract: PASS — modifying Finding list UI adds filter + badge only; no new destructive actions.

Project Structure

Documentation (this feature)

specs/117-baseline-drift-engine/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
└── contracts/
   └── openapi.yaml

Next: generate specs/117-baseline-drift-engine/tasks.md via /speckit.tasks.

Source Code (repository root)

app/
├── Jobs/
│   ├── CaptureBaselineSnapshotJob.php
│   └── CompareBaselineToTenantJob.php
├── Models/
│   ├── BaselineSnapshot.php
│   ├── BaselineSnapshotItem.php
│   ├── InventoryItem.php
│   ├── Policy.php
│   ├── PolicyVersion.php
│   └── Finding.php
├── Services/
│   ├── Baselines/
│   │   ├── BaselineCompareService.php
│   │   ├── BaselineSnapshotIdentity.php
│   │   └── (new) CurrentStateHashResolver + providers
│   └── Drift/
│       ├── DriftHasher.php
│       └── Normalizers/SettingsNormalizer.php
└── Filament/
    ├── Pages/BaselineCompareLanding.php
    └── Resources/FindingResource.php

database/migrations/
└── (new) add evidence_fidelity to findings (required for filtering)

tests/
└── Feature/ (new/updated Pest tests for resolver + compare + UI filter)

Structure Decision: Implement as an incremental change within existing Baselines/Findings domains (no new modules).

Complexity Tracking

No constitution violations are required for v1.5. (Table intentionally empty.)

Phase 0 — Research (output: research.md)

Goals:

• Confirm current baseline capture/compare logic and identify the precise extension points.
• Decide where fidelity/provenance should be stored (JSONB vs columns) to support filtering.
• Confirm real route URIs/names for contracts (Filament + Monitoring).

Deliverable: specs/117-baseline-drift-engine/research.md

Phase 1 — Design (output: data-model.md + contracts/* + quickstart.md)

Deliverables:

• Data model changes and JSON shapes: specs/117-baseline-drift-engine/data-model.md
• Endpoint reference contract (no new APIs; documented existing routes): specs/117-baseline-drift-engine/contracts/openapi.yaml
• Developer quickstart: specs/117-baseline-drift-engine/quickstart.md

Post-design constitution re-check: PASS (see Phase 1 notes in research/design outputs).

Phase 2 — Implementation Planning (high-level)

1. Implement CurrentStateHashResolver (provider chain + batch resolution).
2. Update baseline capture to store best available hash (content if present, else meta) + provenance.
3. Update baseline compare to:
   • use resolver with since = baseline_snapshots.captured_at
   • record evidence gaps in run context
   • emit findings with baseline+current provenance
4. Update Findings UI:
   • show fidelity badge
   • add fidelity filter (content/meta)
   • display baseline+current provenance fields
5. Add migration for findings.evidence_fidelity (required for fast, stable fidelity filtering).
6. Add Pest tests (resolver behavior, compare integration, UI filter query behavior).
7. Run vendor/bin/sail bin pint --dirty --format agent and focused tests.

Scope note (v2.0)

• v2.0 “full content capture mode for Golden Master” is explicitly out of scope for v1.5 implementation tasks.
• v1.5 remains opportunistic: compare is DB-only and consumes only existing stored evidence.