geointel/docs/17-max-prep/M9_AUTONOMOUS_BUILD_DOCTRINE.md

M9 Autonomous Build Doctrine

Purpose

This document defines how Codex should behave when building GeoIntel with minimal human intervention.

Build Philosophy

GeoIntel must grow like a professional engineering system:

1. Contracts first.
2. Backend services second.
3. Frontend integration third.
4. AI pipelines only after stable data flow.
5. QA/QC after outputs exist.
6. Polish only after functionality is testable.

Strictness Levels

Frozen

Codex must not change these:

• FastAPI backend.
• React TypeScript frontend.
• PostgreSQL/PostGIS database.
• Docker Compose local stack.
• Project/Area/Dataset/Analysis domain model.
• API response envelope.
• Storage root conventions.
• V1 scope.

Guided

Codex may choose implementation details within these:

• exact Python package split,
• React component granularity,
• internal helper names,
• validation library patterns,
• test fixture organization,
• queue abstraction internals.

Open Improvement Area

Codex may improve freely if documented:

• UI microcopy,
• accessibility,
• loading states,
• logging clarity,
• test coverage,
• developer command quality,
• type safety.

Self-Driving Loop

Every build pass must follow this loop:

1. Read relevant specs.
2. Identify scope for the pass.
3. Implement the smallest complete vertical slice.
4. Run tests/lint/type checks where available.
5. Update execution log.
6. Update build status.
7. List next pass.

Anti-Patterns

Do not:

• create huge untested code dumps,
• implement UI without API contracts,
• invent fake geospatial values,
• build YOLO UI before dataset IO works,
• create multiple competing state stores,
• store geospatial data as plain strings when PostGIS geometry is required,
• ignore CRS handling,
• call external services without adapter boundaries.

Autonomy Boundary

Codex can keep working independently as long as:

• tests are passing or failures are honestly documented,
• no frozen decision is changed,
• V1 scope is preserved,
• every new file belongs to an approved module,
• build logs are updated.