# 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`.