cortex/CLAUDE.md

# cortex/CLAUDE.md

Cortex = the multi-brain agent. Client-side only. Never imports `server/*`.

## Belongs here

- 3 brains — Epidemiology, Logistics, Governance (`cortex/brains/`).
- Per-brain subagents — Perception, World Modeler, Planner, Critic, Brain Executive (`cortex/subagents/`).
- Council Executive + 4-phase state machine (`cortex/council.py`).
- Routing policy: MLP head over `MetacognitionState` (MVP primary); LoRA stretch (`cortex/routing_policy.py`).
- Metacognition signals (`cortex/metacognition.py`).
- Anti-hivemind protocol + collapse detectors (`cortex/anti_hivemind.py`).
- Brain-specific observation lenses (`cortex/lenses.py`).
- LLM client wrapper (`cortex/llm_client.py`).
- Cortex-internal schemas (`cortex/schemas.py`).

## Does not belong here

SEIR dynamics, telemetry noise, reward math (→ `server/`). GRPO loop, rollout buffer (→ `training/`). Baseline agents (→ `baselines/`).

## Allowed imports

`models` (wire types), `cortex/*`, torch, OpenAI SDK, stdlib.

## Forbidden imports

`server/*` (binding — no reaching into SEIR constants, latent state, or graders; training hits the env over HTTP like production). `training/*`, `baselines/*`, `demo/*`.

---

## Enforcement rules (all binding)

### Role split

- **Perception is pure Python. Do not introduce an LLM call.**
- **Brain Executive is pure Python. Do not introduce an LLM call.**
- **World Modeler, Planner, Critic are LLM calls. Do not rewrite in Python.**
- **Router-callable subagent set is exactly `{WorldModeler, Planner, Critic}`.** The routing policy must not invoke Perception or Brain Executive.

### Per-tick hard caps (enforce in Council Executive)

- **At most 2 deliberation rounds per tick.** Force convergence after round 2.
- **At most 1 cross-brain challenge per tick total** — not per brain, total across brains.
- **At most 1 Critic call per brain per tick.** A brain's Critic must not run twice in one tick.
- **Read hard token budget per tick from the task config at tick start.** When depleted, the router may only emit `emit_outer_action` or `stop_and_no_op`.
- **Worst-case LLM calls per tick = 19** (9 round-1 + 9 round-2 + 1 cross-brain challenge). Any design exceeding 19 is a bug.

### Execution order

- Perception runs once per brain at tick start. Not router-callable.
- Brain Executive runs once per brain at round end. Not router-callable.
- Only World Modeler / Planner / Critic are invoked by the router, via `call_subagent`.

### Anti-hivemind protocol — exactly 5 steps per deliberation round (MVP; no anonymization)

1. **Private first pass.** Each brain produces its `BrainRecommendation` without seeing peers.
2. **Typed evidence disclosure.** Each recommendation must cite `EvidenceCitation` objects and include a `falsifier` field. Uncited claims zero out `r_proto` for that brain.
3. **Targeted challenge.** Metacognition selects ≤ 1 cross-brain challenge per tick. Structured objection, not free chat.
4. **Dissent preservation.** Minority recommendations ride the emitted action as risk flags and are re-checked next tick. Do not discard.
5. **Constitutional decision.** Council Executive selects: act / request more data / another round (within 2-round cap) / escalate / `no_op`.

Step 4′ (anonymized comparison) is `[V2]`. Do not implement in MVP.

### Router action space — exactly these 6 kinds

- `call_subagent(brain, subagent ∈ {WorldModeler, Planner, Critic})`
- `request_challenge(challenger_brain, target_brain)`
- `switch_phase(new_phase)` — Divergence → Challenge → Narrowing → Convergence. Cannot skip forward.
- `preserve_dissent(tag)`
- `emit_outer_action(OuterAction)` — closes the tick.
- `stop_and_no_op` — closes the tick.

`recurse_in(...)` is `[V2]`. Do not add a 7th router action.

### Phase machine invariants

- Phases may not skip forward (Divergence cannot jump to Convergence).
- Phases may re-enter backward on explicit dissent-triggered flag.
- The first `emit_outer_action` or `stop_and_no_op` step closes the tick, even mid-round.

### Logging contract

- **Training-data row = one router step**, not a tick or round: `(episode_id, tick, round, step_idx, RoutingAction, MetacognitionState, tokens_spent, subagent_report?)`.
- Do not log ticks or rounds as training rows.

### Temperature

- Eval: temperature 0 on all LLM subagents for reproducibility.
- Training rollouts: temperature > 0 on LLM subagents so the router sees exploration.

---

## Public APIs (owned here)

- `Council.step(observation: CrisisworldcortexObservation) -> OuterAction`
- `RoutingPolicy.forward(state: MetacognitionState) -> RoutingAction`
- `cortex.schemas` types: `BrainRecommendation`, `BeliefState`, `CandidatePlan`, `MetacognitionState`, `RoutingAction`, `EvidenceCitation`, `RouterStep`, `Trajectory`.
- `cortex.llm_client` (Session 7+): OpenAI / HF-router wrapper with **per-caller token-counting middleware**. Exposes `tokens_used_for(caller_id) -> int` so harnesses (`inference.py`, `baselines/*`, `training/train_router.py`) can compose `r_budget` per the Q1 decision (root `CLAUDE.md`). The env never sees these counts; the wire protocol carries no `tokens_spent_*` fields.

## Testing requirements

- Protocol-invariant test: after any `Council.step`, the 5 protocol steps ran in order or a short-circuit reason is logged.
- Cap tests: synthetic signals inviting > 2 rounds / > 1 cross-brain challenge / > 1 Critic-per-brain must fail closed, not silently exceed.
- No-LLM-call tests: Perception and Brain Executive must not call the LLM client — mock the client, assert zero invocations.
- Import-graph test: grep `cortex/**.py` for `import server` / `from server` — must return empty.
- Determinism (eval-mode): same observation + same policy checkpoint → identical `OuterAction`.

## Common failure modes

- Not clamping rounds at 2 — silently inflates tick cost, breaks matched-compute baseline comparisons.
- Router calling Perception or Brain Executive — violates role split, pollutes training data.
- Discarding minority recommendations — deletes the dissent-preservation signal the pitch depends on.
- Skipping typed evidence disclosure — grader zeros `r_proto`.
- Sharing a single observation lens across brains — collapses evidence-diversity.
- Adding an LLM call inside Perception or Brain Executive — breaks the "3 LLM calls per brain per round" cost guarantee.