Initial public release

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.