TenantAtlas/specs/044-drift-mvp/plan.md

Implementation Plan: Drift MVP (044)

Branch: feat/044-drift-mvp | Date: 2026-01-12 | Spec: specs/044-drift-mvp/spec.md Input: Feature specification from specs/044-drift-mvp/spec.md

Summary

Introduce a generic, persisted Finding pipeline and implement Drift as the first generator.

• Drift compares Inventory Sync Runs for the same selection scope (scope_key).
• Baseline run = previous successful run for the same scope; comparison run = latest successful run.
• Findings are persisted with deterministic fingerprints and support MVP triage (new → acknowledged).
• UI is DB-only for label/name resolution (no render-time Graph calls).
• Drift generation is tracked via BulkOperationRun for status/errors across refresh and idempotency.

Technical Context

Language/Version: PHP 8.4.x Framework: Laravel 12 Admin UI: Filament v4 + Livewire v3 Storage: PostgreSQL (JSONB) Testing: Pest v4 Target Platform: Docker (Sail-first local), Dokploy container deployments Project Type: Laravel monolith Performance Goals:

• Drift generation happens async (job), with deterministic output
• Drift listing remains filterable and index-backed Constraints:
• Tenant isolation for all reads/writes
• No render-time Graph calls; labels resolved from DB caches
• Evidence minimization (sanitized allowlist; no raw payload dumps)
• Drift generation is job-only and uses BulkOperationRun (resource=drift, action=generate) as the canonical run record Scale/Scope:
• Tenants may have large inventories; findings must be indexed for typical filtering

Constitution Check

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

• Inventory-first: Drift is derived from Inventory Sync Runs and Inventory Items (“last observed” state).
• Read/write separation: Drift generation is analytical; writes are limited to triage acknowledgement and must be audited + tested.
• Graph contract path: Drift UI performs no Graph calls; Graph calls remain isolated in existing Inventory/Graph client layers.
• Deterministic capabilities: drift scope derives from existing selection hashing and inventory type registries.
• Tenant isolation: all reads/writes tenant-scoped; no cross-tenant leakage.
• Automation: drift generation is queued; jobs are deduped/locked per scope+run pair and observable.
• Data minimization: store only minimized evidence JSON; logs contain no secrets/tokens.

Project Structure

Documentation (this feature)

specs/044-drift-mvp/
├── plan.md              # This file (/speckit.plan output)
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
│   └── admin-findings.openapi.yaml
└── tasks.md             # Phase 2 output (/speckit.tasks)

Source Code (repository root)

app/
├── Filament/
│   ├── Pages/
│   │   └── DriftLanding.php                 # drift landing page (summary + generation status)
│   └── Resources/
│       └── FindingResource/                 # list/detail + acknowledge action (tenant-scoped)
├── Jobs/
│   └── GenerateDriftFindingsJob.php         # async generator (on-demand)
├── Models/
│   └── Finding.php                          # generic finding model
└── Services/
    └── Drift/
        ├── DriftFindingGenerator.php        # computes deterministic findings for baseline/current
        ├── DriftHasher.php                  # baseline_hash/current_hash helpers
        └── DriftScopeKey.php                # scope_key is InventorySyncRun.selection_hash (single canonical definition)

database/migrations/
└── 2026_.._.._create_findings_table.php

tests/Feature/Drift/
├── DriftGenerationDeterminismTest.php
├── DriftTenantIsolationTest.php
└── DriftAcknowledgeTest.php

Structure Decision: Laravel monolith using Filament pages/resources and queued jobs.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
(none)

Phase 0 Output (Research)

Completed in specs/044-drift-mvp/research.md.

Phase 1 Output (Design)

Completed in:

• specs/044-drift-mvp/data-model.md
• specs/044-drift-mvp/contracts/
• specs/044-drift-mvp/quickstart.md

Phase 2 Planning Notes

Next step is expanding specs/044-drift-mvp/tasks.md (via /speckit.tasks) with phased, test-first implementation tasks.