Initial GeoIntel V1 foundation

docs/11-quality/REGRESSION_TRAPS.md

@@ -0,0 +1,81 @@
+# Regression Traps
+
+This document lists common failure modes Codex must actively avoid.
+
+## Geospatial Traps
+
+### CRS Loss
+
+Never store or return geometries without CRS context. GeoJSON is usually WGS84 by convention, but source CRS must still be preserved in dataset metadata.
+
+### Bounding Box Confusion
+
+Never mix `[minx, miny, maxx, maxy]` with `[west, south, east, north]` without explicitly naming fields.
+
+### Area Units
+
+Never compute area in degrees. Reproject to an appropriate projected CRS before area or distance calculations. For Flanders/Kempen, prefer Belgian Lambert 72 / EPSG:31370 for metric calculations unless a stronger reason is documented.
+
+### Raster/Vector Alignment
+
+Never compare raster-derived outputs with vector reference layers without documenting resolution, CRS and alignment assumptions.
+
+### Invalid Geometry
+
+Always validate polygons. Attempt safe fixes only when documented; otherwise return a validation error.
+
+## AI Traps
+
+### Confidence Is Not Accuracy
+
+Do not present model confidence as accuracy. Accuracy requires comparison against reference or labels.
+
+### Fixture Detection Is Not Real AI
+
+When using fixture/stub output, label it clearly as fixture/demo mode.
+
+### Silent Model Fallback
+
+Never silently fall back from real model inference to fixture mode. The response must indicate the mode used.
+
+### Mask Polygonization Noise
+
+Segmentation polygonization must include simplification/cleanup parameters and preserve original mask path.
+
+## Backend Traps
+
+### Long Work in Request Thread
+
+Do not run heavy raster/AI operations synchronously inside request handlers. Use a job boundary.
+
+### Inconsistent Status Values
+
+Use the frozen status enum only: `queued`, `running`, `completed`, `failed`, `cancelled`.
+
+### File Path Leakage
+
+API responses may expose logical storage keys or download URLs, not arbitrary host paths.
+
+## Frontend Traps
+
+### UI-Only State
+
+Do not create project, area, dataset or analysis state only in frontend memory. Persist via API.
+
+### Empty Success Screens
+
+Every page must distinguish loading, empty, error, ready and completed states.
+
+### Map Layer Ambiguity
+
+Every map layer must show source, timestamp, opacity, visibility and legend where applicable.
+
+## Documentation Traps
+
+### TODO Instead of Decision
+
+Do not use TODO comments for architecture gaps. Either implement, document a limitation, or ask for a decision.
+
+### Contract Drift
+
+If code changes API responses, update contract docs and examples in the same pass.