geointel/docs/12-build-control/CODEX_DECISION_BOUNDARIES.md

Codex Decision Boundaries

This document defines where Codex has freedom and where it must not decide alone.

Codex Can Decide

• internal helper function names
• folder organization within already approved domains
• UI microcopy that clarifies state
• additional tests
• stricter validation when compatible with contracts
• small refactors that reduce duplication
• dependency minor versions when compatible
• CSS implementation details

Codex Must Follow Existing Specs

• primary tech stack
• FastAPI backend
• React frontend
• PostGIS database
• GRB-first reference strategy
• status enums
• API envelopes
• CRS calculation rules
• QA/QC formulas
• V1 scope boundaries
• build sequence

Codex Must Ask or Stop

• replacing FastAPI, PostGIS, React or MapLibre
• changing project direction from GeoAI Workbench
• adding authentication
• adding paid services
• changing reference data strategy
• changing scoring/math definitions
• presenting fixture output as real AI
• introducing non-deterministic tests
• removing docs/tests to make builds pass

Improvement Rule

If Codex sees a better approach, it may implement it only when:

1. it is backward compatible with specs
2. it improves correctness, reliability or clarity
3. it updates docs and tests
4. it does not expand V1 scope

If not, document it as a proposal in docs/PROPOSED_IMPROVEMENTS.md.