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

M9 Max Preparation Pack

Status: specification expansion after M8. Purpose: make GeoIntel as close as possible to a self-driving Codex project while still allowing Codex to make local implementation improvements.

Goal

GeoIntel must be prepared so that Codex can:

1. read the repository,
2. understand the product and constraints,
3. build the foundation,
4. validate itself,
5. recover from common failures,
6. report honestly what was completed,
7. avoid architectural drift.

Principle

Strict on architecture. Flexible on implementation details.

Codex may improve:

• component structure inside the approved route/component map,
• service internals if IO contracts remain stable,
• validation messages if API envelope remains stable,
• tests if they increase coverage,
• UI polish if it does not change the workflow.

Codex may not change without explicit approval:

• backend framework,
• frontend framework,
• database choice,
• PostGIS requirement,
• core entity names,
• API response envelope,
• dataset storage layout,
• project positioning as a GeoAI Workbench,
• V1 scope freeze.

M9 Additions

This pack adds:

• final autonomous build doctrine,
• exact day-one Codex master prompt,
• build pass scorecards,
• gap-to-task conversion rules,
• real-versus-demo data policy,
• geospatial edge case handling,
• failure mode catalog,
• module data contracts,
• UI empty/loading/error states,
• API validation examples,
• seed fixtures policy,
• regression map,
• implementation review scripts,
• handoff checklist.

Expected Use Tomorrow

1. Extract the full zip.
2. Open the repository in Codex.
3. Paste prompts/codex/M9_DAY_ONE_MASTER_PROMPT.md.
4. Let Codex run Pass 0 first.
5. Require Codex to update docs/CODEX_EXECUTION_LOG.md after each pass.
6. Do not allow feature expansion until Pass 1-4 are green.

Success Definition

The preparation is successful if Codex can start from an empty implementation and produce:

• a working FastAPI app,
• a working React app,
• Docker Compose services,
• PostGIS models/migrations,
• project/area/dataset APIs,
• demo fixture loading,
• initial map UI shell,
• validation and health checks,
• tests for the implemented pieces,
• a changelog and execution log.