geointel/docs/20-run-readiness/PASS_SEQUENCE_FINAL.md

Final Codex Pass Sequence

Codex must execute these passes in order. Do not skip ahead unless the previous pass is complete and smoke-checked.

Pass 0 — Repo audit and bootstrap

Goal: confirm the repo can be used as an implementation workspace.

Deliverables:

• confirm folder structure;
• install/dependency plan selected;
• create missing backend/frontend scaffolding only if absent;
• no product feature work yet;
• run docs smoke scripts.

Exit criteria:

• CODEX_START.md is acknowledged;
• canonical docs are read;
• no conflicting start path remains unaddressed in notes.

Pass 1 — Backend application foundation

Goal: create a FastAPI app that imports and serves health/status endpoints.

Deliverables:

• backend/app/main.py;
• settings/config module;
• API router structure;
• health endpoint;
• error envelope helper;
• minimal tests.

Exit criteria:

• backend imports successfully;
• health endpoint test passes;
• no database required yet.

Pass 2 — Database and domain foundation

Goal: establish SQLAlchemy/Alembic/PostGIS-ready domain models.

Deliverables:

• DB config;
• migration skeleton;
• models for Project, Area, Dataset, AnalysisRun, Detection, Metric, Export;
• schemas for request/response;
• geometry storage strategy documented in code comments and docs.

Exit criteria:

• migrations can be generated/applied in local environment;
• models match canonical domain docs;
• no geometry stored as arbitrary string when PostGIS type is available.

Pass 3 — Project and Area API

Goal: implement the first user-managed domain objects.

Deliverables:

• project CRUD;
• area CRUD;
• geometry validation;
• area calculation;
• API tests;
• response envelope compliance.

Exit criteria:

• create/list/read project works;
• create/list/read area works;
• invalid geometry returns controlled error.

Pass 4 — Dataset manager foundation

Goal: register datasets and extract basic metadata.

Deliverables:

• dataset upload/registration endpoint;
• metadata schema;
• storage path convention;
• fixture registration path;
• dataset state machine implemented.

Exit criteria:

• fixture vector dataset can be registered;
• dataset moves through valid states;
• failed validation is explicit.

Pass 5 — Vector processing core

Goal: load reference polygons and predicted detection polygons.

Deliverables:

• GeoJSON import;
• geometry normalization;
• CRS handling;
• feature count and bounds metrics;
• persistence of reference and predicted layers.

Exit criteria:

• reference buildings fixture imports;
• predicted buildings fixture imports;
• invalid GeoJSON is rejected safely.

Pass 6 — QA/QC engine foundation

Goal: compare predicted detections against reference polygons.

Deliverables:

• IoU/overlap matching;
• precision, recall, F1;
• false positive/false negative outputs;
• quality check records;
• tests with demo fixtures.

Exit criteria:

• expected demo metrics are reproduced or documented;
• algorithm is deterministic;
• matching thresholds are configurable but defaulted.

Pass 7 — GeoJSON export

Goal: export geospatial outputs from the system.

Deliverables:

• export endpoint;
• export records;
• GeoJSON FeatureCollection output;
• export validation;
• smoke test.

Exit criteria:

• detections export as valid GeoJSON;
• QA/QC outputs can be exported;
• no broken geometry emitted.

Pass 8 — Frontend workbench shell

Goal: create a minimal but coherent UI.

Deliverables:

• React/TypeScript app shell;
• route structure;
• project list/detail;
• map workbench placeholder with layer panel;
• API client;
• loading/error/empty states.

Exit criteria:

• frontend builds;
• health/status can be displayed;
• no hardcoded permanent fake data except clearly marked demo fixtures.

Pass 9 — Map and metrics integration

Goal: show the vertical slice visually.

Deliverables:

• render area/reference/prediction layers;
• metrics panel;
• QA/QC result cards;
• export action;
• basic style guide compliance.

Exit criteria:

• demo Geel workflow can be clicked through;
• layer visibility/opacity works at minimum level;
• UI does not obscure the map or results.

Pass 10 — Stabilization and release candidate

Goal: make the first vertical slice releasable.

Deliverables:

• smoke tests;
• docs update;
• known limitations;
• changelog;
• run instructions;
• regression checklist.

Exit criteria:

• backend tests pass;
• frontend build passes;
• demo workflow documented;
• no architecture invariant violated.