docs/CORTEX_ARCHITECTURE.md

# Cortex Architecture (Phase A — locked contract for Sessions 9–13)

**Status:** locked. Sessions 9–13 implement against this document. Per-session
proposals reference sections by number ("per Phase A §3.2…"); decisions
recorded here are not re-litigated in implementation sessions.

**Source-of-truth dependencies (binding):**
- `CRISISWORLD_CORTEX_SYSTEM_DESIGN.md` v2.1 — the project design intent,
  particularly §7 (Cortex), §8 (anti-hivemind), §9 (phase state machine),
  §10 (worked example), §11.2 (Cortex schemas), §13 (file structure),
  §14–§19 (rewards), §22 (policy parameterization).
- `cortex/CLAUDE.md` — binding role split, hard caps, anti-hivemind 5-step
  protocol, 6-kind router action space, phase-machine invariants, logging
  contract, temperature rules.
- `cortex/schemas.py` — already-implemented Pydantic types; this doc reuses
  them verbatim and notes the small set of additions Sessions 9–13 must
  introduce.
- `baselines/CLAUDE.md` — for B3 (cortex_fixed_router) integration in
  Session 13.

When this doc and a `CLAUDE.md` disagree, the `CLAUDE.md` wins (it's the
binding contract); flag the divergence to the human reviewer before
implementing.

---

## §1 — Complete data flow

A single CrisisWorld tick triggers exactly one full Cortex pass that
produces exactly one `OuterAction`. The pass walks five layers, with
state propagating in a strict order:

```
                          ┌────────────────────────────────────────┐
  CrisisworldcortexEnv ──►│ 0. Observation arrives                 │
  (HTTP / SyncEnvClient)  │    CrisisworldcortexObservation v[…]   │
                          └────────────────┬───────────────────────┘
                                           ▼
                          ┌────────────────────────────────────────┐
                          │ 1. Lenses (per-brain, deterministic)   │
                          │    cortex.lenses.lens_for(brain, obs)  │
                          │    → BrainLensedObservation × 3        │
                          └────────────────┬───────────────────────┘
                                           ▼
                          ┌────────────────────────────────────────┐
                          │ 2. Perception (per-brain, deterministic│
                          │    Python — NOT router-callable)       │
                          │    → PerceptionReport × 3              │
                          └────────────────┬───────────────────────┘
                                           ▼
   ┌── routing‐policy step ─►┌────────────────────────────────────┐
   │                         │ 3. LLM Subagents (router-callable):│
   │                         │      WorldModeler / Planner / Critic│
   │                         │    Each call returns a typed        │
   │                         │    SubagentReport (BeliefState |   │
   │                         │    CandidatePlan | CriticReport).   │
   │                         └────────────────┬───────────────────┘
   │                                          ▼
   │                         ┌────────────────────────────────────┐
   │                         │ 4. Brain Executive (per-brain,     │
   │                         │    deterministic Python — NOT      │
   │                         │    router-callable)                │
   │                         │    → BrainRecommendation × 3       │
   │                         └────────────────┬───────────────────┘
   │                                          ▼
   │                         ┌────────────────────────────────────┐
   │                         │ 5. Metacognition signals           │
   │                         │    → MetacognitionState            │
   │                         └────────────────┬───────────────────┘
   │                                          ▼
   │                         ┌────────────────────────────────────┐
   │     RoutingPolicy ◄─────│ 6. Council Phase Machine           │
   │     (deterministic for  │    Divergence → Challenge →        │
   │      Session 13;        │    Narrowing → Convergence         │
   │      trainable from     │    enforces hard caps and emits    │
   │      Session 15)        │    one RoutingAction per step      │
   └─────────────────────────└────────────────┬───────────────────┘
                                              ▼
                          ┌────────────────────────────────────────┐
                          │ 7. CouncilDecision → OuterAction       │
                          │    submitted to env via .step(action)  │
                          └────────────────────────────────────────┘
```

**Data flow contract:**

- The env-side observation flows through `CrisisworldcortexEnv.step()` →
  `Council.step(observation)`. The Council never imports `server/*` —
  baselines/CLAUDE.md and cortex/CLAUDE.md both forbid this.
- Per design §7.2, **Perception** is *deterministic Python* and runs
  once per brain at tick start. **Brain Executive** is *deterministic
  Python* and runs once per brain at round end. Only **WorldModeler /
  Planner / Critic** are router-callable LLM subagents.
- The router (`RoutingPolicy.forward`) is the only place an LLM is
  invoked. Each `RoutingAction` of kind `call_subagent` triggers exactly
  one LLM call and produces one `SubagentReport`.
- **Tokens flow through `cortex.llm_client.LLMClient`**. Caller-IDs follow
  the `cortex:<brain>:<subagent>:t<tick>:r<round>:s<step>` format so per-tick
  budget tracking matches the harness pattern from Session 7a.
- **State that persists across rounds within a tick**: the latest
  `BrainRecommendation` per brain, the latest `BeliefState` per brain
  (so round 2 can read round 1's beliefs), the `MetacognitionState`
  signals updated each round, the deliberation-rounds-used counter,
  the cross-brain-challenges-used counter (capped at 1), the per-brain
  Critic-calls-used counter (capped at 1).
- **State that persists across ticks**: the env-side `recent_action_log`
  (already on the wire); Cortex itself is **stateless across ticks** in
  the MVP — design §7.2 V2 note flags long-term memory as `[V2]` only.

---

## §2 — Pydantic schemas at every boundary

Most schema work is already done in `cortex/schemas.py` (Session 4); this
section locks the small set of additions Sessions 9–13 need and pins the
already-existing shapes against any drift.

### Already locked in `cortex/schemas.py` (do not change)

- `EvidenceCitation` — `source ∈ {telemetry, resource, policy, action_log,
  belief, memory}`, `ref: str`, `excerpt: str`.
- `PerceptionReport` — `brain, salient_signals, anomalies, confidence,
  evidence`. Output of the deterministic Python Perception subagent.
- `BeliefState` — `brain, latent_estimates, hypotheses, uncertainty,
  reducible_by_more_thought, evidence`. WorldModeler output.
- `CandidatePlan` — `action_sketch, expected_outer_action, expected_value,
  cost, assumptions, falsifiers, confidence`. Planner output.
- `CriticReport` — `brain, target_plan_id, attacks, missing_considerations,
  would_change_mind_if, severity`. Critic output.
- `BrainRecommendation` — `brain, top_action, top_confidence,
  minority_actions, reasoning_summary, evidence, falsifier, uncertainty,
  tokens_used, anonymous_id (V2 slot)`. Brain Executive output.
- `CouncilDecision` — `action, rationale, preserved_dissent, phase_trace,
  rounds_used, tokens_used`. Council Executive output.
- `MetacognitionState` — `tick, round, phase, inter_brain_agreement,
  average_confidence, average_evidence_support, novelty_yield_last_round,
  collapse_suspicion, budget_remaining_frac, urgency,
  preserved_dissent_count, challenge_used_this_tick`.
- `RoutingAction` — `kind ∈ {call_subagent, request_challenge, switch_phase,
  preserve_dissent, emit_outer_action, stop_and_no_op}` plus per-kind
  optional fields.

### Additions Sessions 9–13 must introduce (locked here)

#### A1. `BrainLensedObservation` (Session 10)

```
class BrainLensedObservation(BaseModel):
    brain: Literal["epidemiology", "logistics", "governance"]
    raw_obs: CrisisworldcortexObservation       # full obs reference (not copy)
    salient_field_ids: List[str]                # e.g. ["regions[*].hospital_load"]
    derived_features: Dict[str, float]          # brain-specific scalar features
    last_reward: float                          # plumbed from B1's pattern
```

**Rationale:** Lenses don't strip fields from the observation (the agent
might need them later) — they project a *salience map* alongside it.
`derived_features` lets each brain pre-compute domain-specific scalars
once and pass them to all three of its LLM subagents without re-reading
the raw obs.

#### A2. `SubagentInput` (Session 9)

```
class SubagentInput(BaseModel):
    brain: Literal["epidemiology", "logistics", "governance"]
    role: Literal["world_modeler", "planner", "critic"]
    tick: int
    round: int
    perception: PerceptionReport
    prior_belief: Optional[BeliefState] = None       # round 2+ only
    prior_plans: List[CandidatePlan] = []            # passed to Critic; empty for WM/Planner
    target_plan_id: Optional[str] = None             # required for Critic
    last_reward: float
    recent_action_log_excerpt: List[ExecutedAction]
```

**Rationale:** Typed inputs make subagent prompts deterministic and
testable. `prior_belief` is `None` on round 1 (nothing to revise yet).
`prior_plans` is empty for WorldModeler and Planner; populated for
Critic so it can attack a specific plan.

#### A3. `RouterStep` (Session 13 — already named in cortex/CLAUDE.md exports)

```
class RouterStep(BaseModel):
    episode_id: str
    tick: int
    round: int
    step_idx: int
    routing_action: RoutingAction
    metacognition_state: MetacognitionState
    tokens_spent: int
    subagent_report: Optional[SubagentReport] = None  # populated when routing_action.kind == "call_subagent"
    policy_kind: Literal["trainable", "deterministic_fallback"] = "trainable"  # which policy emitted this step
```

**Rationale:** Per cortex/CLAUDE.md "Logging contract", the training-data
row IS one router step. This schema makes it easy to dump a full
trajectory as `List[RouterStep]` without bespoke serialisation. The
`policy_kind` field (OQ-3 resolution) tags which policy emitted the
step: `"trainable"` for the Session-15 learned router, `"deterministic_fallback"`
for the Session-13 router used both as B3 baseline AND as the crash
fallback when the trainable router raises mid-tick (see §7 metacognition
layer). GRPO advantage computation filters to `policy_kind == "trainable"`
only — fallback steps are off-policy and excluded from the gradient.
Default is `"trainable"` so B3 round-tripping does not need to set the
field; B3 is a baseline, not training data, so the default value is
inert for B3 trajectories.

#### A4. `Trajectory` (Session 13 — referenced by training/* and inference.py)

```
class Trajectory(BaseModel):
    episode_id: str
    task: Literal["outbreak_easy", "outbreak_medium", "outbreak_hard"]
    seed: int
    router_steps: List[RouterStep]              # flat list, one per router step
    council_decisions_per_tick: List[CouncilDecision]
    rewards_per_tick: List[float]               # obs.reward each tick
    terminal_kind: Literal["none", "success", "failure", "timeout"]
```

These four additions are the **only** new schema types Sessions 9–13 need.
Everything else is already typed in `cortex/schemas.py`.

---

## §3 — Council phase machine

The Council Executive owns four phases (§9 of the design doc) and
exactly one transition arrow from each (with a bidirectional arrow for
dissent-triggered backtrack). Sessions 12 implements the machine;
Sessions 9–11 implement the phase-internal work that the machine drives.

### Phase definitions

| Phase | Purpose | Phase-end criterion |
|---|---|---|
| **Divergence** | Each brain produces an independent `BrainRecommendation` (anti-hivemind step 1). Subagent calls fire here. | Inter-brain diversity sufficient OR ≥ ⅓ of per-tick budget spent OR all 3 brains have produced a recommendation |
| **Challenge** | At most one cross-brain Critic call (the single allowed challenge per tick — cortex/CLAUDE.md cap). | Challenge resolved (challenger received a counter-recommendation or accepted the original) OR challenge cap exceeded OR diminishing novelty |
| **Narrowing** | Council ranks `top_action` candidates from each brain; minority recommendations get tagged for `preserved_dissent`. | Top candidate stable across last router step OR ⅔ of budget spent OR `urgency` flag set |
| **Convergence** | Emit the chosen `OuterAction` and finalise `CouncilDecision`. | First `emit_outer_action` or `stop_and_no_op` step closes the tick — even mid-round. |

### State machine (start → end)

`Council.step(observation)` initialises:

1. `phase = Divergence`
2. `round = 1`
3. `deliberation_rounds_used = 0`
4. `cross_brain_challenges_used = 0`
5. `critic_calls_per_brain = {epi: 0, logistics: 0, governance: 0}`
6. `tick_tokens_used = 0`
7. `lenses = {brain: lens_for(brain, observation) for brain in BRAINS}`
8. `perceptions = {brain: run_perception(brain, lenses[brain]) for brain in BRAINS}` (Python, 0 tokens)

Then the deliberation loop:

```
while True:
    metacog_state = compute_metacognition_signals(...)
    routing_action = routing_policy.forward(metacog_state)
    apply(routing_action)            # may invoke subagent, change phase, etc.
    log_router_step(routing_action, metacog_state, ...)
    if routing_action.kind in {"emit_outer_action", "stop_and_no_op"}:
        break
    if deliberation_rounds_used == 2 and phase == Convergence:
        force_emit()
        break
    if budget_exhausted():
        force_emit_or_no_op()
        break
```

### Transition rules (binding)

- **Forward only**: Divergence → Challenge → Narrowing → Convergence. No
  forward-skipping (cortex/CLAUDE.md "Phase machine invariants").
- **Backward re-entry on dissent**: if `preserve_dissent` was emitted *and*
  `metacog_state.preserved_dissent_count >= 2`, the router may emit
  `switch_phase(Challenge)` to re-open challenge. This is the only
  allowed backward transition. The `>= 2` threshold (Item A resolution)
  reflects "two preserved dissents = real minority views surfaced; a
  single one is noise" — re-opening challenge on a single preserved
  dissent would burn the cross-brain-challenge cap on what may be a
  one-off objection.
- **Round-2 entry trigger** (Item C resolution): the router enters
  round 2 ONLY by emitting an explicit `switch_phase(Divergence)`
  routing action. Council Executive forbids implicit round increment
  (e.g. silently bumping `round = 2` after Convergence-without-emit).
  Rationale: every round boundary is an explicit policy decision,
  which keeps the Session-15 router's training signal clean — the
  trainable router learns "when to spend a second round" as a
  first-class action choice rather than as an emergent side-effect.
- **Round increment**: every time `phase` returns to Divergence (or
  re-enters Challenge from Convergence/Narrowing via a backtrack), the
  Council Executive checks `deliberation_rounds_used`. If it's already 2,
  it overrides the router's `switch_phase(...)` and forces a
  `switch_phase(Convergence)`. Never silently skip — log the override as
  a `RouterStep` with kind `switch_phase` and a `phase_trace` entry
  noting "forced by 2-round cap".

### Termination conditions (any one terminates the tick)

1. Router emits `emit_outer_action` — submit and advance.
2. Router emits `stop_and_no_op` — submit a `NoOp()` and advance.
3. Round 2 + Convergence reached → force `emit_outer_action` with the
   current top-ranked candidate.
4. Per-tick budget depleted (`tick_tokens_used ≥ TICK_BUDGET`) → router
   may only emit `emit_outer_action` or `stop_and_no_op`. If it emits
   anything else, the Council Executive **overrides** to
   `emit_outer_action` (with the current best candidate or NoOp marker
   if no candidate exists yet).
5. Brain failure (`SubagentReport` not received within timeout, see §7) →
   the failing brain's recommendation is treated as `top_action = NoOp()`
   with `top_confidence = 0.0`; the round continues with the other two.

### Phase-to-protocol mapping (Item F resolution)

The 5-step anti-hivemind protocol (cortex/CLAUDE.md, §8.1 of design doc)
maps onto the 4-phase machine as follows. This pin lets
`tests/test_cortex_protocol_invariants.py` assert the exact protocol
step exercised in each phase.

| Anti-hivemind step | Phase |
|---|---|
| 1. Independent reasoning (private first pass) | Divergence |
| 2. Cross-brain critique (typed evidence disclosure + targeted challenge entry) | Challenge phase entry |
| 3. Counter-recommendation (challenge resolved or accepted) | Challenge phase end |
| 4. Anonymized comparison | **Deferred V2 per Decision 56** — not implemented in MVP |
| 5. Final aggregation with preserved dissent | Narrowing + Convergence |

The Session-12 protocol-invariant test asserts that for any `Council.step`
trace, every phase-entry `RouterStep` is paired with exactly the protocol
step listed above (or a logged short-circuit reason — e.g. budget
exhausted, brain failure, override). Step 4 is asserted as
**not-fired** in MVP; if it ever fires, the test treats that as a
forward-leak from a V2 branch into MVP and fails closed.

---

## §4 — Hard cap accounting and preserved-dissent tracking

### Counters (held in Council Executive instance)

| Counter | Cap | Where decremented / incremented |
|---|---|---|
| `deliberation_rounds_used` | ≤ 2 | Incremented each time `phase` returns to Divergence (i.e. round boundary); checked before the router's next `switch_phase`. |
| `cross_brain_challenges_used` | ≤ 1 | Incremented when `RoutingAction.kind == "request_challenge"` is applied; future `request_challenge` actions are blocked by the Council Executive (override → `switch_phase(Narrowing)`). |
| `critic_calls_per_brain[brain]` | ≤ 1 each | Incremented when `call_subagent(brain, "critic")` fires; subsequent Critic calls on the same brain are blocked. |
| `tick_tokens_used` | < `TICK_BUDGET` (default 6000) | See §5. |

### Invariants (asserted at end of `Council.step`)

- `deliberation_rounds_used ≤ 2` — ALWAYS. If violated, raise
  `AssertionError` (NOT a logged warning — this is an integrity break).
- `cross_brain_challenges_used ≤ 1` — ALWAYS.
- `for brain in BRAINS: critic_calls_per_brain[brain] ≤ 1` — ALWAYS.
- `total LLM calls in a tick ≤ 19` — checked end-of-tick. Calls are
  3 brains × 3 LLM subagents × 2 rounds = 18 + 1 cross-brain challenge.

### Preserved-dissent contract

- **What gets recorded:** when `RoutingAction.kind == "preserve_dissent"`
  fires, the Council appends a string tag to a tick-local
  `preserved_dissent: List[str]`. The tag format is
  `"<brain>.<minority_action_kind>:<short_rationale>"`, e.g.
  `"governance.escalate:precautionary_until_R3_confirms"`. Max 80 chars
  per tag (truncate longer rationales — keep the prefix readable).
- **When recorded:** *during* deliberation, by the router. Multiple tags
  can accumulate within one tick.
- **Who reads it:**
  - The Council Executive embeds the list verbatim in
    `CouncilDecision.preserved_dissent`.
  - The training reward composer reads `len(preserved_dissent)` to
    feed the `r_div_health` term (per design §18). This is **eval signal
    that IS in the training reward** — preserved dissent rewards
    diversity behaviorally.
  - The eval-only `dissent_value` metric (design §20.1, score not
    optimized but logged) reads the contents — it scores whether a
    minority warning that was preserved later proved correct (next-tick
    re-check).

### Cap-violation behavior

If the router somehow asks for an action that would violate a cap, the
Council Executive **silently overrides** the action AND logs an
`OverrideEvent` to the trajectory. Specifically:

- `request_challenge` after the challenge cap → drop to
  `switch_phase(Narrowing)` with override note.
- `call_subagent(brain, "critic")` after the Critic cap → drop to
  `call_subagent(brain, "world_modeler")` with override note (give the
  brain another belief-revision pass instead).
- `switch_phase(Convergence)` skipping over Challenge in round 1 → drop
  to `switch_phase(Challenge)` first, with override note.

The override path exists to keep training stable: a learned router that
emits a forbidden action gets the closest-legal action it would have
gotten anyway, so the policy gradient is not corrupted by raw failures.

---

## §5 — Token budget propagation

### Initial state per tick

- `TICK_BUDGET` is read **once at tick start** from
  `state.task_config.cognition_budget_per_tick`. Default = 6000 (locked
  at every TaskConfig per `server/simulator/tasks.py`).
- `Council` exposes `TICK_BUDGET` as a class attribute that can be
  overridden via a constructor kwarg — same shape as B2's
  `tick_budget` parameter (Session 8). Session 16 (training-eval
  re-calibration) will use the override.

### Propagation pattern

- Tokens flow **bottom-up** through `cortex.llm_client.LLMClient`. Each
  subagent call uses a unique caller-id following:
  `cortex:<brain>:<role>:t<tick>:r<round>:s<step_idx>`. The LLMClient
  middleware accumulates per-caller tokens.
- Per-call cost is read from `ChatResponse.prompt_tokens +
  completion_tokens` and accumulated into the Council's
  `tick_tokens_used: int`. This mirrors B2's pattern (Session 8 §4).
- **No reclaim**: each brain implicitly gets ⅓ of the per-tick budget,
  but there's no enforcement at the brain level. The router decides
  call ordering; if Epidemiology consumes more than ⅓, Logistics simply
  has fewer rounds available. This is the matched-compute story —
  Cortex's flexibility comes from the router, not from per-brain quotas.

### Behavior at cap

The router's space contracts at the cap:

- `tick_tokens_used + estimated_next_call_cost ≥ TICK_BUDGET`: the
  Council Executive **rewrites** any `call_subagent` or
  `request_challenge` to `emit_outer_action` (with the current best
  candidate) or `stop_and_no_op` (if no candidate yet).
- `estimated_next_call_cost` uses the same simple-moving-average pattern
  as B2 (window=3, reset at tick start to `_INITIAL_CALL_COST_ESTIMATE = 600`).

### Matched-compute defense

Cortex's per-tick LLM-token consumption is what B2's `tick_budget`
matches against (per design §20.1.1 line 1201:
*"Token budget per tick: identical to Cortex's per-tick token budget in
that task config. Measured by actual tokens consumed, not theoretical
caps."*). Session 16 (eval calibration) will:

1. Run Cortex on each task with the trained router.
2. Measure the median per-tick `tick_tokens_used` across episodes.
3. Update B2's `tick_budget` to match.
4. Re-run B2 baselines for the ablation chart.

---

## §6 — Routing policy interface

### Locked signature

```
class RoutingPolicy(Protocol):
    def forward(self, state: MetacognitionState) -> RoutingAction: ...
```

Sessions 13 (deterministic) and 15 (trainable) ship two implementations
with this exact signature.

### `MetacognitionState` carries (already locked in `cortex/schemas.py`)

- **Tick context**: `tick`, `round` (1 or 2), `phase`.
- **Per-tick deliberation history (aggregate signals only)**:
  `inter_brain_agreement`, `average_confidence`,
  `average_evidence_support`, `novelty_yield_last_round`,
  `collapse_suspicion`.
- **Resource state**: `budget_remaining_frac`, `urgency`.
- **Hard-cap state**: `preserved_dissent_count`,
  `challenge_used_this_tick`.

What it deliberately does **not** carry:
- The full observation (the lensed observation never reaches the router).
- The brain recommendations themselves (those go into
  `inter_brain_agreement` aggregation).
- Raw subagent reports (collapsed into `average_evidence_support`).

This collapse is intentional — design §22 line 1257 says *"Featurize
MetacognitionState into a fixed-length vector (~20–40 dims)"*. A router
trained on this vector with Option B (small MLP head) is the MVP target;
Option A (LoRA on a small instruct model) is the stretch.

### `RoutingAction` (locked in `cortex/schemas.py`)

```
RoutingAction.kind ∈ {
    "call_subagent",         # → brain + subagent ∈ {WM, Planner, Critic}
    "request_challenge",     # → target_brain + challenger_brain (the brain whose Critic will run)
    "switch_phase",          # → new_phase (cannot skip forward)
    "preserve_dissent",      # → tag (string)
    "emit_outer_action",     # → outer_action: OuterActionPayload
    "stop_and_no_op",        # → emit NoOp, terminate tick
}
```

Sessions 13's deterministic router uses a fixed decision table over
`(phase, round, agreement, budget)`. Sessions 15's trainable router is
GRPO over the same input/output shape — identical interface, swappable
implementation.

### Determinism contract (eval-mode)

Per cortex/CLAUDE.md: *"Determinism (eval-mode): same observation +
same policy checkpoint → identical OuterAction."* This requires:

- LLM temperature = 0 in eval (already locked in cortex/CLAUDE.md).
- All RNG seeds threaded explicitly (not pulled from `random.random()`).
- Sessions 13's deterministic router has no internal randomness —
  ties broken by deterministic ordering of brains.
- Sessions 15's trainable router uses argmax in eval mode (sampling is
  for training rollouts only).

---

## §7 — Failure modes per layer and fallback behavior

### Subagent (LLM) layer

| Failure | Detect | Fallback | Logged | Reward signal sees |
|---|---|---|---|---|
| LLM call raises (auth, network, rate limit) | `try/except` in `LLMClient.chat`-equivalent wrapper | Empty `SubagentReport` with `confidence=0.0`, `evidence=[]`. Brain Executive treats this as "no useful input from this subagent". | `[WARN] cortex: <caller_id> llm.chat failed: <exc>` to stderr. Trajectory `RouterStep.subagent_report` set to `None` and `tokens_spent=0`. | `r_proto` zero for that brain (no evidence cited) — already aligned with the protocol-integrity reward. |
| LLM output fails to parse (typed JSON malformed) | Pydantic `ValidationError` on `BeliefState.model_validate(json)` etc. | One retry with a "your previous response failed to parse" prefix; if that also fails, return empty `SubagentReport` as above. | `[WARN] cortex: <caller_id> parse_failure raw=<snippet>`. Counter `parse_failure_count` increments in trajectory. | Same as above — empty report → no evidence → `r_proto = 0` for the brain. |
| Subagent output references nonexistent region or invalid action variant | `OuterActionPayload` discriminated-union validation | Treat as parse failure (above). | Same as above. | Same as above. |

### Brain layer (Brain Executive)

| Failure | Detect | Fallback | Logged | Reward signal sees |
|---|---|---|---|---|
| All 3 subagents returned empty reports | `aggregate_brain_outputs(...)` sees no plans | `BrainRecommendation(top_action=NoOp(), top_confidence=0.0, ..., uncertainty=1.0)` | `[WARN] cortex: brain=<X> all-subagent-empty fallback to NoOp` | The brain's `top_action` is NoOp; if that wins the council vote, env runs a NoOp tick. |
| Pydantic constructor of `BrainRecommendation` raises | (defensive — should not happen if subagent fallbacks are correct) | Same as above. | `[ERROR] cortex: brain=<X> recommendation construction failed: <exc>` | Same as above. |

### Council layer

| Failure | Detect | Fallback | Logged | Reward signal sees |
|---|---|---|---|---|
| Router emits a cap-violating action | Council's cap counters + override logic (§4) | Closest-legal action, recorded as override. | `[INFO] cortex: router action overridden: <kind> -> <kind>` | Training-data row records the OVERRIDDEN action so the policy learns the legal substitute. |
| Per-tick budget exhausted before any candidate exists | `tick_tokens_used ≥ TICK_BUDGET` and `current_top_candidate is None` | Submit synthetic V2-rejected `parse_failure_marker()` (reuse the shared B1/B2 helper). | `[ERROR] cortex: budget exhausted with no candidate; submitting parse_failure_marker` | r_policy = 0 lands on this tick (matches B1/B2 contract). |
| Wire-level `env.step()` raises | `try/except` in `Council.step` outer loop | Emit a `CouncilDecision` with `action=NoOp()`, `phase_trace=["env_step_failed"]`. Episode continues with the env in an unknown state. | `[ERROR] cortex: env.step failed at tick=<N>: <exc>` | obs.reward = 0 for this tick (per inference.py's session 7d handling). |

### Metacognition layer

| Failure | Detect | Fallback | Logged | Reward signal sees |
|---|---|---|---|---|
| `MetacognitionState` field outside [0, 1] (e.g. `inter_brain_agreement = 1.2`) | Pydantic validation in the constructor | Clamp to [0, 1] silently; this is a metric-computation bug worth fixing but should not crash the tick. | `[WARN] cortex: metacog state field <name>=<value> out of range; clamped` | Router sees the clamped value; training learns from clamped state. |
| Routing policy raises (Sessions 15 trainable router crashes mid-tick) | `try/except` in `Council.deliberate()` | Fall back to Sessions 13's deterministic router for the rest of the tick. | `[ERROR] cortex: trainable router crashed: <exc>; using deterministic fallback for tick <N>` | The deterministic router emits a sane action. |

---

## §8 — Test strategy across sessions 9–13

Each session ships its own RED tests; integration smoke gates fire after
Sessions 11, 12, 13.

### Session 9 — Subagents

- **Per-role tests** (`tests/test_cortex_subagents.py`):
  - `test_world_modeler_emits_belief_state` — stub LLMClient returns
    valid `BeliefState` JSON; subagent returns parsed `BeliefState`.
  - `test_planner_emits_candidate_plan` — likewise for `CandidatePlan`.
  - `test_critic_emits_critic_report` — likewise for `CriticReport`.
  - `test_subagent_parse_failure_returns_empty_report` — stub returns
    garbage; subagent returns empty `BeliefState/CandidatePlan/
    CriticReport` with confidence 0.
  - `test_perception_runs_without_llm_call` — stub LLMClient with
    `chat` raising; Perception completes (Python only).
- **Schema tests** (`tests/test_cortex_schemas.py` already exists for
  the existing types; extend for `SubagentInput`).

### Session 10 — Lenses

- **Lens transformation tests** (`tests/test_cortex_lenses.py`):
  - `test_epi_lens_emphasizes_telemetry` — derived features include
    `r_effective_estimate`, `worst_region_infection`.
  - `test_logistics_lens_emphasizes_resources` — derived features
    include `total_inventory`, `hospital_load_max`.
  - `test_governance_lens_emphasizes_legal` — derived features include
    `escalation_unlocked_strict`, `legal_constraints_count`.
  - `test_lens_does_not_strip_raw_obs` — `BrainLensedObservation.raw_obs`
    is the same observation object (or model-equal); not a stripped
    subset.

### Session 11 — Brains (single-brain end-to-end)

- **Brain coordination tests** (`tests/test_cortex_brains.py`):
  - `test_brain_executive_packages_subagent_outputs` — given fixture
    `(perception, belief, plan, critic)`, Brain Executive emits a
    correctly-shaped `BrainRecommendation`.
  - `test_brain_executive_zero_llm_calls` — mock LLMClient,
    instantiate brain, run executive; assert zero LLM calls (Python
    only).
  - `test_brain_handles_empty_subagent_outputs` — fallback path covered.
- **Single-brain end-to-end smoke** (`tests/test_cortex_brain_smoke.py`):
  - One brain processes one observation, returns a `BrainRecommendation`.
  - Total LLM calls = exactly 3 (WM + Planner + Critic).
  - **Integration smoke gate after Session 11**: a single brain runs
    end-to-end on a real observation. Council still doesn't exist yet.

### Session 12 — Council Executive + phase machine

- **Phase machine tests** (`tests/test_cortex_council.py`):
  - `test_council_runs_5_protocol_steps_in_order` — assert the 5 anti-
    hivemind steps fire in order with stub brains.
  - `test_council_caps_deliberation_rounds_at_2` — synthetic signals
    inviting 3+ rounds force convergence at round 2.
  - `test_council_caps_cross_brain_challenges_at_1` — second
    `request_challenge` is overridden.
  - `test_council_caps_critic_calls_per_brain_at_1` — second
    `call_subagent(brain, "critic")` is overridden.
  - `test_council_preserves_dissent_via_routing_action` —
    `preserve_dissent` tag accumulates in `CouncilDecision`.
  - `test_council_emits_outer_action_terminates_tick` — `emit_outer_action`
    closes the tick mid-round.
  - `test_council_token_budget_exhaustion_forces_emit` — when
    `tick_tokens_used ≥ TICK_BUDGET`, only emit / no_op are allowed.
- **Integration smoke gate after Session 12**: Council runs one tick
  end-to-end with stub brains, produces a valid `OuterAction`.

### Session 13 — Metacognition + Routing + B3 (cortex_fixed_router)

- **Metacognition tests** (`tests/test_cortex_metacognition.py`):
  - All `MetacognitionState` fields computable from
    `BrainRecommendation`s + tick context.
  - `inter_brain_agreement` formula tested against hand-crafted cases.
  - `collapse_suspicion` flags when all 3 brains return identical
    `top_action`.
- **Deterministic router tests** (`tests/test_cortex_routing_policy.py`):
  - Decision table fires the expected `RoutingAction` per
    `(phase, round, agreement, budget)`.
  - Determinism: same `MetacognitionState` → same `RoutingAction`,
    bytewise.
- **B3 baseline tests** (`tests/test_baseline_b3.py`):
  - `B3CortexFixedRouter` runs one full episode on `outbreak_easy`.
  - Token totals are within ±10% of B1's per cortex/CLAUDE.md
    (matched-compute test).
- **Integration smoke gate after Session 13**: B3 runs end-to-end via
  `inference.py --agent b3` (forward-compat with the agent_cls hook
  added in Session 8).

### Cumulative test count

- Session 9: ≈ 8 new tests
- Session 10: ≈ 5 new tests
- Session 11: ≈ 6 new tests + smoke
- Session 12: ≈ 10 new tests + smoke
- Session 13: ≈ 12 new tests + B3 + smoke
- **Total: ≈ 41 new tests** on top of the current 143.

---

## §9 — Pre-approved modeling decisions

Decisions are grouped by layer. Each entry: **decision** / **rationale** /
**alternative considered & why rejected**.

### Subagents (Session 9)

1. **WorldModeler prompt structure: SYS = role + schema; USR = perception + last_reward + recent_action_log_excerpt.** / Mirrors B1's structure for matched-compute defensibility. / Considered including raw `CrisisworldcortexObservation` JSON; rejected because perception already extracted the salient signals — re-including raw obs doubles tokens.

2. **Planner prompt structure: SYS = role + action schema (B1's); USR = perception + WM's `BeliefState` JSON + last_reward.** / Planner needs the action schema to emit valid `OuterActionPayload`. The schema reuse from B1 keeps matched-compute clean. / Considered a fully different action vocabulary; rejected — `OuterActionPayload` is the wire contract.

3. **Critic prompt structure: SYS = critic role; USR = perception + target plan + WM belief.** / Critic emits prose `CriticReport` fields; no action schema needed (saves ~400 tokens vs Planner's prompt). / Considered including all sibling brains' plans; rejected — that's a cross-brain challenge (Phase 2), not the per-brain Critic.

4. **All subagent SYS prompts loaded from `cortex/subagents/prompts/<role>.txt` at module load.** / Decouples prompt iteration from code changes; fixture-friendly. / Considered inline f-strings in code; rejected — multi-paragraph prompts in code are unreadable.

5. **Subagent output validated via Pydantic `TypeAdapter[<role-specific-type>]`.** / Already the pattern in `parse_action` (B1); reusable. / Considered hand-rolled JSON parsing; rejected — Pydantic gives discriminated-union safety free.

6. **Empty `SubagentReport` on parse / call failure: `confidence=0.0, evidence=[]`** for any of the three subagent types (with role-specific other fields zeroed/empty). / Honest "no signal" state; downstream r_proto naturally penalizes. / Considered raising the exception; rejected — would break the per-brain isolation contract. **(D-FR-3 reinforcement)** A single subagent's empty fallback does NOT trigger `parse_failure_marker` — that fires only on full-brain emptiness (Brain Executive sees `top_confidence == 0` from all 3 subagents); see Decision 42.

7. **Subagent caller_id format: `cortex:<brain>:<role>:t<tick>:r<round>:s<step_idx>`.** / Mirrors B2's `b2:t<tick>:p<n>:<role>` pattern. / Considered a flat `cortex:<step_idx>` form; rejected — losing the per-brain breakdown loses critical training analytics.

8. **Subagent retry on parse failure: 1 retry max, then fallback to empty.** / Bounded compute, deterministic outcome. / Considered no retry; rejected — first-attempt parse failures are common with smaller models, retry recovery is cheap.

### Lenses (Session 10)

9. **Three lenses: epidemiology, logistics, governance. Each is a function `lens_for(brain, obs) -> BrainLensedObservation`.** / Matches the 3 brains. / **(Item E resolution)** V2 brains (Communications, Equity) deferred entirely per Decision 56 — no MVP stub lens functions. `lens_for(brain, obs)` raises `KeyError` on `brain ∈ {'communications', 'equity'}`. Rationale: stubs returning the raw obs would silently let a V2-leaked code path "work", masking the boundary; raising is the loud-fail behaviour V2 deferral contracts demand.

10. **Epidemiology derived features: `r_effective_estimate, worst_region_infection, transmission_rate_trend`.** / These are exactly the signals an epi-savvy human would compute from telemetry. / Considered raw telemetry only (no derived features); rejected — forces every WM call to redo the same computations.

11. **Logistics derived features: `total_inventory, hospital_load_max, deployment_feasibility_per_region`.** / Operational salience. / Same rationale.

12. **Governance derived features: `escalation_unlocked_strict, legal_constraints_count, restrictions_active_count`.** / Legal/policy salience. / Same.

13. **Lens does NOT strip the raw `CrisisworldcortexObservation` from the lensed object.** / Subagents may need to look at fields the lens didn't emphasize. / Considered stripping for "true" lens isolation; rejected — over-aggressive, would force lens to anticipate every subagent need.

14. **`derived_features` is `Dict[str, float]` (flat dict).** / Easy to log, easy to train on. / Considered a typed schema per brain; rejected — lens features evolve; flat dict trades type safety for iteration speed.

### Brain Executive (Session 11)

15. **Decision rule: argmax over `CandidatePlan.expected_value × confidence`.** / Reasonable heuristic; matches design §7.2. / Considered a weighted vote among multiple plans; rejected — single brain should commit to one top action and surface alternatives as `minority_actions`.

16. **`top_confidence` = the chosen plan's `confidence` × the WM's `(1 - uncertainty)`.** / Multiplicative — both must be high. / Considered just plan confidence; rejected — high-plan-confidence-with-high-WM-uncertainty is a known failure mode the council should distrust.

17. **`minority_actions` = all `CandidatePlan.expected_outer_action` from this round NOT chosen as top.** / Preserves dissent at brain level too. / Considered top-2 only; rejected — design §7.2 says the Brain Exec carries minority forward; arbitrary truncation loses signal.

18. **Brain Executive runs ONCE per brain at round end; not router-callable.** / Per cortex/CLAUDE.md binding. / N/A — locked.

19. **Reasoning summary: a 1–2 sentence string from the Planner's `action_sketch`.** / Fits the 400-char `BrainRecommendation.reasoning_summary` cap. / Considered an LLM call to produce a summary; rejected — Brain Executive must be Python-only per cortex/CLAUDE.md.

20. **`evidence` field on `BrainRecommendation` = union of all `EvidenceCitation` lists from `BeliefState`, `CandidatePlan`, `CriticReport`.** / Ensures the council sees the brain's full evidence chain. / Considered Critic only; rejected — claims with no upstream evidence get zeroed `r_proto`. **(Session 11 implementation note — M-FR-3)** Implementation reads evidence from `PerceptionReport.evidence` + `BeliefState.evidence` only, since `CandidatePlan` and `CriticReport` schemas (Session 9) carry no `evidence` field. Adding evidence fields to those schemas was rejected as schema-churn risk; the perception+beliefs union captures the actionable evidence chain since plans/critics derive from beliefs. See `cortex/brains/_executive.py:aggregate_brain_outputs`.

21. **Brain identifier strings: `"epidemiology"`, `"logistics"`, `"governance"` (lowercase, full word).** / Readable and grep-friendly. / Considered abbreviations (epi, log, gov); rejected — log-grep collisions.

### Council Executive (Session 12)

22. **Phase initialisation: `Divergence` always.** / Per design §9. / N/A.

23. **Initial `MetacognitionState`: all aggregate fields = 0.0 (or 1.0 for `budget_remaining_frac`).** / Honest pre-deliberation state. / Considered prior-tick carry-over; rejected — Cortex is stateless across ticks (no memory in MVP).

24. **Aggregation rule for the 3 `BrainRecommendation`s: weighted vote on `top_action.kind` first, then on parameters within the winning kind.** / Two-level vote keeps semantically-similar actions together. / Considered exact-match-only; rejected — would force Cortex to flip-flop on minor parameter differences.

25. **Vote weight per brain: `top_confidence × evidence_count`.** / Rewards confident, well-evidenced brains. / Considered uniform weights; rejected — would erase brain-level differences. **(D-FR-2 resolution)** Do NOT multiply by `(1 - uncertainty)` here — Decision 16 already bakes `(1 - uncertainty)` into `top_confidence` via the multiplicative `confidence × (1 - uncertainty)` rule. Adding it again at the council layer would double-count uncertainty and over-penalise the most-uncertain brain. Cross-reference Decision 16 when reviewing this in future sessions.

26. **Tie-breaking: deterministic ordering `epidemiology > logistics > governance`.** / Required for eval determinism. / Considered random; rejected — breaks the eval-mode determinism contract.

27. **Cross-brain challenge selection: when `request_challenge` fires, the *challenger_brain*'s Critic runs against the *target_brain*'s top plan.** / Matches design §10 worked example. / Considered pairwise challenge (both brains' Critics); rejected — exceeds the 1-challenge cap. **(Item B resolution)** Cross-brain Critic USR field includes BOTH the target's `PerceptionReport` AND the challenger's `PerceptionReport` (≈ 200 extra tokens / cross-brain challenge — affordable within `TICK_BUDGET=6000`). Rationale: a logistics Critic challenging an epi plan needs the epi-lens view of the data (otherwise the critique is uninformed) plus its own logistics-lens view (otherwise the challenge has no domain leverage). Single-perception Critic was considered and rejected — would force the Critic to "guess" what the target brain saw.

28. **Phase advancement triggers** (Session 13's deterministic router; Session 15 learns these):
    - Divergence → Challenge: `inter_brain_agreement < 0.4` AND `round 1 complete`.
    - Challenge → Narrowing: challenge resolved OR cap hit.
    - Narrowing → Convergence: top candidate stable across last router step OR `urgency > 0.7` OR `budget_remaining_frac < 0.2`.
    / These thresholds are the deterministic-router defaults; trainable router learns its own. / Other thresholds considered; locked here for Session 13's reproducibility. **(D-FR-1 resolution)** Conservative-only: `< 0.4` is the *single* threshold for `request_challenge` firing. The aggressive variant — also firing on `agreement ∈ [0.4, 0.7] AND round == 1` — was rejected. Reasoning: the challenge cap is 1/tick, so aggressive triggering buys *earlier* challenges, not *more* challenges. Challenging moderate disagreement (the [0.4, 0.7] band) misallocates the cap; high agreement is consensus and must not be challenged at all. Aligns with the anti-hivemind story — challenge real dissent, not moderate disagreement.

29. **Forced convergence on round 2 cap: emit current top-ranked action; if no candidate, emit `parse_failure_marker()`.** / Matches B2's pattern. / Considered emitting `NoOp()` directly; rejected — `parse_failure_marker` correctly fires the r_policy=0 penalty.

30. **`CouncilDecision.phase_trace`: list of strings, one per phase entered, e.g. `["Divergence", "Challenge", "Narrowing", "Convergence"]`.** / Cheap to log; useful for debugging. / Considered timestamped events; rejected — too verbose for trajectory storage.

31. **`CouncilDecision.rationale`: a 1–3 sentence string explaining the chosen action, generated deterministically from the winning brain's `reasoning_summary`.** / No extra LLM cost. / Considered an LLM-generated summary; rejected — would add a per-tick LLM call to the council layer.

### Metacognition (Session 13)

32. **`inter_brain_agreement` formula: 1.0 if all 3 `top_action.kind` match; 0.5 if 2/3 match; 0.0 otherwise.** / Three buckets capture the meaningful states. / Considered continuous parameter-overlap score; rejected — too noisy for the small router.

33. **`average_confidence` formula: `mean(brain_rec.top_confidence for brain_rec in [...])`** across the 3 brains. / Standard. / N/A.

34. **`average_evidence_support` formula: `mean(len(brain_rec.evidence) / max(1, claims_count(brain_rec)))` across the 3 brains** where `claims_count = len(reasoning_summary.split('.')) - 1`. / Approximate but computable from the recommendation alone. / Considered LLM-rated evidence support; rejected — adds LLM call.

35. **`collapse_suspicion`: 1.0 if all 3 brains' `top_action` is bytewise-equal AND all 3 evidence lists are length 0; else 0.0.** / Catches the "all said NoOp with no reasoning" failure. / Considered a graded score; rejected — this is the binary signal eval cares about.

36. **`urgency`: `1.0 - ticks_remaining / max_ticks` clipped + `worst_region_infection_estimate × 0.5`, clamped to [0, 1].** / Both time pressure and crisis severity. / Considered ticks-only; rejected — task-difficulty differences vanish. **(D-FR-4 resolution)** Multiplier confirmed at `0.5`. The alternative — `× 1.0` — was rejected: a 1.0 weight would force premature convergence on `outbreak_hard` precisely when anti-hivemind reasoning matters most. Hard tasks need *more* deliberation, not faster convergence. The 0.5 weight lets infection severity nudge urgency without dominating it.

37. **`novelty_yield_last_round`: only computed in round 2; round 1 always returns 0.0.** / Eval-only signal per design §7.4.3 line 404. / N/A.

### Routing policy (Session 13 deterministic, Session 15 trainable)

38. **Session 13 deterministic router decision table** (binding for B3 baseline):
    - Round 1, Divergence, no recommendations yet: `call_subagent(epi, world_modeler)`, then `(epi, planner)`, then `(epi, critic)`, then logistics, then governance — fixed brain order.
    - End of round 1, agreement < 0.4: `switch_phase(Challenge)` → `request_challenge(challenger, target)` where **`challenger = brain with min(top_confidence)`** and **`target = brain with max(top_confidence)`**, ties broken by Decision 26's deterministic ordering (`epidemiology > logistics > governance`).
    - **All-equal-confidences edge case**: when `min(top_confidence) == max(top_confidence)` across all three brains, do NOT fire `request_challenge` at all. Skip the Challenge phase and `switch_phase(Narrowing)` directly. Cross-brain challenge requires productive asymmetry; identical confidences provide none — Decision-26 tie-break would otherwise collapse to `challenger == target == epidemiology`, violating the cross-brain contract. The 1-challenge cap is preserved (unspent), and the council still has the dissent-preservation channel for surfacing minority recommendations.
    - End of round 2 OR agreement ≥ 0.7: `switch_phase(Convergence)` → `emit_outer_action(council_top)`.
    - Budget < 20% remaining: `emit_outer_action` immediately.
    / Reproduces design §10 worked example. / **(Decision-38 inconsistency fix)** The earlier draft hardcoded `challenger=logistics, target=epidemiology` without justification. The dynamic pair lets the *most-uncertain* brain push back on the *most-confident*, which is where anti-hivemind correction has highest expected value: a low-confidence brain challenging a high-confidence one is exactly the configuration where dissent could productively flip the council's decision. Hardcoded pair was rejected because (a) it presupposes which domain is "always right to be challenged", which the design doc does not assert, and (b) it defeats the point of the metacognition signal feeding the router. The all-equal-confidences edge case is handled by short-circuiting to Narrowing rather than firing a same-brain self-challenge.

39. **Session 15 trainable router: Option B (small MLP head over 24-dim featurized state, discrete output over top-50 most-common (kind, brain, subagent) tuples).** / Per design §22; Colab-compatible. / Option A (LoRA) is the stretch.

40. **Featurization: `MetacognitionState` → `np.ndarray[float, (24,)]`.** / Fixed dim across all phases. / Considered phase-conditional feature sets; rejected — breaks the trainable-router's argmax over a fixed action space.

41. **Routing policy returns the action with highest log-prob (eval) or sampled (training).** / Standard. / N/A.

### Failure / fallback (cross-cutting)

42. **`parse_failure_marker()` reuse from `baselines.flat_agent`** when the council has no candidate at budget exhaustion. / Cross-baseline rejection contract; already public API. / N/A.

43. **All `[WARN]` / `[ERROR]` lines go to stderr with the `cortex:` prefix.** / Consistent with B1/B2 pattern. / N/A.

44. **Trajectory storage: in-memory `List[RouterStep]` per episode; trainer persists at episode end.** / Bounded memory (worst-case 19 calls/tick × 12 ticks = 228 router steps). / Considered streaming to disk; rejected — adds I/O without need.

### Testing (cross-cutting)

45. **All Cortex tests use mock `LLMClient`** with scripted responses; no real-network calls in unit tests. / Same pattern as Sessions 7a/8 stub LLMs. / N/A.

46. **Integration smoke (Sessions 11 / 12 / 13) uses in-process env adapter** (same as B1/B2 tests). / Production B3 hits HTTP per baselines/CLAUDE.md; smoke can short-circuit. / N/A.

47. **`tests/test_cortex_protocol_invariants.py`** (Session 12): asserts post-`Council.step` that the 5 anti-hivemind steps fired in order, OR a short-circuit reason is logged. / Per cortex/CLAUDE.md "Testing requirements". / N/A.

48. **`tests/test_cortex_no_llm_call_in_python_layers.py`** (Session 11/12): mock `LLMClient`, assert zero invocations during Perception or Brain Executive runs. / Per cortex/CLAUDE.md binding. / N/A.

### Tooling (cross-cutting)

49. **All caller_ids are strings (no enum types).** / Matches B1/B2 pattern; pickle-safe. / N/A.

50. **Cortex never imports from `server/*` or `baselines/*`.** / cortex/CLAUDE.md binding; enforced by `tests/test_import_graph.py`. / N/A.

51. **B3's class name: `B3CortexFixedRouter`.** / Mirrors `B1FlatAgent`, `B2MatchedComputeAgent`. / N/A.

52. **B3's filename: `baselines/cortex_fixed_router.py`.** / Per `baselines/CLAUDE.md` line 9. / N/A.

53. **B3 composes `Council(routing_policy=DeterministicRouter())` directly; doesn't subclass.** / Same composition pattern as B1/B2. / N/A.

54. **Council exposes `step_callback` parameter matching B1/B2's signature.** / inference.py and harnesses can stream `B1StepEvent`s for B3 too. / N/A.

55. **`B1StepEvent.action` for B3 = the council's emitted `OuterActionPayload`.** / Same shape as B1/B2. / N/A.

56. **Anonymized comparison (anti-hivemind step 4′ from design §8.1) deferred to V2.** / Already locked in cortex/CLAUDE.md. / N/A.

57. **`recurse_in` (RLM operator) deferred to V2.** / Already locked. / N/A.

58. **Memory subagent (long-term episodic memory) deferred to V2 with stub return.** / Per design §7.2. / N/A.

59. **Communications and Equity brains deferred to V2.** / Per design §7.1. / N/A.

60. **All MetacognitionState fields use `float ∈ [0, 1]` except `tick`, `round`, `preserved_dissent_count`, `challenge_used_this_tick`.** / Already locked in `cortex/schemas.py`. / N/A.

### Phase A review-pass additions (Sessions 9–13 binding)

These decisions land during the Phase A review pass (April 2026); each
is locked to the same standard as Decisions 1–60.

61. **Round-2 entry mechanism** (Item C): the router enters round 2 ONLY by emitting an explicit `switch_phase(Divergence)` routing action. Council Executive forbids implicit round increment. / Every round boundary becomes a first-class policy decision; the Session-15 trainable router learns "when to spend a second round" as an explicit action choice rather than an emergent side-effect — cleaner gradient signal. / Considered implicit round-bump on Convergence-without-emit; rejected — would couple round increment to phase state and obscure the router's training signal. (Cross-reference §3 transition rules.)

62. **Round-2 `prior_belief` encoding when round 1 produced nothing** (Item D): when round 1 produced no useful `BeliefState` (parse failure, empty subagent fallback, or LLM-call exception), round-2 `SubagentInput.prior_belief` is an EMPTY `BeliefState(brain=<X>, latent_estimates={}, hypotheses=[], uncertainty=1.0, reducible_by_more_thought=False, evidence=[])`, NOT `None`. / Different prompt signals: `None` tells the WorldModeler "round 1 has not happened, no history to revise"; an empty `BeliefState` tells it "round 1 happened, produced nothing — start clean but acknowledge the failed pass". Conflating the two would mask the failure mode in the trajectory log. / Considered using `None` for both; rejected — collapses two distinct epistemic states into one.

63. **`PerceptionReport.salient_signals` cap** (OQ-2 resolution): `salient_signals` is `List[str]` with **at most 5 entries** per report. Pydantic validator enforces. / Cap prevents the LLM (in V2 lens-extension experiments) from emitting a paragraph as a "signal"; tests assert content not schema. / Considered a per-brain enum; rejected — over-rigid for early MVP iteration where lens features are still being tuned.

64. **Training-rollout temperature** (OQ-1 resolution): deferred to Session 15. Phase A does not pin a numeric value. `cortex.llm_client.LLMClient.chat(..., temperature: float = 0.0)` already exposes the parameter; Session 15 trainer reads its rollout temperature from the GRPO config and passes it through. / Right session for this decision is Session 15, where the trainer will run early experiments and pick a value based on observed exploration. / Considered pinning `0.7` (common GRPO default); rejected — premature; locks a hyperparameter before any training data exists.

65. **`RouterStep.policy_kind` GRPO advantage filter** (OQ-3 resolution): when the Session-15 trainable router crashes mid-tick and Council falls back to the deterministic router (per §7 metacognition layer), the deterministic-router steps that close the tick are tagged `policy_kind="deterministic_fallback"`. GRPO advantage computation filters to `policy_kind == "trainable"` ONLY — fallback steps are off-policy with respect to the gradient. B3 baseline runs are unaffected: every B3 RouterStep gets the default `policy_kind="trainable"`, but B3 trajectories are not training data so the field is inert for B3. / Cleanest split: keep all router steps on the trajectory (so trainer can still measure failure rate, fallback-tick reward, etc.) but exclude fallback steps from the policy gradient. / Considered dropping fallback steps entirely from the trajectory; rejected — loses observability into how often the trainable router crashes and what the deterministic fallback does instead. (Cross-reference §2 A3 schema and §7 metacognition layer.)

### Decisions resolved during Phase A review pass (April 2026)

All four D-FR items below were resolved in the review pass and folded
into the relevant decision entries above. Listed here for trace-
ability; the binding text now lives on the referenced decisions.

- **D-FR-1 → resolved.** Conservative threshold only (`inter_brain_agreement < 0.4`). Aggressive variant rejected. → Decision 28 updated.
- **D-FR-2 → resolved.** Vote weight stays `top_confidence × evidence_count`; do NOT add `(1 - uncertainty)` factor (already in Decision 16's `top_confidence`). → Decision 25 updated.
- **D-FR-3 → resolved.** `parse_failure_marker` fires only on full-brain emptiness (status quo of Decisions 6 + 42). Single-subagent failures use 1-retry + empty-report fallback. → Decision 6 updated.
- **D-FR-4 → resolved.** `urgency` keeps `worst_region_infection × 0.5`. The 1.0 weight was rejected — would force premature convergence on `outbreak_hard`. → Decision 36 updated.

### Open questions resolved during Phase A review pass

- **OQ-1 → resolved.** Training-rollout temperature deferred to Session 15. → Decision 64 added.
- **OQ-2 → resolved.** `salient_signals` is free-form `List[str]` capped at 5. → Decision 63 added.
- **OQ-3 → resolved.** Trainable-router fallback steps logged with `policy_kind` field on `RouterStep`; GRPO filter excludes fallback. → §2 A3 + Decision 65 added.

### Additional pins resolved during Phase A review pass

- **Item A → resolved.** Backward re-entry threshold pinned at `preserved_dissent_count >= 2`. → §3 transition rules updated.
- **Item B → resolved.** Cross-brain Critic USR includes BOTH target's and challenger's perception (~200 extra tokens / challenge). → Decision 27 updated.
- **Item C → resolved.** Round-2 entry: only via explicit `switch_phase(Divergence)` from router. → §3 transition rules + Decision 61 added.
- **Item D → resolved.** Round-2 `prior_belief` when round 1 failed: empty `BeliefState`, NOT `None`. → Decision 62 added.
- **Item E → resolved.** No V2-brain stub lens functions; `lens_for(brain, obs)` raises `KeyError` on V2 brain ids. → Decision 9 updated.
- **Item F → resolved.** Phase-to-protocol mapping pinned (steps 1, 2, 3, 5 → MVP phases; step 4 → V2-deferred). → §3 phase-to-protocol mapping subsection added.

### Inconsistency resolved during Phase A review pass

- **Decision 38 inconsistency → resolved.** Hardcoded `request_challenge(challenger=logistics, target=epidemiology)` replaced with dynamic pair: `challenger = brain with min(top_confidence)`, `target = brain with max(top_confidence)`, ties broken by Decision 26's deterministic ordering. → Decision 38 updated.

---

## §10 — Implementation sequencing and dependencies

### DAG (read top-to-bottom, branches indicate parallelisable work)

```
Session 9 (Subagents)
    │
    ├─► WorldModeler / Planner / Critic schemas + prompts + tests
    │
Session 10 (Lenses)
    │  (depends on Session 9 only for SubagentInput.perception field shape)
    │
    ├─► Per-brain lens functions + BrainLensedObservation tests
    │
Session 11 (Brains)
    │  (depends on Sessions 9 + 10)
    │
    ├─► Brain Executive Python aggregation
    ├─► Single-brain end-to-end test
    │  ── INTEGRATION SMOKE GATE 1 (after Session 11) ──
    │
Session 12 (Council Executive + phase machine)
    │  (depends on Session 11)
    │
    ├─► Phase machine (4 phases)
    ├─► Hard-cap counters + override logic
    ├─► Preserved-dissent recording
    ├─► CouncilDecision aggregation
    │  ── INTEGRATION SMOKE GATE 2 (after Session 12) ──
    │
Session 13 (Metacognition + Routing + B3)
    │  (depends on Session 12)
    │
    ├─► Metacognition signal computation
    ├─► Deterministic RoutingPolicy (decision table)
    ├─► B3CortexFixedRouter baseline
    │  ── INTEGRATION SMOKE GATE 3 (after Session 13) ──
    │
Session 15 (out of Phase A scope) (Trainable router)
    │
    ├─► Featurization → MLP head
    ├─► GRPO loop on stored trajectories
    ── (drop-in replacement for Session 13's router via the locked Protocol) ──
```

### Per-session inputs / outputs

| Session | Inputs (what must exist) | Outputs (what unlocks the next session) |
|---|---|---|
| 9 | `cortex/schemas.py`, `cortex/llm_client.py` (already in repo) | `cortex/subagents/{world_modeler,planner,critic}.py` files; `tests/test_cortex_subagents.py` green |
| 10 | Session 9 outputs; `CrisisworldcortexObservation` schema (locked) | `cortex/lenses.py` with `lens_for(brain, obs) -> BrainLensedObservation`; lens tests green |
| 11 | Sessions 9 + 10 | `cortex/brains/{epidemiology,logistics,governance}.py` files; brain Python aggregation in `cortex/brains/executive.py`; single-brain smoke green |
| 12 | Session 11 | `cortex/council.py` with `Council.step(observation) -> CouncilDecision`; phase machine tests green; Council smoke green |
| 13 | Session 12 | `cortex/metacognition.py` (signal computation); `cortex/routing_policy.py` (DeterministicRouter only — trainable router is Session 15); `baselines/cortex_fixed_router.py` (B3); B3 smoke green |

### Integration smoke gates

- **Gate 1 (Session 11 end):** a single brain takes a real observation
  on `outbreak_easy`, makes 3 LLM calls (mocked), returns a valid
  `BrainRecommendation`. No council yet. Pass = unblock Session 12.
- **Gate 2 (Session 12 end):** Council instantiated with 3 brains and
  the deterministic-router stub (placeholder until Session 13). Runs
  one tick, emits one `CouncilDecision`, returns a valid `OuterAction`.
  Pass = unblock Session 13.
- **Gate 3 (Session 13 end):** B3CortexFixedRouter runs a full episode
  on `outbreak_easy` via in-process env (smoke) and via Docker (manual
  smoke per Session 7c pattern). LLM-call count per tick is in [9, 19].
  Token total per episode is within ±10% of B1's. Pass = ship Phase A.

### Dependency on already-shipped infrastructure

- `cortex.llm_client.LLMClient` (Session 7a): caller-id token tracking.
- `baselines.flat_agent.parse_failure_marker` (Session 8): rejection
  marker reuse.
- `B1StepEvent / StepCallback` (Session 8): callback contract.
- `tests/test_import_graph.py`: structural enforcement; will start
  flagging cortex/* if anything imports server/*.
- `inference.py` (Session 7b/8): `agent_cls` parameter is the forward-
  compat hook for B3 + future Cortex-with-trainable-router.

---

## Final report

### Word count

≈ 8,275 words after the Phase A review pass — about 275 over the
original 8,000 soft ceiling. (Initial draft: ≈ 6,529 words; review
pass added ≈ 1,750 words of resolution prose, including per-resolution
"why rejected" rationale to keep §9's decision-format consistent.)
The overage is accepted as the cost of folding all 13 resolutions
inline rather than as a separate addendum file — single source of
truth for Sessions 9–13.

### Sections completed (10/10)

§1 Data flow / §2 Schemas / §3 Phase machine (now includes phase-to-
protocol mapping) / §4 Hard caps + dissent / §5 Token budget /
§6 Routing policy / §7 Failure modes / §8 Test strategy / §9 Pre-
approved decisions (65 entries — 60 initial + 5 review-pass additions) /
§10 Sequencing.

### Decisions auto-resolved (rationales recorded inline in §9)

65 modeling decisions, grouped by layer:
- 8 subagent decisions
- 6 lens decisions
- 7 brain executive decisions
- 10 council executive decisions
- 6 metacognition decisions
- 4 routing policy decisions
- 3 failure / fallback decisions
- 4 testing decisions
- 12 tooling / V2-deferral decisions
- **5 review-pass additions (61–65)**: round-2 entry mechanism,
  round-2 `prior_belief` encoding, `salient_signals` cap, training-
  rollout temperature deferral, `RouterStep.policy_kind` GRPO filter.

### Phase A review pass — resolutions (April 2026)

All 4 D-FR items, 3 OQ items, 6 additional pins (Items A–F), and 1
Decision-38 inconsistency resolved. Each is folded into the relevant
inline decision; the §9 "resolved during Phase A review pass"
subsection lists the cross-references for traceability.

| ID | Resolution (1-line) | Lands in |
|---|---|---|
| D-FR-1 | Conservative-only `< 0.4`; aggressive variant rejected. | Decision 28 |
| D-FR-2 | Vote weight stays `top_confidence × evidence_count`; no extra `(1 - uncertainty)` factor (Decision 16 already bakes it in). | Decision 25 |
| D-FR-3 | `parse_failure_marker` fires only on full-brain emptiness; single-subagent failures use empty-report fallback. | Decision 6 |
| D-FR-4 | `urgency` keeps `worst_region_infection × 0.5`; 1.0 weight rejected. | Decision 36 |
| OQ-1 | Training-rollout temperature deferred to Session 15. | Decision 64 (new) |
| OQ-2 | `salient_signals` is free-form `List[str]` capped at 5. | Decision 63 (new) |
| OQ-3 | `policy_kind` field on `RouterStep`; GRPO filter excludes fallback. | §2 A3 + Decision 65 (new) |
| Item A | Backward re-entry pinned at `preserved_dissent_count >= 2`. | §3 transition rules |
| Item B | Cross-brain Critic USR includes target + challenger perception (~200 extra tokens). | Decision 27 |
| Item C | Round-2 entry: only via explicit `switch_phase(Divergence)`. | §3 + Decision 61 (new) |
| Item D | Round-2 `prior_belief` when round 1 failed: empty `BeliefState`, NOT `None`. | Decision 62 (new) |
| Item E | No V2-brain stub lens; `lens_for` raises `KeyError` on V2 brain ids. | Decision 9 |
| Item F | Phase-to-protocol mapping pinned (steps 1, 2, 3, 5 → MVP phases; 4 → V2-deferred). | §3 phase-to-protocol mapping subsection |
| Decision 38 inconsistency | Hardcoded `(challenger=logistics, target=epidemiology)` → dynamic `(min top_confidence, max top_confidence)`, ties via Decision 26. | Decision 38 |

### Standing-by status

**Decisions locked. Session 9 unblocked.** Phase A is complete; no
remaining flagged items, no remaining open questions. Sessions 9–13
implement against this document. Future revisions to Phase A
contracts require explicit ✅ in a new review pass.

### What is NOT in this document

- No Python code (per the no-code constraint).
- No Session 14+ details (training reward composition, eval harness,
  HF Spaces deploy). Phase A intentionally bounds at Session 13.