Initial public release

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.

docs/11-quality/SELF_REVIEW_CHECKLIST.md

@@ -0,0 +1,58 @@
+# Self-Review Checklist for Codex
+
+Codex must run this checklist before ending every implementation pass.
+
+## Product Fit
+
+- [ ] Does the work still support GeoIntel as a GeoAI Workbench?
+- [ ] Did the pass avoid adding unrelated dashboard/chat features?
+- [ ] Is the Kempen/GRB-first strategy preserved?
+
+## API and Backend
+
+- [ ] Are new endpoints documented?
+- [ ] Do endpoints return stable JSON shapes?
+- [ ] Are errors structured and useful?
+- [ ] Are validation failures explicit?
+- [ ] Are long-running tasks behind a job/status boundary?
+
+## Database
+
+- [ ] Are migrations included?
+- [ ] Are geometry columns documented?
+- [ ] Are timestamps and provenance fields included?
+- [ ] Is source metadata preserved?
+
+## Geospatial Correctness
+
+- [ ] Is CRS captured?
+- [ ] Are metric calculations done in a projected CRS?
+- [ ] Are geometries validated?
+- [ ] Are bounds and area units explicit?
+
+## AI Pipeline Correctness
+
+- [ ] Is model mode clear: real, stub or fixture?
+- [ ] Is confidence not mislabeled as accuracy?
+- [ ] Are generated detections georeferenced or explicitly not georeferenced?
+- [ ] Are model parameters stored with the run?
+
+## Frontend
+
+- [ ] Are loading, empty, error and success states implemented?
+- [ ] Does the UI use API data instead of hardcoded business data?
+- [ ] Are map layers inspectable?
+- [ ] Can users understand what happened after running an analysis?
+
+## Testing
+
+- [ ] Were relevant tests added or updated?
+- [ ] Do smoke scripts still pass?
+- [ ] Are fixtures deterministic?
+
+## Documentation
+
+- [ ] Was `CHANGELOG.md` updated?
+- [ ] Was `docs/BUILD_STATUS.md` updated?
+- [ ] Were affected specs updated?
+- [ ] Are known limitations explicit?