# 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.