😏

docs/OPTIMIZATION.md

@@ -0,0 +1,237 @@
+# Optimization and Performance Policy
+
+Codex MMO optimizes for completed, validated work—not maximum agent count. A model or worker is useful only when it improves at least one of these dimensions without imposing greater integration cost:
+
+- Wall-clock latency through genuine parallelism.
+- Capability through specialization or stronger reasoning.
+- Context isolation for noisy or independent branches.
+- Confidence through independent verification.
+- Access-route cost or local-resource efficiency.
+- Operational control through durable, cancellable jobs.
+
+## The delegation decision
+
+The root should evaluate five variables together:
+
+1. **Difficulty** — how much reasoning or implementation capability is required?
+2. **Independence** — can the branch proceed without blocking or duplicating root work?
+3. **Criticality** — is it on the immediate critical path?
+4. **Verifiability** — how cheaply can the result be checked from primary evidence?
+5. **Execution economics** — launch overhead, provider cost, latency, resource pressure, and integration burden.
+
+A strong default decision tree is:
+
+```text
+Is the task an immediate critical-path blocker?
+├── yes: root usually handles it directly
+└── no
+    ├── difficult/high-consequence and independent: flagship peer
+    ├── substantive bounded engineering: implementation specialist
+    ├── cheap, literal, easily verified evidence: low-cost scout
+    └── no meaningful benefit from delegation: root handles it
+```
+
+Difficulty alone does not determine delegation. A hard independent review is an excellent flagship-worker task; a hard architectural decision that blocks all progress normally belongs in the root thread.
+
+## Root productivity
+
+The root is an active engineer and integrator. Its generated policy requires:
+
+1. Identify the immediate critical path.
+2. Identify independent side work.
+3. Spawn only useful branches.
+4. Continue non-overlapping root work immediately.
+5. Consume results as they become relevant.
+6. Wait only at a real dependency barrier.
+7. Reconcile contradictions from primary evidence.
+8. Review material changes and run integrated validation.
+
+The runtime records explicit Agent MCP wait events and root events emitted during worker intervals. Evaluation reports wait seconds/ratio, event coverage, worker overlap, and time to first useful result; event coverage is not proof of continuous cognition. A profile that causes the root to spawn and immediately idle is still misconfigured even if worker utilization looks high.
+
+## Native versus MCP execution
+
+Native Codex agents and Agent MCP solve different performance problems.
+
+Use native agents when:
+
+- Launch latency matters.
+- The task is small or read-heavy.
+- Tight `/agent` interaction is useful.
+- Built-in Codex authentication and native behavior should remain direct.
+- External scope/contract enforcement is not essential.
+
+Use MCP when:
+
+- Exact model/route pinning must be auditable.
+- The worker is low-trust or inconsistent.
+- The task is long-running or asynchronous.
+- Cancellation, durable results, or operator inspection matter.
+- Nested delegation needs enforceable lineage and budgets.
+- Workspace writes need isolated worktrees, explicit scopes, and audited patch integration.
+- Structured output must be validated.
+
+Hybrid profiles use native first-level branches for lower latency and MCP for strict or nested work. This avoids paying process-launch overhead universally without giving up enforcement where it has value.
+
+## Weak-model economics
+
+A cheap model is not automatically efficient. Its net value is:
+
+```text
+saved strong-model work
+- launch and prompt cost
+- verification cost
+- contradiction-resolution cost
+- rework caused by incorrect output
+```
+
+A weak or conflict-prone model should therefore receive only tasks that are:
+
+- Narrow.
+- Low ambiguity.
+- Read-only.
+- Mechanically checkable.
+- Cheap to repeat or discard.
+- Unlikely to contaminate architecture or final decisions.
+
+The bundled Qwen role is restricted to evidence gathering for precisely this reason. The same trust policy can be applied to any model. Low-trust output is evidence to verify, never authority.
+
+Do not delegate a command the root can execute directly in less time than starting and checking a worker.
+
+## Parallelism policy
+
+Concurrency ceilings are limits, not targets.
+
+Read-heavy work can be parallelized aggressively when branches are independent:
+
+- Repository mapping.
+- Independent diagnosis.
+- Specification extraction.
+- Review from different perspectives.
+- Test and log analysis.
+
+Write-heavy work requires stronger partitioning:
+
+- Assign disjoint files or components.
+- Require MCP write scopes and isolated Git worktrees where enforceability matters.
+- Avoid logically coupled edits even when paths differ.
+- Keep one root responsible for reading, accepting/rejecting, explicitly integrating, inspecting, and testing patches.
+- Cancel duplicate branches once one result makes the other unnecessary.
+
+Too many agents increase context duplication, provider queuing, file conflicts, and synthesis time. Start with two or three useful branches; increase only when evaluation shows a wall-clock or quality benefit.
+
+## Resource groups
+
+Resource groups model shared capacity rather than model names. Examples include:
+
+- A ChatGPT subscription.
+- An OpenCode Go account.
+- A Z.AI plan.
+- A direct API rate pool.
+- One local GPU.
+
+Each active MCP role consumes `resource_units`. Admission is atomic across sessions. This prevents a six-agent profile from launching six copies against a one-slot local model server or exhausting one provider while other capacity sits idle.
+
+Tune group capacity in a user catalog fragment based on measured provider and hardware behavior. Do not encode a physical capacity assumption in profile instructions.
+
+## Context isolation
+
+Worker prompts include the delegated objective, role instructions, output contract, workspace context, and parent lineage—not the entire root transcript by default. This reduces token duplication and keeps independent branches independent.
+
+Good briefs state:
+
+- Exact scope.
+- Expected artifact or decision.
+- Relevant constraints.
+- Required evidence and validation.
+- What the worker must not decide.
+
+Bad briefs paste the complete conversation, ask an agent to “solve everything,” or omit success criteria.
+
+## Structured results
+
+Strict contracts reduce synthesis cost by making important outputs predictable. They are particularly valuable for:
+
+- Low-trust evidence collectors.
+- Review findings.
+- Implementation summaries.
+- Proposal comparisons.
+- Test reports.
+
+Keep contracts small. Requiring a large nested schema can consume more model effort than it saves. Full logs and diffs remain as artifacts; the structured result should contain the decision-relevant subset.
+
+## Contradiction handling
+
+Never use model voting as a substitute for verification. When agents disagree:
+
+1. Identify the exact conflicting propositions.
+2. Locate source code, specifications, tests, logs, or reproducible commands that discriminate between them.
+3. Run or inspect that evidence.
+4. Ask a specialist only when the evidence itself requires expert interpretation.
+5. Record residual uncertainty.
+
+A stronger model is not automatically correct; a majority is not automatically correct; an independent result is valuable only when its assumptions and evidence are visible.
+
+## Gateway reuse
+
+Switchyard runs per resolved transport/model route set. Sessions with equivalent gateway identity can reuse one gateway; different route semantics remain isolated. This gives:
+
+- Stable model IDs.
+- No route collisions during profile switching.
+- Credential minimization.
+- Reuse without globally exposing unused routes.
+- Independent shutdown of idle gateways.
+
+Profiles using only direct Codex routes avoid gateway startup entirely.
+
+## Reasoning levels
+
+Use the highest reasoning setting only where its marginal value exceeds latency and token cost.
+
+Recommended defaults:
+
+- Root or flagship architect: high to maximum supported level.
+- Substantive implementation: high.
+- Mechanical evidence collector: reasoning disabled or lowest reliable mode.
+- Reviewer: high when subtle correctness is material.
+- Plan mode: explicitly configured so the client does not silently fall back to a lower preset.
+
+A profile binding is validated against declared model and route reasoning metadata. Labels are not assumed to be semantically identical across access products; catalog entries record the selector accepted by that exact path.
+
+## Evaluation-driven tuning
+
+Use matched variants within the workload-specific suite:
+
+```bash
+codex-mmo eval run --profile adaptive-engineering --suite adaptive-change
+codex-mmo eval run --profile adaptive-engineering --suite adaptive-change --trial-mode release
+codex-mmo eval compare RUN_ID_A RUN_ID_B
+```
+
+Compare:
+
+- Success rate, workload metrics, and objective validation.
+- Wall-clock time.
+- Observed root MCP wait ratio, peak workers, worker overlap, and time to first result.
+- Actual worker-role/model/route/serving routing and result-acceptance rate.
+- Worker completion/failure rate.
+- Result acceptance and contract failures.
+- Retry and cancellation counts.
+- Conflicts and out-of-scope warnings.
+- Token usage plus separate actual-API, API-equivalent, subscription, and local-resource ledgers.
+- Integration corrections.
+
+Optimization changes should be justified by these results, not by intuition about model rank.
+
+## Common anti-patterns
+
+- Spawning every available model on every task.
+- Delegating the critical path and immediately waiting.
+- Giving weak models ambiguous or high-consequence work.
+- Letting multiple writers edit overlapping logic.
+- Using the same prompt for every role.
+- Allowing unbounded nested delegation.
+- Retrying a failed branch repeatedly without changing context or approach.
+- Treating structured output as proof of correctness.
+- Running both Codex Ultra’s autonomous orchestration and an external mesh without explicit accounting.
+- Routing built-in Codex models through an unnecessary translation layer.
+- Measuring utilization instead of completed validated work.