Audit LoRA projection coverage across model families

.gitignore

@@ -22,6 +22,7 @@ local/*
 # Environments
 .env
 .venv
+.venv-sglang/
 env/
 venv/
 ENV/

.pre-commit-config.yaml

@@ -14,6 +14,9 @@ repos:
       - id: check-toml
       - id: check-ast
       - id: check-added-large-files
+        # The semantic audit ledger intentionally retains evidence for every
+        # reviewed scope. Keep the size guard for all other additions.
+        exclude: ^test_audit_decisions\.json$
       - id: check-merge-conflict
       - id: check-shebang-scripts-are-executable
       - id: detect-private-key
@@ -37,3 +40,10 @@ repos:
         args: ["--config", ".codespellrc"]
         additional_dependencies:
           - tomli
+  - repo: local
+    hooks:
+      - id: check-public-tree
+        name: check public tree for private references
+        entry: python scripts/check_public_tree.py
+        language: system
+        pass_filenames: false

CONTRIBUTING.md

@@ -47,6 +47,7 @@ The hooks include:
 - **ruff-format** — code formatting (line length 120)
 - **codespell** — catches typos
 - **trailing-whitespace / end-of-file-fixer** — file hygiene
+- **check-public-tree** — rejects private paths, cluster references, and internal identifiers
 
 CI runs the same hooks, so if pre-commit passes locally, CI will too.
 
@@ -56,12 +57,18 @@ Additional guidelines:
 
 ## Testing
 
+Test additions, consolidation, and removal follow the evidence-based process in [TEST_TRIAGE.md](TEST_TRIAGE.md).
+
 ```bash
-# Run unit tests
-pytest tests/
+# Create the repository-local Python 3.12 test environment from uv.lock
+uv venv .venv --python 3.12
+UV_PROJECT_ENVIRONMENT=.venv uv sync --group test --no-install-project
+
+# Run unit tests against this checkout rather than an ambient xorl install
+PYTHONPATH="$PWD/src" .venv/bin/python -m pytest tests/
 
 # Run a specific test file
-pytest tests/server/api_server/test_checkpoint_paths.py -v
+PYTHONPATH="$PWD/src" .venv/bin/python -m pytest tests/server/api_server/test_checkpoint_paths.py -v
 ```
 
 Tests must pass locally before requesting review.

README.md

@@ -76,14 +76,26 @@ The repo includes two git submodules under `submodules/` (needed for server / on
 - **[xorl-client](https://github.com/togethercomputer/xorl-client)** — Lightweight Python SDK (no PyTorch dependency) for driving the xorl training server. Provides `ServiceClient`, `TrainingClient`, `SamplingClient`, and `RestClient` with async-first `APIFuture` semantics, automatic request ordering, and Tinker API compatibility.
 - **[xorl-sglang](https://github.com/togethercomputer/xorl-sglang)** — XoRL's fork of [SGLang](https://github.com/sgl-project/sglang) with NCCL-based weight sync endpoints, MoE routing data export (R3), and numerical alignment flags for online RL.
 
-Install individually:
+Install the client in the default environment. Keep SGLang in its own
+Torch-2.11 environment; its compiled kernel wheel is not ABI-compatible with
+the default Torch-2.12 profile:
 
 ```bash
 pip install -e submodules/xorl-client
-pip install -e "submodules/xorl-sglang/python[all]"
+uv venv .venv-sglang --python 3.12
+uv pip install --python .venv-sglang/bin/python -e submodules/xorl-sglang/python
+uv pip install --python .venv-sglang/bin/python \
+  torchdata==0.11.0 nvidia-cutlass-dsl==4.5.2 quack-kernels==0.5.0
+uv pip install --python .venv-sglang/bin/python --no-deps -e .
+uv pip install --python .venv-sglang/bin/python pytest
+PYTHONPATH=src:submodules/xorl-sglang/python XORL_REQUIRE_SGL_KERNEL=1 \
+  .venv-sglang/bin/python -m pytest -q tests/ops/test_sgl_kernel_smoke.py
 ```
 
-Or use the bundled `pyproject.sglang.toml` which pins PyTorch to 2.9.1 (required by sglang) and installs everything together:
+The bundled `pyproject.sglang.toml` provides the same combined profile for uv.
+It also overrides SGLang's newer Quack/CUTLASS metadata with the versions used
+by XoRL's trainer source; the exact SGLang kernel smoke above validates that
+boundary.
 
 **uv:**
 ```bash
@@ -92,15 +104,7 @@ uv sync
 source .venv/bin/activate
 ```
 
-**conda:**
-```bash
-conda create -n xorl-sglang python=3.12
-conda activate xorl-sglang
-cp pyproject.sglang.toml pyproject.toml
-pip install -e .
-```
-
-> **Note:** The default `pyproject.toml` uses PyTorch 2.10.0. sglang requires PyTorch 2.9.1, so the two cannot coexist in the same environment unless you use `pyproject.sglang.toml`.
+> **Note:** The default `pyproject.toml` uses Torch 2.12.1. Pinned SGLang requires Torch 2.11.0; do not install `sglang-kernel` into the default environment.
 
 See the [installation guide](https://togethercomputer.github.io/xorl/getting-started/installation/) for full setup including optional dependencies (DeepEP, Flash Attention).