geointel/docs/30-codex-optimization/CODEX_OPTIMIZATION_OVERVIEW.md

M13 Codex Optimization Overview

M13 adds an optimization layer on top of the M12 run-ready repository. The goal is to improve Codex output quality by making the implementation process more constrained where correctness matters, while still allowing local improvements inside documented boundaries.

M13 purpose

Codex should be able to:

1. choose the correct entry document without ambiguity;
2. work pass-by-pass without re-planning the whole product;
3. use reusable skills for repeated implementation patterns;
4. respect token and context budgets;
5. avoid secrets leakage;
6. split work safely across parallel agents or worktrees;
7. self-review every implementation pass against explicit gates;
8. escalate only real blockers.

New canonical Codex flow

1. Read CODEX_START.md.
2. Read docs/30-codex-optimization/CODEX_RUN_CHECKLIST.md.
3. Read docs/30-codex-optimization/PROMPT_DISCIPLINE.md.
4. Select the active pass from docs/20-run-readiness/PASS_SEQUENCE_FINAL.md.
5. Select only the relevant skill from skills/.
6. Implement the smallest coherent pass.
7. Run make readiness plus module-specific checks.
8. Fill in docs/CODEX_EXECUTION_LOG.md.
9. Produce a pass summary using prompts/codex/m13/PASS_COMPLETION_REPORT_PROMPT.md.

M13 rule hierarchy

If instructions conflict, follow this order:

1. docs/governance/GEOINTEL_CONSTITUTION.md
2. docs/governance/ARCHITECTURE_INVARIANTS.md
3. docs/governance/FORBIDDEN_DECISIONS.md
4. CODEX_START.md
5. docs/30-codex-optimization/*
6. active pass prompt
7. module documentation
8. historical milestone documents

Historical M0-M12 documents remain useful, but they must not override governance, invariants, M12 final readiness, or M13 optimization rules.