1# TITAN-MoE — project instructions for Claude Code (WP33 UQO)23Topology-Aware Intelligent Expert Orchestration for Distributed MoE Inference on Apple Silicon.4Author: Simon-Pierre Boucher (UQO). Agent: Claude Code. Language of code, docs and paper: English.5Full mandate: `docs/MANDATE.md`. Research log: `research/LOG.md`. Decisions: `research/DECISIONS.md`.67## Non-negotiable scientific integrity8- Never invent measurements, sources, screenshots, benchmark results, hardware details or novelty claims.9- Distinguish hypotheses (H1–H5 in `docs/MANDATE.md`) from findings. A claim enters the paper only with a raw log under `benchmarks/raw/`.10- Never claim a test passed without its raw output (`tests/` run logs go to `benchmarks/raw/tests/`).11- If hardware, permissions or models are unavailable: record the blocker in `research/LOG.md`, mark the experiment PENDING, keep going on independent work.12- Preserve raw data and the exact command (every benchmark writes a JSON record with command line, git commit, environment hash, seed and timestamps).13- 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.1415## Layout16`titan/` scheduler, registry, cache · `metal/` Metal kernels · `transport/` authenticated node transport · `adapters/` MoE formats ·17`tests/` · `benchmarks/{configs,scripts,raw,processed}` · `research/` (LOG, DECISIONS, RELATED_WORK, prior_art.csv, protocol.md) ·18`figures/` · `paper/` (UQO template; `cd paper && make`) · `artifacts/` (environment.json, manifest.json) · `scripts/` (setup, reproduce) ·19`third_party/` (shallow clones of colibri / mlx / mlx-lm / llama.cpp, git-ignored; hashes in `research/prior_art.csv`).2021## Conventions22- Python 3.12 venv `.venv` (uv); MLX pinned in `requirements-lock.txt`. Run with `.venv/bin/python`.23- Models live in the Hugging Face cache (`~/.cache/huggingface`), never in the repo. Revisions are pinned in `benchmarks/configs/models.yaml`.24- Raw logs are immutable: write-once JSONL/JSON under `benchmarks/raw/<gate>/<experiment>/`; processed tables under `benchmarks/processed/`.25- Every figure/table in the paper is generated by `scripts/make_figures.py` / `scripts/make_tables.py` from `benchmarks/raw/`.26- 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.27- Never commit weights, credentials, or private host inventories (`artifacts/private/` is ignored).28- Gates A–G are sequential; update LOG, DECISIONS, README and test evidence after each gate; incremental commits; no push without authorization.29