geointel/docs/TODO.md

GeoIntel TODO

This file now starts with the current implementation status. Older preparation/backlog sections are preserved below as historical planning context and should not be treated as the live sprint board without checking docs/CODEX_EXECUTION_LOG.md.

Release hardening status

• Remove Python datetime.utcnow() deprecation warnings from backend service paths.
• Split frontend production build into app, React vendor and MapLibre vendor chunks.
• Enforce Python deprecation warnings as release-readiness failures.
• Fix Docker backend package install order and remove mandatory root .env dependency.
• Add Docker build context ignores for backend and frontend.
• Run Docker/PostGIS live validation on Tower/Unraid.
• Add Unraid Compose template assets with editable ports, storage path and app icon.
• Add single-container Unraid runtime with embedded PostGIS, backend and frontend.
• Remove embedded PostGIS password defaults from all-in-one Docker image metadata.
• Report reused-volume PostgreSQL collation mismatches in live migration smoke.
• Execute Tower PostgreSQL collation reindex/refresh after backup.

Current implementation status

• Backend FastAPI foundation, health endpoint and service structure.
• React/TypeScript frontend foundation and MapLibre workbench.
• Map layer visibility, opacity and feature property inspection.
• Selected project area/AOI map overlay with visibility and opacity controls.
• SQLAlchemy/PostGIS ORM models and Alembic migration chain through Sprint 9.
• Dataset upload, storage metadata and vector feature persistence.
• Raster metadata and raster operation service boundaries.
• Vector operation service boundaries and fixture-backed tests.
• Provider registry skeleton for GRB, OSM, manual and fixture providers.
• Detection Lab foundation, persistence, GeoJSON output and QA integration.
• Configured-YOLO optional dependency strategy and local preflight.
• Segmentation Lab foundation, persistence, GeoJSON output and QA integration.
• QA/QC golden benchmark fixtures and script.
• Run QA/QC golden benchmark from the main readiness gate.
• Verify browser-facing demo QA/QC metrics against the golden baseline.
• Explicit offline demo workflow seed for project, AOI, fixture datasets and persisted QA metrics.
• Project-scoped QA/QC result listing and frontend QA/QC Results panel.
• Persisted export foundation for vector/detection/segmentation GeoJSON and project metadata JSON.
• Lightweight HTML project report artifact export.
• V1 readiness handoff summary in project metadata/report exports.
• Browser-facing demo/export workflow smoke script with connected V1 state checks.
• Compact V1 workbench status strip for project, AOI, datasets, map, QA/QC and exports.
• Dry-run-first demo export artifact cleanup tooling.
• Browser-facing default workbench state smoke for the offline demo project.
• Browser-facing workbench interaction backing-state smoke and stable UI test anchors.
• Backend API contract audit comparing implemented FastAPI routes with docs/API_CONTRACTS.md.
• Live Docker/PostGIS validation on Tower/Unraid.
• Real YOLO compatibility smoke with optional AI extras and local model file.
• Detection and segmentation workflow hook extraction beyond Sprint 10.
• Export and QA/QC workflow hook extraction beyond Sprint 10.
• Dataset, raster and vector workflow hook extraction beyond Sprint 10.
• Dataset detail, raster controls and vector controls component decomposition.
• QA/QC results and map workspace component decomposition.
• Docker Compose port/storage/database configuration via .env defaults for Unraid.
• Single-container geointel Unraid compose/template runtime.
• Export preview component decomposition and HTML report download-only UX hardening.
• Provider, change-detection and map-workspace orchestration hook decomposition.
• Project/area/dataset cross-load orchestration hook decomposition.
• Demo workflow orchestration hook decomposition.
• Final App.tsx import/encoding cleanup and size audit.
• Optional final bootstrap-effect extraction.
• Decide next V1 stabilization focus: golden dataset expansion or frontend visual polish backlog.
• Expand golden QA/QC benchmark coverage across partial, perfect, no-overlap and MultiPolygon scenarios.
• Improve workbench shell visual polish, mobile navigation density and AI result readability.
• Improve Map workspace layer provenance, empty guidance and selected-feature summary readability.
• Add Data/Map mobile visual polish for upload forms, action grids and map toolbar density.
• Add AI Labs mobile visual polish for model cards, lab forms and result tables.
• Add Export/System mobile visual polish for export actions and provider capability cards.
• Add inspector mobile polish for dataset metadata, raster/vector tools and action groups.
• Add export preview readability polish for large JSON/GeoJSON handoff artifacts.
• Add accessibility focus polish for primary workbench keyboard navigation.
• Add raster/vector operation form readability polish for dense tool panels.
• Add compact loading/error/empty/result state polish across QA, exports and AI labs.
• Add compact shell density polish for topbar context, mobile navigation and workspace skip flow.
• Add Overview workspace panel hierarchy polish for readiness and recommended-action regions.
• Add Data workspace selected-summary and panel density polish.
• Add Map workspace panel hierarchy and layer-control density polish.
• Add selected map feature extraction with highlight, property table, copy and GeoJSON download.
• Add operational GIS map workflow with road basemap, persisted database layer selection and AOI/layer vector_features query run.
• Add basemap policy notice and guided GIS query-to-QA/export workflow in the Map workspace.
• Add reusable latest-result mode for repeated Map QA/QC runs without duplicate derived artifacts.
• Add opt-in Docker/Unraid AI build/runtime path for local PyTorch/Ultralytics YOLO operation.
• Surface configured-YOLO runtime preflight status through the API and Detection Lab UI.
• Add read-only local model asset catalog and Detection Lab model-file selection.
• Add live model asset detection workflow smoke for configured-YOLO runtime/provenance validation.
• Add one-click full GIS workflow action for query, derived dataset, QA/QC and export handoff.
• Add QA/QC workspace result hierarchy and filter density polish.
• Add Change Detection panel hierarchy and analysis workspace density polish.
• Add calm workbench layout pass to reduce duplicate navigation, heavy card styling and shell density.
• Add Data and Map usability layout pass with compact catalog cards and map-first spatial review.
• Add QA/QC and Exports usability layout pass with calmer evidence review and handoff artifact scanning.
• Add AI Labs Detection/Segmentation hierarchy and result density polish.
• Add Export/System handoff hierarchy and provider registry density polish.
• Add operator-provided real raster/reference detection + QA workflow smoke.
• Validate the configured building model on a real georeferenced Kempen orthophoto/GeoTIFF with persisted reference vectors and QA/QC metrics.
• Fix configured-YOLO mixed-case class labels so Building model output matches building domain filters.
• Persist CRS metadata in raster tile manifests so AI detections can be transformed to WGS84 GeoJSON correctly.
• Add real-data detection calibration sweep tooling for confidence-threshold and QA/QC metric comparison.
• Add calibration QA evidence export tooling for false-positive/false-negative inspection artifacts.
• Add real-data detection quality matrix tooling for model/tile/threshold comparison.
• Add reproducible Geel/Mol/Turnhout operator sample preparation and multi-sample quality matrix tooling.
• Run first Geel/Mol/Turnhout persisted detection quality baseline.
• Add and benchmark a stronger yolov8s building-segmentation runtime model candidate.
• Add operator-only tile-level YOLO dataset export with overlapping windows and deterministic negative tile retention.
• Train and benchmark the first tile-level local YOLO candidate on Tower through the persisted QA/QC matrix.
• Calibrate confidence, IoU and model selection against additional local orthophoto/reference samples beyond Geel/Mol/Turnhout.
• Add negative/background AOIs to the operator sample corpus and train an expanded local tile-level YOLO candidate.
• Add a hard-negative model-quality pass with sparse/background AOIs and explicit false-positive scoring.
• Train a hard-negative-balanced YOLO candidate and rerun dense QA plus background false-positive matrices.
• Benchmark an external remote-sensing YOLOv8l building candidate as an explicit local model asset.
• Train and gate the uniquehardneg160e50 YOLOv8s candidate through 7 positive AOIs and 9 hard-negative/background samples.
• Train and gate an AOI-scale aoi512e80 YOLOv8s candidate to test the 160px training-scale hypothesis.
• Raise configured-YOLO max_det through YOLO_MAX_DETECTIONS so dense AOIs are not capped at 300 detections before QA/QC.
• Rerun live dense-AOI calibration after redeploy with YOLO_MAX_DETECTIONS=1000; Westerlo reached 523/1000 detections at lower thresholds and Turnhout reached 822/1000, confirming the old 300 cap is removed.
• Add configured-YOLO cross-tile duplicate suppression and raw/suppressed calibration evidence fields.
• Rerun live dense-AOI calibration after redeploy with YOLO_DUPLICATE_IOU_THRESHOLD=0.5; Westerlo 0.25 improved to F1 0.2537313432835821 and Turnhout 0.25 improved to F1 0.14114114114114112, but the candidate remains rejected.
• Find or train a materially stronger aerial/Kempen building model candidate; geointel-building-yolov8n-expanded160e50-pt is the best current dense-AOI candidate but still too weak and too noisy for a V1 default.
• Train a higher-capacity local aerial-building detector with stronger positive recall while preserving the hard-negative false-positive gate.
• Add more diverse positive AOIs and revisit geometry-to-box label strategy before the next default-model training attempt.
• Build the next candidate gate around better positive AOI coverage, label strategy and hard-negative retention.

Sprint 8 status

• Detection foundation ORM and migration
• Detection model registry capability stubs
• Detection run service boundary
• Detection API foundation
• Detection Lab UI foundation
• Segmentation Lab foundation
• Configured YOLO local preflight
• Real YOLO/PyTorch model compatibility smoke

0. Repository Foundation

• Repo mappenstructuur voorbereiden
• Productdocumentatie voorbereiden
• Architectuurdocumentatie voorbereiden
• Codex build plan voorbereiden
• Masterprompt voorbereiden
• Init git repository
• Voeg echte backend scaffold toe
• Voeg echte frontend scaffold toe

1. Backend Foundation

• FastAPI app aanmaken
• Config systeem aanmaken
• Database connectie voorbereiden
• SQLAlchemy models toevoegen
• Alembic migrations toevoegen
• Health endpoint toevoegen
• Tests voor health endpoint toevoegen

2. Database / PostGIS

• Docker compose met PostgreSQL/PostGIS
• PostGIS extensie activeren
• projects tabel
• areas tabel
• datasets tabel
• analysis_runs tabel
• detections tabel
• quality_checks tabel
• exports tabel
• spatial indexes

3. Frontend Foundation

• React + TypeScript scaffold
• Routing
• Layout met sidebar
• API client
• Project pages
• Map Workbench basis
• Map layer controls
• Feature property inspector
• Selected area display

4. Project & Area API

• POST /projects
• GET /projects
• GET /projects/{id}
• POST /projects/{id}/areas
• GET /projects/{id}/areas
• GeoJSON validatie

5. Dataset Manager

• Upload endpoint
• Storage paths
• Raster metadata extraction
• Vector metadata extraction
• Dataset list UI
• Dataset detail UI

6. Raster Core

• Rasterio metadata reader
• Raster preview generation
• Clip raster by area
• Tile raster by area
• Save tile metadata

7. Vector Core

• GeoPandas importer
• CRS detection
• CRS transformation
• Geometry validation
• Clip vector by area
• Store features in PostGIS

8. Reference Data

• OSM fetcher als fallback
• GRB integration research verwerken in code
• Reference dataset cache
• Reference layer viewer

9. Detection Lab

• YOLO wrapper
• Model config
• Inference job
• Pixel bbox naar geo polygon
• Detections opslaan
• Detection UI
• GeoJSON export

10. QA/QC Lab

• Spatial matching
• IoU berekening
• Precision/recall/F1
• False positive layer
• False negative layer
• QA dashboard
• QA export foundation

11. Segmentation Lab

• Segmentation service design
• Mask artifact path convention
• Polygonize masks
• Segmentatiekaartlaag

12. Change Detection

• Compare two runs
• Added/removed objects
• Change stats
• Change layer

13. Tests

• Unit tests GIS helpers
• API tests
• DB/migration smoke tests
• Raster fixture tests
• Vector fixture tests
• QA/QC tests

14. Portfolio Release

• Demo dataset voorbereiden
• Demo workflow documenteren
• Screenshots toevoegen
• README portfolio sectie
• Full smoke test

Repo preparation additions

• Add Data Catalog.
• Add Analysis Specifications.
• Add QA/QC Specification.
• Add Raster Operations Specification.
• Add Vector Operations Specification.
• Add Detection Pipeline Specification.
• Add Segmentation Pipeline Specification.
• Add Change Detection Specification.
• Add UI Page Specifications.
• Add Storage Architecture.
• Add Demo Scenarios.
• Add Development Rules.
• Add Codex phase prompts.

Recommended first Codex build sequence

• Phase 1: Backend foundation using docs/CODEX_PHASE_1_PROMPT.md.
• Phase 2: Dataset Manager using docs/CODEX_PHASE_2_PROMPT.md.
• Phase 3: Detection + QA/QC skeleton using docs/CODEX_PHASE_3_PROMPT.md.

M2 Engineering Package

• Add ADR decision records.
• Add RFC placeholders for future modules.
• Add API/database/event contracts.
• Add model registry and class catalogs.
• Add queue architecture.
• Add acceptance matrix and test catalog.
• Add Codex M2 build prompts.
• Start Codex Pass 01 backend foundation.

M4 Autonomous Build Readiness

• Add M4 autonomous build readiness document.
• Add M4 sprint board.
• Add module build contracts.
• Add acceptance test catalog.
• Add API example responses.
• Add job lifecycle contract.
• Add frontend state and route contracts.
• Add backend service IO contracts.
• Add model registry seed specification.
• Add demo fixture manifest.
• Add Codex autonomous runbook.
• Add Codex pass prompts.
• Add Geel demo fixtures.

Next M5 Preparation

• Add concrete SQL migration snippets for every core table.
• Add OpenAPI YAML draft.
• Add frontend component prop contracts.
• Add backend unit-test skeleton files.
• Add frontend test skeleton files.
• Add live data connector research notes with verified endpoints.

M5 Operational Readiness Checklist

• CI/CD specification added.
• Healthcheck contracts added.
• Observability plan added.
• Troubleshooting runbook added.
• Rollback and recovery plan added.
• Security checklist added.
• Geospatial validation rules added.
• Build governance added.
• Codex pass documents added.
• Smoke scripts added.
• M6: implement actual backend foundation.
• M6: implement database migrations.
• M6: implement frontend shell.

M8 Codex Day-1 Readiness

• Add Day 1 master prompt.
• Add pass-by-pass Day 1 prompts.
• Add autonomy boundaries.
• Add failure recovery playbook.
• Add quality gate matrix.
• Add operator checklist.
• Add smoke script scaffold.
• Let Codex execute Day 1 implementation passes.

M10 Ultra Preparation

• Add autonomous build charter.
• Add Codex start-here guide.
• Add M10 master autonomous prompt.
• Add pass sequence.
• Add geometry and CRS contracts.
• Add error taxonomy.
• Add feature flag strategy.
• Add model adapter guide.
• Add QA/QC matching algorithm.
• Add frontend state machine.
• Add implementation ticket index and tickets.
• Add API example payloads.
• Add final pre-Codex checklist.

Current Workbench UI

• Replace the one-page workflow panel stack with a task-based workbench shell.
• Add persistent project/AOI/dataset/layer context.
• Move selected dataset details into a persistent inspector.
• Deploy the shell refactor to Tower and run live browser smoke on port 1202.
• Polish Data, Map and AI Labs workspaces.
• Polish QA/QC and Exports workspaces.
• Add selected-object inspector detail tabs for project, AOI, dataset, QA check, export and AI run context.
• Improve map/dataset selection ergonomics from the workbench canvas and inspector.
• Improve populated Data/Exports readability after a demo workflow run.
• Improve live visual shell width, scroll behavior and Map workspace layout at 1280px.
• Add export history filtering controls for long-running demo environments.
• Add a safe export retention/cleanup command for demo environments.
• Add a live dry-run maintenance smoke for demo export cleanup.
• Add browser screenshot artifact automation for visual regression handoff.
• Add backend error-envelope audit for expected user-error paths.
• Expand golden datasets beyond the original single building QA fixture pair.
• Add workbench visual polish pass for command bar, panel surfaces, empty states and mobile nav density.
• Add map/result overlay ergonomics for active layer provenance and feature property summaries.
• Add export/report handoff polish for artifact readiness, action grouping and export provenance.
• Polish lightweight HTML project report readability, print styling and handoff sections.
• Add Map empty-state quick actions for ready vector datasets.
• Add Data catalog role-density polish for reference/candidate/source scanning.
• Add Data catalog action polish for map, metadata, export and QA affordances.
• Add QA/QC handoff polish for candidate/reference context and persisted results.
• Add QA/QC metric card polish for precision, recall, F1, IoU and error counts.
• Add mobile overflow hardening for workbench navigation, inspector and long QA identifiers.
• Add QA/QC result filtering and density controls for long-running demo projects.
• Add Overview workflow guidance for the V1 project -> data -> map -> QA/AI -> export path.
• Audit populated demo workflow and tighten complete-state Overview guidance copy.
• Make Overview workflow rail Map/Export clicks preserve useful dataset context.
• Add latest handoff artifact cards to the Export Center for report, metadata and GeoJSON outputs.
• Add QA/QC evidence drilldown for selected checks, false-positive/negative evidence and provenance JSON.
• Add raster pipeline readiness and guardrail surfaces for metadata, CRS, preview, tile manifest and clip-AOI handoff.
• Add useful default dataset context so Data, Map and Exports are immediately usable after project/demo load.
• Make raster tile handoff to Detection Lab auto-select the configured YOLO run form.
• Add AI Lab run-readiness checks for Detection and Segmentation before job submission.
• Add AI Lab action guardrails so explicit fixture models are not exposed as normal operator runs.
• Add persisted vector area selection from the Map workspace with bbox extract and GeoJSON download.
• Persist map area selections as Export Center handoff artifacts.
• Persist map area selections as reusable derived vector datasets indexed into vector_features.
• Add Map workspace QA/QC shortcut for saved derived selection datasets.
• Add Map workspace QA/QC evidence drilldown handoff for saved selection comparisons.
• Persist QA/QC feature-level evidence for matches, false positives and false negatives.
• Render persisted QA/QC feature-level evidence as Map workspace overlays.
• Add safe local YOLO model env configuration helper for Unraid/Tower runtime activation.
• Harden configured YOLO inference for single-band raster tiles and wrapped runtime errors.
• Add operator-only YOLO dataset export and local training-smoke wrapper for real sample calibration.
• Train/evaluate a small local GeoIntel building-detector smoke from the current operator samples and reject it because QA/QC did not improve.
• Add operator-only tile-level YOLO dataset export with overlapping windows and deterministic negative tile retention.
• Run tile-level training on Tower and accept/reject the resulting local model through the persisted QA/QC matrix.
• Train/evaluate a YOLOv8s hard-negative local building-detector candidate on Tower and keep it inactive because hard-negative false positives remain.
• Add an operator-facing local model catalog/activation workflow with SHA256, active model status and explicit threshold guidance.
• Block silent local model asset auto-selection in Detection Lab.
• Add structured raster tile manifest handoff into Detection Lab with linked preflight visibility.
• Add full threshold calibration comparison UX so detection runs can compare candidate thresholds before promotion.
• Add guided in-app detection calibration runner for explicit threshold sweeps.
• Link guided calibration rows to the QA evidence map.
• Add guided calibration summary export from the Detection Lab.
• Allow the evidence bundle script to consume Detection Lab calibration summary exports.
• Add a local browser-summary QA evidence bundle smoke using mocked canonical evidence responses.
• Add a multi-AOI calibration evidence portfolio convention for model-review handoff.
• Run the first live multi-AOI calibration evidence portfolio on Tower for Geel, Mol and Turnhout.
• Run fresh positive-AOI matrix coverage for Balen, Herentals and Westerlo.
• Preserve model/tile provenance in calibration evidence bundle summaries.
• Prevent same-threshold calibration evidence responses from overwriting each other in multi-model portfolios.
• Add a model promotion decision report that combines positive-AOI score with hard-negative false-positive pressure.
• Train and reject a YOLOv8s hard-negative r8 partial candidate after 12 CPU epochs through the full positive/background promotion gate.
• Finish and reject the full YOLOv8s hard-negative r8 e60 candidate through the same promotion gate.
• Add more AOIs after the tile-level baseline so the next local model attempt is not limited to Geel/Mol/Turnhout.
• Add negative/background AOIs so the next tile dataset is not all positive tiles.
• Improve positive training coverage/label quality before the next higher-capacity model attempt; simply extending the same hardneg r8 run is not enough.

Sprint 146 - Operator YOLO dataset quality audit

• Add a dataset/label-quality audit for generated operator YOLO tile datasets.
• Report sample coverage, validation coverage, repeated hard-negative pressure and YOLO label area integrity.
• Wire the audit script into the readiness syntax gate.
• Use live audit output to decide whether the next model pass needs more positive AOIs, label cleanup or unique hard negatives.
• Add more unique background/hard-negative AOIs before repeating hard-negative-balanced YOLO training.
• Keep yolo-building-tile-expanded160 as the clean current training baseline; avoid promoting r4/r8 repeat-heavy datasets as defaults.
• Regenerate Tower operator samples, export a new unique-hard-negative tile dataset and rerun the dataset audit before training.

Sprint 147 - Unique hard-negative AOI expansion

• Expand the documented operator background candidates from 3 to 9 unique AOIs.
• Keep every new background AOI explicit, allow_empty_reference=True, and sample_role='background_candidate'.
• Add test coverage for minimum background candidate count, unique centers and regional spread.
• Prepare the new samples on Tower and build a fresh hard-negative tile dataset.
• Rebuild Tower all-in-one image so the newly copied operator scripts are available inside /app/scripts without docker cp.
• Fix YOLO preflight CLI so it respects Tower .env runtime configuration.
• Train a new candidate from yolo-building-tile-uniquehardneg160 and run the positive/background promotion gates before activating it.