Initial public release

docs/20-run-readiness/PASS_SEQUENCE_FINAL.md

@@ -0,0 +1,206 @@
+# 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.