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

Token and Context Budget Policy

This repository is intentionally documentation-heavy. Codex must not load all documents for every task.

Context tiers

Tier 0 — Always read

• CODEX_START.md
• docs/00-start/START_HERE.md
• docs/30-codex-optimization/CODEX_RUN_CHECKLIST.md
• active pass prompt

Tier 1 — Read when architecture-sensitive

• docs/governance/GEOINTEL_CONSTITUTION.md
• docs/governance/ARCHITECTURE_INVARIANTS.md
• docs/governance/FORBIDDEN_DECISIONS.md
• relevant ADRs

Tier 2 — Read when module-specific

• relevant module spec
• relevant skill
• relevant API/database contract
• relevant tests/fixtures

Tier 3 — Historical reference only

• old milestone handoff summaries
• previous pass prompts not active for the current run
• release notes from previous preparation milestones

Budget rules

• Prefer reading indexes before detailed specs.
• Prefer targeted grep/find over opening large unrelated docs.
• Do not re-summarize old milestones unless needed.
• Work in small coherent diffs.
• If a task requires touching more than three major subsystems, split it into passes.
• If the active prompt conflicts with governance, stop and report.

Large file policy

Large generated files, model artifacts, tiles, rasters and exports must not be created during documentation-preparation passes unless they are tiny fixtures. Real heavy assets belong outside git or in storage paths documented by docs/STORAGE_ARCHITECTURE.md.