# TITAN-MoE — project instructions for Claude Code (WP33 UQO)

Topology-Aware Intelligent Expert Orchestration for Distributed MoE Inference on Apple Silicon.
Author: Simon-Pierre Boucher (UQO). Agent: Claude Code. Language of code, docs and paper: English.
Full mandate: `docs/MANDATE.md`. Research log: `research/LOG.md`. Decisions: `research/DECISIONS.md`.

## Non-negotiable scientific integrity
- Never invent measurements, sources, screenshots, benchmark results, hardware details or novelty claims.
- Distinguish hypotheses (H1–H5 in `docs/MANDATE.md`) from findings. A claim enters the paper only with a raw log under `benchmarks/raw/`.
- Never claim a test passed without its raw output (`tests/` run logs go to `benchmarks/raw/tests/`).
- If hardware, permissions or models are unavailable: record the blocker in `research/LOG.md`, mark the experiment PENDING, keep going on independent work.
- Preserve raw data and the exact command (every benchmark writes a JSON record with command line, git commit, environment hash, seed and timestamps).
- Authorization is required before: remote execution on nodes not yet listed in `artifacts/environment.json` as authorized, downloads > 20 GB, paid APIs, security changes (firewall, SSH, RDMA enable), destructive actions.

## Layout
`titan/` scheduler, registry, cache · `metal/` Metal kernels · `transport/` authenticated node transport · `adapters/` MoE formats ·
`tests/` · `benchmarks/{configs,scripts,raw,processed}` · `research/` (LOG, DECISIONS, RELATED_WORK, prior_art.csv, protocol.md) ·
`figures/` · `paper/` (UQO template; `cd paper && make`) · `artifacts/` (environment.json, manifest.json) · `scripts/` (setup, reproduce) ·
`third_party/` (shallow clones of colibri / mlx / mlx-lm / llama.cpp, git-ignored; hashes in `research/prior_art.csv`).

## Conventions
- Python 3.12 venv `.venv` (uv); MLX pinned in `requirements-lock.txt`. Run with `.venv/bin/python`.
- Models live in the Hugging Face cache (`~/.cache/huggingface`), never in the repo. Revisions are pinned in `benchmarks/configs/models.yaml`.
- Raw logs are immutable: write-once JSONL/JSON under `benchmarks/raw/<gate>/<experiment>/`; processed tables under `benchmarks/processed/`.
- Every figure/table in the paper is generated by `scripts/make_figures.py` / `scripts/make_tables.py` from `benchmarks/raw/`.
- Cluster nodes: short SSH aliases; LAN only; never store private keys on nodes; sudo via `echo '<pw>' | sudo -S` only when a decision record authorizes it.
- Never commit weights, credentials, or private host inventories (`artifacts/private/` is ignored).
- Gates A–G are sequential; update LOG, DECISIONS, README and test evidence after each gate; incremental commits; no push without authorization.