docs: realign milestones to agreed MVP-1 scope

TODO.md

@@ -1,139 +1,156 @@
 # Reanimator Development Milestones
 
-Use this file as the single source of truth for progress tracking and AI task delegation.
+This file is the single source of truth for delivery progress and AI task delegation.
 
 Status legend: `[ ] todo` `[-] in progress` `[x] done` `[!] blocked`
 
-## Milestone 0 - Project Bootstrap
+## MVP-1 Scope (Agreed)
 
-**Goal:** initialize repository structure and baseline tooling.
+### In Scope
+
+- Registry: `customer/project/asset/component/internal_pn (LOT)`
+- Ingest `logbundle` -> parse `first_seen` + installation relationships
+- Timeline events: `LOG_COLLECTED`, `INSTALLED`, `REMOVED`, `FIRMWARE_CHANGED`
+- UI: server card + current components + movement list
+- Basic tickets import + link to server (`asset`)
+
+### Out of Scope (After MVP-1)
+
+- AFR/MTBF production analytics
+- Spare-parts forecasting (ZIP)
+- Advanced ticket/component time-window inheritance
+- Predictive models and anomaly detection
+
+---
+
+## Milestone 0 - Bootstrap Foundation
+
+**Goal:** ready-to-build Go service skeleton and migration scaffolding.
 
 - [x] Initialize Go module (`go mod init`)
-- [x] Create folders: `cmd/reanimator-api`, `internal/{domain,repository,api,ingest,events,connectors,jobs}`
+- [x] Create base folders (`cmd`, `internal/*`, `migrations`)
-- [x] Add app entrypoint (`cmd/reanimator-api/main.go`)
+- [x] Add API entrypoint and `/health` endpoint
-- [x] Add config loading (env-based, minimal)
+- [x] Add env-based config loader
-- [x] Add migration framework and first migration folder
+- [x] Add migration loader command (`cmd/reanimator-migrate`)
-- [x] Add Makefile targets (`build`, `test`, `migrate-up`, `migrate-down`)
+- [x] Add Make targets (`build`, `test`, `run`, `migrate-up`, `migrate-down`)
+- [x] Verify `go build ./...` passes
 
-**Definition of done:**
+**Current state:** completed.
-- `go build ./...` passes
-- project starts and exposes health endpoint
 
 **AI task prompt:**
-> Implement Milestone 0 from TODO.md. Keep changes minimal and production-oriented. Update TODO.md status as you complete tasks.
+> Milestone 0 is done. Do not change bootstrap unless required by later milestones.
 
 ---
 
-## Milestone 1 - Core Schema + Registry API
+## Milestone 1 - Registry (MVP-1)
 
-**Goal:** implement core data model and CRUD for registry entities.
+**Goal:** implement registry domain and CRUD API.
 
-- [ ] Migration: `customers`, `projects`, `locations`
+- [ ] SQL migrations: `customers`, `projects`, `locations`
-- [ ] Migration: `assets`, `components`, `lots`, `installations`
+- [ ] SQL migrations: `assets`, `components`, `lots`, `installations`
-- [ ] Add required indexes from README
+- [ ] Add indexes from README
 - [ ] Repositories for registry entities
-- [ ] API endpoints for create/list/get assets/components/projects
+- [ ] API endpoints for create/list/get (`customers`, `projects`, `assets`, `components`)
-- [ ] Basic request validation and error mapping
+- [ ] Basic validation and error mapping
 
 **Definition of done:**
-- schema is applied end-to-end
+- migrations apply cleanly on MariaDB
-- registry APIs work with real MariaDB
+- registry API works end-to-end
 
 **AI task prompt:**
-> Implement Milestone 1 from TODO.md with SQL migrations and REST endpoints. Include tests for repository and handler layers.
+> Implement Milestone 1 from TODO.md. Focus on clean schema and working CRUD endpoints for registry entities. Update checkbox statuses in TODO.md.
 
 ---
 
-## Milestone 2 - Log Ingestion Pipeline
+## Milestone 2 - Ingest First Seen + Installations (MVP-1)
 
-**Goal:** support idempotent upload and observation persistence.
+**Goal:** idempotent logbundle ingestion with first useful derived data.
 
-- [ ] Migration: `log_bundles`, `observations`
+- [ ] SQL migrations: `log_bundles`, `observations`
-- [ ] `POST /ingest/logbundle` with idempotency by bundle hash
+- [ ] `POST /ingest/logbundle` idempotent by content hash
-- [ ] Store raw metadata + parsed observations
+- [ ] Persist raw bundle metadata + parsed observations
-- [ ] Parser adapter interface (pluggable parsers)
+- [ ] Detect and persist `first_seen` for components
-- [ ] Error handling for partial parse failures (without data loss)
+- [ ] Detect and persist installation relationships from observations
 
 **Definition of done:**
-- same bundle upload is idempotent
+- duplicate bundle upload does not duplicate state
-- observations are persisted and queryable
+- first_seen and installation data are queryable
 
 **AI task prompt:**
-> Implement Milestone 2 from TODO.md. Focus on idempotency and clean ingest abstractions. Add integration test for duplicate bundle upload.
+> Implement Milestone 2 from TODO.md with strict idempotency and first_seen/installation extraction. Add integration test for duplicate uploads.
 
 ---
 
-## Milestone 3 - Derived Events + Timeline
+## Milestone 3 - Timeline v1 (MVP-1)
 
-**Goal:** generate lifecycle events from observations and expose timeline APIs.
+**Goal:** produce event history visible in API and ready for UI.
 
-- [ ] Migration: `timeline_events`
+- [ ] SQL migration: `timeline_events`
-- [ ] Observation diffing service
+- [ ] Event derivation from observations/installation deltas
-- [ ] Generate events: `LOG_COLLECTED`, `INSTALLED`, `REMOVED`, `MOVED`, `FIRMWARE_CHANGED`
+- [ ] Emit: `LOG_COLLECTED`, `INSTALLED`, `REMOVED`, `FIRMWARE_CHANGED`
-- [ ] APIs: `GET /assets/{id}/timeline`, `GET /components/{id}/timeline`
+- [ ] API: `GET /assets/{id}/timeline`
-- [ ] Ensure deterministic ordering and pagination
+- [ ] API: `GET /components/{id}/timeline`
+- [ ] Deterministic sorting + pagination
 
 **Definition of done:**
-- timeline is generated from observation deltas
+- timeline endpoints return stable chronological event history
-- API returns consistent chronological history
+- install/remove/firmware changes appear correctly
 
 **AI task prompt:**
-> Implement Milestone 3 from TODO.md. Add deterministic event generation and timeline pagination. Include tests for move/install/remove scenarios.
+> Implement Milestone 3 from TODO.md. Build deterministic timeline generation and API pagination. Add tests for installed/removed/firmware-changed cases.
 
 ---
 
-## Milestone 4 - Ticket Correlation + Failure Events
+## Milestone 4 - UI v1 + Ticket Import (MVP-1)
 
-**Goal:** connect service cases to assets/components and track failures explicitly.
+**Goal:** first visible product value for operations workflow.
 
-- [ ] Migration: `tickets`, `ticket_links`, `failure_events`
+- [ ] Minimal UI: server card
-- [ ] Connector endpoint: `POST /connectors/tickets/sync`
+- [ ] Minimal UI: current components list
-- [ ] Link tickets to project/asset/component
+- [ ] Minimal UI: movement/event list from timeline
-- [ ] Implement component ticket visibility through installation time windows
+- [ ] SQL migrations: `tickets`, `ticket_links`
-- [ ] Create failure event ingestion path (`log`/`ticket`/`manual`)
+- [ ] Endpoint: `POST /connectors/tickets/sync`
+- [ ] Link ticket to server (`asset`)
 
 **Definition of done:**
-- tickets are synced and linked
+- operator opens server page and sees current hardware + movement history + linked tickets
-- failure events can be created and queried
 
 **AI task prompt:**
-> Implement Milestone 4 from TODO.md with time-window ticket correlation and explicit failure events. Add tests for inherited component visibility.
+> Implement Milestone 4 from TODO.md with minimal but usable UI and basic ticket sync/linking to assets.
 
 ---
 
-## Milestone 5 - Reliability Analytics (MVP)
+## Milestone 5 - Post-MVP Analytics
 
-**Goal:** provide first operational analytics for decision making.
+**Goal:** after MVP-1, add reliability metrics and planning value.
 
-- [ ] Aggregations by LOT, firmware, and component type
+- [ ] Explicit `failure_events` model and ingestion path
-- [ ] AFR/MTBF calculation jobs (initial version)
+- [ ] AFR/MTBF calculations by LOT/component class
-- [ ] API endpoint(s) for reliability summary
+- [ ] Firmware risk analytics
-- [ ] Background job scheduling for periodic recomputation
+- [ ] ZIP forecasting baseline
 
 **Definition of done:**
-- analytics endpoint returns stable metrics
+- metrics are reproducible and usable for operational planning
-- recalculation jobs run successfully on schedule
 
 **AI task prompt:**
-> Implement Milestone 5 from TODO.md. Prioritize correctness and reproducibility of AFR/MTBF metrics. Add test fixtures for edge cases.
+> Implement Milestone 5 from TODO.md only after MVP-1 is complete. Prioritize metric correctness and reproducibility.
 
 ---
 
 ## Cross-Cutting Tasks
 
-- [ ] Observability: structured logs + request IDs
+- [ ] Structured logs + request IDs
-- [ ] AuthN/AuthZ baseline for non-public endpoints
+- [ ] OpenAPI spec
-- [ ] OpenAPI spec and API examples
+- [ ] CI (build/test/migration check)
-- [ ] CI pipeline: build, test, migration check
+- [ ] Release note discipline
-- [ ] Release notes/changelog discipline
 
 ---
 
 ## Progress Snapshot
 
-Update this section each time work is merged.
+Update this section after each merged PR.
 
 - Last update: 2026-02-04
-- Current milestone: Milestone 1
+- Current milestone: Milestone 1 (Registry)
-- Overall progress: 1/6 milestones completed
+- MVP-1 progress: 1/5 milestones completed (Milestone 0 done)
 - Active blockers: none