Initial public release

2026-08-31 21:56:53 +02:00
commit faeb58ef6d
1386 changed files with 263203 additions and 0 deletions
@@ -0,0 +1,86 @@
+# Codex Tomorrow Runbook
+
+## Before starting
+
+Use the latest full repo zip, extract it, and open the repository root.
+
+Read:
+
+1. `CODEX_START.md`
+2. `docs/00-start/START_HERE.md`
+3. `docs/20-run-readiness/RUN_READINESS_FINAL.md`
+4. `docs/20-run-readiness/PASS_SEQUENCE_FINAL.md`
+5. `prompts/codex/final/DAY_1_MASTER_PROMPT.md`
+
+## Operating rhythm
+
+For each pass:
+
+1. Restate the pass goal.
+2. List files expected to change.
+3. Implement only the pass scope.
+4. Run the relevant commands.
+5. Fix failures within scope.
+6. Update status docs.
+7. Produce pass report.
+
+## Do not allow Codex to drift into
+
+- redesigning the product;
+- adding auth/multi-user early;
+- building a chatbot first;
+- implementing LiDAR first;
+- building a full report generator first;
+- replacing FastAPI/PostGIS/React;
+- using only demo data without real-data-ready interfaces;
+- hiding broken states behind TODO comments.
+
+## Recommended first commands
+
+```bash
+find . -maxdepth 3 -type f | sort | head -200
+bash scripts/check_repo_structure.sh
+python scripts/smoke_docs.py
+python scripts/validate_fixtures.py
+python scripts/preimplementation_audit.py
+```
+
+If scripts fail because permissions are missing, run them with `bash scriptname.sh` or `python scriptname.py` rather than changing architecture.
+
+## Pass report template
+
+```text
+Pass:
+Scope:
+Files changed:
+Commands run:
+Tests/smoke checks:
+What works now:
+Known limitations:
+Architecture invariants touched:
+Golden path status:
+Next pass:
+```
+
+## Stop conditions
+
+Stop and create a proposal note instead of coding when:
+
+- a required architecture decision is missing;
+- a chosen dependency conflicts with the dependency policy;
+- a requested change violates an invariant;
+- API contracts require breaking changes;
+- a geospatial assumption is unclear and affects data correctness.
+
+## Success definition for tomorrow
+
+A successful day does not require every advanced module. A successful day means:
+
+- backend foundation exists;
+- database/domain foundation exists;
+- project/area/dataset flow works;
+- fixture vector import works;
+- QA/QC can run on fixture buildings;
+- GeoJSON export exists;
+- minimal UI can display the workflow or at least consume the API;
+- docs and tests reflect reality.
@@ -0,0 +1,40 @@
+# Implementation Readiness Checklist
+
+## Repo readiness
+
+- [ ] `CODEX_START.md` exists at repo root.
+- [ ] `docs/00-start/START_HERE.md` exists.
+- [ ] `docs/20-run-readiness/RUN_READINESS_FINAL.md` exists.
+- [ ] `prompts/codex/final/DAY_1_MASTER_PROMPT.md` exists.
+- [ ] `scripts/preimplementation_audit.py` runs.
+- [ ] Demo fixtures validate.
+
+## Architecture readiness
+
+- [ ] Product identity is fixed.
+- [ ] Stack is fixed.
+- [ ] Database choice is fixed.
+- [ ] CRS/GIS standards are fixed.
+- [ ] State machines are fixed.
+- [ ] Golden paths are fixed.
+- [ ] Forbidden decisions are explicit.
+
+## Build readiness
+
+- [ ] Pass order is known.
+- [ ] First vertical slice is known.
+- [ ] V1 exclusions are known.
+- [ ] Definition of Done is known.
+- [ ] Smoke tests are known.
+- [ ] Pass report format is known.
+
+## Release readiness target
+
+- [ ] Backend imports.
+- [ ] Health endpoint works.
+- [ ] Database models exist.
+- [ ] Project/Area/Dataset APIs exist.
+- [ ] Fixtures can be imported.
+- [ ] QA/QC metrics can be computed.
+- [ ] GeoJSON can be exported.
+- [ ] Minimal UI can show results.
@@ -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.
@@ -0,0 +1,37 @@
+# Repo Conflict Resolution
+
+The repo contains many milestone documents. This is intentional, but implementation must not follow conflicting instructions.
+
+## Conflict categories
+
+### Product conflict
+
+Example: one document says GeoIntel is a dashboard, another says GeoIntel is a GeoAI Workbench.
+
+Resolution: follow `GEOINTEL_CONSTITUTION.md`.
+
+### Stack conflict
+
+Example: one document suggests another backend framework.
+
+Resolution: follow ADRs and `ARCHITECTURE_INVARIANTS.md`.
+
+### Scope conflict
+
+Example: one older document prioritizes reports before QA/QC.
+
+Resolution: follow `PASS_SEQUENCE_FINAL.md` and `V1_SCOPE_FREEZE.md`.
+
+### API conflict
+
+Example: endpoint naming differs between older docs.
+
+Resolution: follow `API_CONTRACTS.md`, `API_CONTRACT_FREEZE_M2.md`, and response envelope contracts.
+
+### CRS/geospatial conflict
+
+Resolution: follow `GIS_STANDARDS.md`, `CRS_POLICY.md`, and canonical geometry contracts.
+
+## Rule
+
+When implementing, newer canonical control docs are binding. Older milestone docs are explanatory only.
@@ -0,0 +1,75 @@
+# M12 Run Readiness Final Audit
+
+## Purpose
+
+This document converts the large GeoIntel preparation set into a practical final execution layer for Codex. The repo contains many useful milestone documents, but the implementation run must follow one canonical path.
+
+## Final readiness status
+
+GeoIntel is ready to start implementation when Codex follows the canonical path below and does not treat older milestone documents as competing instructions.
+
+## Canonical control stack
+
+1. Product identity: `docs/governance/GEOINTEL_CONSTITUTION.md`
+2. Architecture invariants: `docs/governance/ARCHITECTURE_INVARIANTS.md`
+3. Forbidden decisions: `docs/governance/FORBIDDEN_DECISIONS.md`
+4. Decision precedence: `docs/governance/DECISION_PRECEDENCE.md`
+5. Domain models: `docs/specs/CANONICAL_DOMAIN_MODELS.md`
+6. GIS standards: `docs/specs/GIS_STANDARDS.md`
+7. Raster standards: `docs/specs/RASTER_STANDARDS.md`
+8. State machines: `docs/specs/STATE_MACHINES.md`
+9. Golden paths: `docs/workflows/GOLDEN_PATHS.md`
+10. Build dependency graph: `docs/build/BUILD_ORDER_DEPENDENCY_GRAPH.md`
+11. Final pass sequence: `docs/20-run-readiness/PASS_SEQUENCE_FINAL.md`
+12. Day 1 master prompt: `prompts/codex/final/DAY_1_MASTER_PROMPT.md`
+
+## Older milestone documents
+
+Older M0-M11 documents remain valuable as supporting context. They are not deleted because they contain useful details, but they must not override the canonical control stack.
+
+When in doubt, Codex must follow:
+
+`CODEX_START.md` → `START_HERE.md` → M12 run-readiness docs → governance/specs → implementation prompts.
+
+## Final V1 scope
+
+V1 is the foundation GeoAI Workbench vertical slice.
+
+V1 includes:
+
+- backend skeleton;
+- database models and migrations;
+- project CRUD;
+- area CRUD with geometry validation;
+- dataset registration/upload metadata;
+- vector import using fixtures first;
+- raster metadata extraction where libraries are available;
+- reference polygon loading;
+- predicted detection import;
+- QA/QC matching against reference polygons;
+- metric persistence;
+- GeoJSON export;
+- minimal frontend workbench;
+- status/error handling;
+- smoke tests.
+
+V1 excludes:
+
+- live production GRB sync as a blocker;
+- heavy model training;
+- full SAM/YOLO production inference as a blocker;
+- LiDAR processing;
+- MLOps registry implementation;
+- QGIS plugin;
+- multi-user permissions;
+- advanced PDF report generation.
+
+## Implementation policy
+
+Codex may improve implementation details, UX clarity, tests, types, helper abstractions and documentation. Codex must not alter product identity, stack, state machines, response envelope, database choice, CRS policy or golden path priority without an ADR proposal.
+
+## Final release target
+
+The first release target is not a complete GeoAI platform. It is a stable, demonstrable vertical slice proving that GeoIntel can move geospatial data through the core pipeline:
+
+`data → processing → geospatial output → QA/QC → export`.