docs/governance.md

Governance — classroom / boardroom / dojo

A clean-room reimplementation (from the behaviour of github.com/openmindx/openmind — Boardroom multi-model consensus + Dojo head-to-head evaluation) of the decision layer that governs training. Lives in mindxtrain/governance/; pure stdlib + pydantic, base-install importable.

The model

• Classroom (governance/classroom.py) — where an actor (model) trains. An actor graduates when its persona imprint took: graduate(imprint_report, min_delta=…) returns a Graduation (the motion the boardroom convenes on). Ties the governance layer to mindxtrain.eval.imprint.
• Boardroom (governance/boardroom.py) — a panel of any number of role-based members (advocate, critic, analyst, devil's advocate, expert, generalist). convene(motion, ballot) tallies votes → approved / rejected / disputed. The boardroom governs the classroom: it decides about training given a graduation. Preset boards: classic_triad, devils_court, full_board, peer_review.
• Dojo (governance/dojo.py) — the boardroom's dispute-settlement extension. When a boardroom is disputed (a tie or no quorum), a dojo settles it. A dojo panel is always an odd prime (≥ 3) — an odd number of decisive judges cannot tie, so the dispute always resolves. Dojo.sized(n) rounds a requested size to the nearest valid prime; settle(motion, ballot) returns a final DojoVerdict. 2 is prime but even (can tie), so it is excluded.

Flow

classroom: train actor → measure imprint → graduate(report) ─► Graduation.motion
                                                                      │
boardroom: convene(motion, ballot) ─► approved / rejected / disputed │
                                                  │ disputed         │
dojo (prime panel): settle_dispute(decision, dojo, ballot) ─► DojoVerdict (no tie)

Members vote via an explicit {id: vote} map or a callable (member, motion) -> vote, so the whole layer is testable with no LLM and can later be backed by real models (boardroom-of-LLMs, dojo head-to-head) — clean-room, never vendoring openmind's TypeScript.

Why prime

A boardroom can be any size because deliberation tolerates abstention and "no decision" (escalate). A dojo must settle — so its panel is an odd prime: approvals + rejections is odd, the majority is strict, and the verdict is final. See governance/primes.py (is_prime, next_prime, nearest_prime) and dojo.prime_dojo_size.

Model-backed deliberation

governance/panel.py backs members + judges with real models (any OpenAI-compatible backend — the same ollama / vLLM the operator serves). deliberate(member, motion) prompts a member from its role stance and parses a VERDICT: APPROVE|REJECT|ABSTAIN; model_ballot() / model_judge_ballot() return ballots you pass straight to Boardroom.convene / Dojo.settle. Lazy + best-effort: a model that errors or returns no parseable verdict abstains (boardroom) or is recorded as reject (dojo). The base URL resolves from MINDXTRAIN_OPENAI_BASE_URL / MINDXTRAIN_VLLM_BASE_URL / MINDXTRAIN_OLLAMA_BASE_URL.

Coach surface

The Boardroom card (after the receipt card) convenes a board on a promotion motion and, if disputed, settles it in a prime dojo:

• GET /coach/api/boardroom/presets — named boards → roles.
• POST /coach/api/boardroom/convene — {motion, members:[{id,role,model}], quorum, votes?, use_models?, base_url?}. Tally supplied votes, or use_models: true to have each member's model deliberate. Model calls run in a worker thread (asyncio.to_thread) so the operator event loop never blocks on inference. Returns the decision + per-member deliberations.
• POST /coach/api/dojo/settle — {motion, size, model?, votes?, use_models?, base_url?}. Sizes the panel to the nearest odd prime and settles.

Tests

• tests/test_governance.py — primes, any-N boardroom (majority / tie / no-quorum), prime-only dojo (rejects non-prime panels, settles without tie), end-to-end classroom → disputed → dojo.
• tests/test_governance_panel.py — verdict parsing, role stances, model-backed ballots driving a boardroom + dojo over a mocked chat backend, graceful backend-error handling.
• tests/test_coach_governance_api.py — convene (votes + model mode), dojo settle (prime sizing), 422 paths, and the Coach card/JS presence.