114 lines
4.4 KiB
Markdown
114 lines
4.4 KiB
Markdown
# 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).
|
|
|
|
## 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)
|
|
**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)
|
|
|
|
```text
|
|
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)
|
|
|
|
```text
|
|
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.
|