adaptive-codex-router

# Adaptive Codex Router Apply a conservative routing heuristic until benchmark evidence exists. After calibration, choose among configurations that preserve the task-specific quality floor, prioritizing quality first, speed second, and token or credit use third. ## Route a task 1. Identify the deliverable stage: `exploratory`, `internal`, `final`, or `high-risk`. 2. Identify the task type, stakes, ambiguity, scope, urgency, and whether meaningful parallel decomposition exists. 3. Run `scripts/route_task.py` with the task text and any known overrides. 4. Inspect the generated quality contract, assumptions, route confidence, and speed-support warning. 5. Apply the recommendation before starting a new root task. For an already-running root task, use the route for a new `codex exec`, a configured worker, or the next task; do not claim to have changed the current model retroactively. 6. Execute the relevant gates in `references/quality-gates.md`. 7. Deliver only after all hard gates pass. On failure, repair the failed part and escalate one step: effort first, model second, independent review or Ultra third. Example: ```bash python3 scripts/route_task.py \ "Implementar uma correção Python pequena e rodar os testes" \ --stage internal --shell-command ``` Use `scripts/run_routed_task.py` only when the user has authorized execution. It defaults to dry-run, sends prompts through stdin, records a private `0600` JSON log with content redacted by default, and never retries a failed mutating task automatically. It executes only `single-agent` worker routes; orchestrate staged, reviewed, or Ultra plans with separate workers and gates rather than degrading them silently. Add `--skip-git-repo-check` only for a directory deliberately chosen for non-repository work or when trust has been checked separately; never apply it silently. ## Apply the policy - Treat zero critical errors and all mandatory gates as non-compensatory constraints. - Prefer Luna for clear, repeatable, mechanically verifiable work. - Prefer Terra for ordinary implementation, analysis, synthesis, and tool use. - Prefer Sol for ambiguous, high-value, open-ended, formal, causal, or publication-facing work. - Prefer Fast for Luna and Terra by default. Record `requested` and `effective` speed separately. If the active catalog rejects Fast, stop, disclose the rejection, and relaunch at an accepted speed only when doing so cannot duplicate side effects or after explicit confirmation. - For large mechanical or classification batches, use a staged pilot → batch → independent sample audit. Do not send an untested heterogeneous corpus directly to Luna. - Use Max only for an exceptionally hard single-agent problem. - Use Ultra only when the work has independent subproblems and a final integrator or reviewer. - Represent mandatory independent review in the orchestration plan even when the implementation itself is single-agent. - Require an explicit adversarial review step for high-risk work and publication-facing formal results. - Escalate uncertainty upward. Never downgrade merely because the prompt is short. - Do not invent pass probabilities. Mark routes `uncalibrated` until representative benchmark evidence exists. - Call uncalibrated output a conservative heuristic, never an empirical optimum. - Compare expected end-to-end latency, including likely repair and rerun time, rather than first-response latency alone. ## Maintain and calibrate - Read `references/routing-policy.json` when changing thresholds or mappings. - Read `references/model-capabilities.json` when model availability, effort levels, or speed tiers may have changed. Refresh current official documentation when its `checked_at` date is stale or a command is rejected. - Read `references/quality-gates.md` when defining the acceptance contract for a new task class. - Read `references/benchmark-baseline.json` only as smoke-test evidence. Do not infer comparative superiority from one non-comparable run per model. - Run `python3 scripts/test_router.py` after any policy or code change. - Run `python3 scripts/evaluate_router.py` to check the representative scenario manifest. - Preserve benchmark prompts, expected routes, outputs, latency, tokens, gate results, and review decisions in an isolated evaluation directory. Do not overwrite canonical project artifacts. ## Report the decision Return the chosen model, effort, requested speed, orchestration pattern, quality floor, route confidence, assumptions, and escalation path. Distinguish routing confidence from empirically measured task success.