Initial GeoIntel V1 foundation

docs/governance/ARCHITECTURE_INVARIANTS.md

@@ -0,0 +1,43 @@
+# Architecture Invariants
+
+These invariants must remain true throughout implementation.
+
+## Core invariants
+
+1. GeoIntel is backend/API-driven. Frontend does not own business logic.
+2. PostGIS is the system of record for geometries and analysis outputs.
+3. Filesystem/object storage stores binary artifacts, not authoritative feature state.
+4. Heavy processing runs as jobs and reports state transitions.
+5. Every analysis result belongs to an `analysis_run`.
+6. Every detection/segmentation stores model metadata when produced by a model.
+7. Every dataset stores source metadata, validation state and CRS information.
+8. API responses use a consistent envelope.
+9. Frontend state follows backend truth; it may cache but not invent completion states.
+10. Exports are generated from persisted outputs, not transient frontend state.
+
+## Geospatial invariants
+
+1. API GeoJSON uses EPSG:4326 unless endpoint explicitly states otherwise.
+2. Belgian metric calculations use EPSG:31370 where possible.
+3. Area values are stored with units.
+4. Length values are stored with units.
+5. Invalid geometries are fixed, rejected or marked with a validation error; never silently accepted.
+6. MultiPolygon/MultiLineString handling must be explicit.
+7. Geometry simplification may not mutate authoritative geometry unless a derived output is created.
+
+## AI invariants
+
+1. AI inference is an analysis run.
+2. Model outputs are candidates with confidence, not ground truth.
+3. Thresholds are parameters and must be stored.
+4. Tiling parameters are parameters and must be stored.
+5. Model version is required for reproducibility.
+6. QA/QC is separate from inference.
+
+## UI invariants
+
+1. Every page has empty/loading/error/success states.
+2. Every destructive action requires confirmation.
+3. Every unavailable feature must show an honest pending state.
+4. The map is a workbench surface, not a decorative background.
+5. Metrics must always indicate source and timestamp.

docs/governance/DECISION_PRECEDENCE.md

@@ -0,0 +1,22 @@
+# Decision Precedence
+
+When documents conflict, use this precedence order.
+
+1. `docs/00-start/START_HERE.md`
+2. `docs/governance/GEOINTEL_CONSTITUTION.md`
+3. `docs/governance/ARCHITECTURE_INVARIANTS.md`
+4. `docs/governance/FORBIDDEN_DECISIONS.md`
+5. ADRs in `adr/`
+6. Canonical specs in `docs/specs/`
+7. Workflow specs in `docs/workflows/`
+8. API/database contracts in `contracts/` and `docs/API_CONTRACTS.md`
+9. Current build plans in `docs/build/`
+10. Older milestone handoffs and prompts.
+
+## Rule for outdated documents
+
+Older milestone files are historical unless referenced by the current canonical start file. Do not delete them, but do not treat them as higher authority.
+
+## Rule for autonomous improvements
+
+If an improvement is compatible with constitution, invariants, contracts, state machines and golden paths, Codex may implement it. If not, document it as a proposal.

docs/governance/FORBIDDEN_DECISIONS.md

@@ -0,0 +1,58 @@
+# Forbidden Decisions
+
+Codex and contributors must not make the following decisions without creating/updating an ADR and receiving explicit approval.
+
+## Technology changes
+
+Forbidden without ADR:
+
+- replacing FastAPI;
+- replacing React/TypeScript;
+- replacing PostgreSQL/PostGIS;
+- replacing Redis + RQ as the default queue strategy;
+- introducing a second ORM or data access pattern;
+- introducing a second map rendering framework for the same purpose;
+- replacing MapLibre/Deck.gl before V1;
+- adding a non-approved AI framework as a core dependency.
+
+## Architecture changes
+
+Forbidden:
+
+- direct model-to-frontend coupling;
+- frontend calling external geodata providers directly;
+- AI services writing directly to core tables without an analysis run;
+- storing geometries only as JSON files instead of PostGIS records;
+- bypassing the response envelope;
+- bypassing state machines;
+- creating synchronous long-running endpoints for heavy operations;
+- hardcoding demo data as if it were production data.
+
+## Product changes
+
+Forbidden:
+
+- making reporting the primary product;
+- making chatbot the primary interface;
+- removing QA/QC from the V1 critical path;
+- moving LiDAR/training/MLOps into V1 critical path;
+- changing the primary region away from the Kempen.
+
+## Data changes
+
+Forbidden:
+
+- dropping CRS metadata;
+- accepting geospatial data without validation state;
+- silently transforming CRS without recording it;
+- treating OSM as more authoritative than GRB-like reference data for the V1 QA workflow;
+- deleting original uploaded datasets when processing succeeds.
+
+## Quality changes
+
+Forbidden:
+
+- removing smoke scripts to pass CI;
+- marking a pass complete without running relevant checks;
+- adding `TODO`, `pass`, placeholder endpoints or fake success responses as completion substitutes;
+- ignoring failing golden path tests.

docs/governance/GEOINTEL_CONSTITUTION.md

@@ -0,0 +1,50 @@
+# GeoIntel Constitution
+
+This document defines the product laws. It has priority over ordinary specs when there is ambiguity.
+
+## Article 1 — GeoAI Workbench First
+
+GeoIntel is a GeoAI Workbench. It must prioritize geospatial processing, AI outputs, QA/QC and GIS exports over generic dashboards or visual polish.
+
+## Article 2 — Correct Data Beats Pretty UI
+
+When there is a tradeoff between visual presentation and correct geospatial processing, correct processing wins.
+
+## Article 3 — Every Output Must Be Traceable
+
+Every detection, segmentation, metric, export or QA score must be traceable to:
+
+- source dataset;
+- processing parameters;
+- model/version if applicable;
+- analysis run;
+- timestamp;
+- CRS and geometry assumptions.
+
+## Article 4 — AI Never Owns the Truth
+
+AI models produce candidate observations. Reference data, QA/QC and explicit metrics determine confidence and usefulness.
+
+## Article 5 — Reproducibility Is Mandatory
+
+An analysis run must be reproducible from stored metadata, parameters and input references.
+
+## Article 6 — Async Processing Is the Default for Heavy Work
+
+Raster operations, vector batch operations, detection, segmentation, QA/QC and exports should be implemented as background jobs when non-trivial.
+
+## Article 7 — No Permanent Mock-Only Features
+
+Demo fixtures are allowed, but every feature must expose a path toward real data operation. UI must not pretend unavailable functionality is complete.
+
+## Article 8 — The Kempen Use Case Drives V1
+
+Generic worldwide support is secondary. V1 must make the Geel/Mol/Turnhout/Kempen workflows excellent.
+
+## Article 9 — Architecture Must Stay Extensible
+
+Sentinel, DHMV, LiDAR, training, QGIS plugin and MLOps are future modules. V1 architecture may not block these.
+
+## Article 10 — Documentation Is Part of the Product
+
+Codex must update docs when contracts, behavior, workflows or limitations change.