Initial public release

docs/16-autonomy-governance/AUTONOMY_BOUNDARIES.md

@@ -0,0 +1,45 @@
+# Autonomy Boundaries for Codex
+
+Codex should be proactive, but not uncontrolled.
+
+## Green zone — Codex can decide
+
+- function and class names when consistent with docs;
+- internal helper extraction;
+- validation improvements;
+- error message clarity;
+- test fixture additions;
+- component decomposition;
+- minor styling improvements;
+- logging improvements;
+- dependency pinning within the approved stack.
+
+## Yellow zone — Codex can decide but must document
+
+- replacing a library with an equivalent only if dependency installation fails and the replacement stays within the stack intent;
+- changing endpoint internals while preserving contracts;
+- adding new tables that support existing aggregates;
+- adding background job scaffolding earlier than planned;
+- improving storage folder structure while preserving published paths.
+
+Must be documented in:
+
+- `docs/CODEX_EXECUTION_LOG.md`;
+- `CHANGELOG.md`;
+- relevant ADR/RFC if architectural.
+
+## Red zone — Codex must stop and ask
+
+- changing FastAPI/React/PostGIS stack;
+- removing GRB-centered QA/QC direction;
+- turning the product into a generic GIS dashboard;
+- removing AI pipeline readiness;
+- changing V1 scope boundaries;
+- adding authentication/multi-user as core V1;
+- adding paid/cloud-only dependencies as mandatory;
+- implementing real external downloads without source strategy and license notes;
+- changing output formats away from GeoJSON/COCO/YOLO/masks without approval.
+
+## Safe fallback principle
+
+When a dependency, data source or model cannot be used yet, implement a controlled adapter interface and deterministic fixture-backed behavior. Mark it as a scaffold, not as production-complete.

docs/16-autonomy-governance/FAILURE_RECOVERY_PLAYBOOK.md

@@ -0,0 +1,51 @@
+# Failure Recovery Playbook
+
+Codex must not spiral when a build fails. Use this playbook.
+
+## Backend import failure
+
+1. Run the smallest import command available.
+2. Fix circular imports first.
+3. Verify package `__init__.py` files.
+4. Ensure config does not require unavailable services at import time.
+5. Add or update a smoke test.
+
+## Database failure
+
+1. Check environment variables.
+2. Check whether PostGIS extension is required at migration time.
+3. Separate pure unit tests from DB integration tests.
+4. Do not remove geometry capability to make tests pass.
+5. Document required local Postgres/PostGIS command.
+
+## Frontend build failure
+
+1. Run TypeScript check.
+2. Fix missing exports/imports.
+3. Do not silence errors with `any` unless documented and temporary.
+4. Ensure API types match contract fixtures.
+5. Add an empty/error state rather than fake success.
+
+## Rasterio/GDAL dependency failure
+
+1. Keep service interface intact.
+2. Add graceful unavailable-state handling.
+3. Keep GeoJSON/vector paths working.
+4. Document local dependency requirement.
+5. Do not fake raster metadata as real metadata.
+
+## YOLO/SAM unavailable
+
+1. Keep model registry and detection service interface.
+2. Implement deterministic fixture inference adapter.
+3. Mark adapter as demo/scaffold.
+4. Preserve output shape expected by QA/QC.
+5. Do not block foundation work.
+
+## External data source unavailable
+
+1. Fall back to fixtures.
+2. Preserve source adapter contract.
+3. Add retry/error state.
+4. Do not hardcode one live response.
+5. Document the failure in execution log.

docs/16-autonomy-governance/IMPROVEMENT_POLICY.md

@@ -0,0 +1,43 @@
+# Improvement Policy
+
+GeoIntel should be strict enough for autonomous execution but flexible enough for good engineering.
+
+## Desired improvements
+
+Codex is encouraged to improve:
+
+- typed API clients;
+- service boundaries;
+- validation specificity;
+- reusable geospatial utilities;
+- test determinism;
+- frontend state handling;
+- developer commands;
+- logging and diagnostics;
+- small UX clarity improvements.
+
+## Undesired improvements
+
+Do not add:
+
+- unrelated dashboards;
+- user accounts before V1;
+- payment/billing;
+- social features;
+- generic file manager replacing dataset manager;
+- raw LLM chatbot as a central feature;
+- unsupported live data scraping;
+- excessive styling frameworks beyond the chosen frontend stack.
+
+## Improvement report format
+
+When making improvements beyond the exact prompt, add:
+
+```text
+IMPROVEMENT:
+- what changed
+- why it helps GeoIntel
+- why it does not change scope
+```
+
+inside `docs/CODEX_EXECUTION_LOG.md`.

docs/16-autonomy-governance/QUALITY_GATE_MATRIX.md

@@ -0,0 +1,24 @@
+# Quality Gate Matrix
+
+Every implementation pass must satisfy the relevant gates.
+
+| Gate | Backend | Frontend | Data/GIS | AI | Required before merge |
+|---|---|---|---|---|---|
+| Import/build | app imports | TS builds | processing modules import | model adapters import | yes |
+| Contract | response envelope | API client typed | metadata shape stable | detection output shape stable | yes |
+| Validation | request schemas | form errors | CRS/file errors | threshold/model errors | yes |
+| Tests | unit/contract | component where feasible | fixture processing | adapter test | yes for touched area |
+| Docs | route/service docs | UI states docs | source/operation docs | model notes | yes |
+| No fake success | errors visible | empty states real | unsupported explicit | unavailable explicit | yes |
+
+## Minimum gates for Day 1
+
+- Backend health passes.
+- Project/area/dataset contracts pass.
+- Frontend shell builds.
+- Fixture metadata tests pass.
+- Smoke script documents exact failures if any remain.
+
+## Gate failure response
+
+If a gate fails, Codex must either fix it or mark the pass incomplete. Do not claim completion when validation was skipped.