geointel/docs/20-run-readiness/CODEX_TOMORROW_RUNBOOK.md

Codex Tomorrow Runbook

Before starting

Use the latest full repo zip, extract it, and open the repository root.

Read:

1. CODEX_START.md
2. docs/00-start/START_HERE.md
3. docs/20-run-readiness/RUN_READINESS_FINAL.md
4. docs/20-run-readiness/PASS_SEQUENCE_FINAL.md
5. prompts/codex/final/DAY_1_MASTER_PROMPT.md

Operating rhythm

For each pass:

1. Restate the pass goal.
2. List files expected to change.
3. Implement only the pass scope.
4. Run the relevant commands.
5. Fix failures within scope.
6. Update status docs.
7. Produce pass report.

Do not allow Codex to drift into

• redesigning the product;
• adding auth/multi-user early;
• building a chatbot first;
• implementing LiDAR first;
• building a full report generator first;
• replacing FastAPI/PostGIS/React;
• using only demo data without real-data-ready interfaces;
• hiding broken states behind TODO comments.

Recommended first commands

find . -maxdepth 3 -type f | sort | head -200
bash scripts/check_repo_structure.sh
python scripts/smoke_docs.py
python scripts/validate_fixtures.py
python scripts/preimplementation_audit.py

If scripts fail because permissions are missing, run them with bash scriptname.sh or python scriptname.py rather than changing architecture.

Pass report template

Pass:
Scope:
Files changed:
Commands run:
Tests/smoke checks:
What works now:
Known limitations:
Architecture invariants touched:
Golden path status:
Next pass:

Stop conditions

Stop and create a proposal note instead of coding when:

• a required architecture decision is missing;
• a chosen dependency conflicts with the dependency policy;
• a requested change violates an invariant;
• API contracts require breaking changes;
• a geospatial assumption is unclear and affects data correctness.

Success definition for tomorrow

A successful day does not require every advanced module. A successful day means:

• backend foundation exists;
• database/domain foundation exists;
• project/area/dataset flow works;
• fixture vector import works;
• QA/QC can run on fixture buildings;
• GeoJSON export exists;
• minimal UI can display the workflow or at least consume the API;
• docs and tests reflect reality.